packages/core/src/lib/components/vertical-line.ts

This is the source snapshot used to build these API details. View this revision on GitHub.
1 import { definePrimitive } from '../define-primitive.js';
2 import type {
3   PibblEventFocusOptions,
4   PibblEventHandlers,
5   PibblEventParticipationOptions,
6 } from '../events/types.js';
7 import {
8   PixelGridAlignment,
9   RenderingContext2D,
10   SystemStyle,
11 } from '../types.js';
12 import type { PibblPhysics2DPropExtension } from '../types.js';
13 import { adjustForPixelGrid } from '../util/pixel-grid-adjustments.js';
14 import {
15   resolveLocalOffset,
16   resolveRequiredLength,
17   stripLayoutParticipation,
18 } from '../style/resolve-built-in.js';
19 import { registerOpaqueStyleProperties } from '../style/resolve-dispatch.js';
20 import type {
21   BoxStyle,
22   LayoutItemStyle,
23   Length,
24   ResolvedDrawingStyle,
25 } from '../style/types.js';
26 import { renderLine, type LineStyle } from './line.js';
27 
28 /**
29  * Authored inputs for VerticalLine, including the declared data and presentation options.
30  *
31  * @see {@link PibblEventHandlers}
32  * @see {@link PibblEventParticipationOptions}
33  * @see {@link PibblPhysics2DPropExtension}
34  * @see {@link VerticalLine}
35  */
36 export interface VerticalLineProps
37   extends PibblEventHandlers, PibblEventFocusOptions, PibblEventParticipationOptions, PibblPhysics2DPropExtension {}
38 
39 /**
40  * Supported geometry and presentation properties for VerticalLine.
41  *
42  * @see {@link SystemStyle}
43  * @see {@link BoxStyle}
44  * @see {@link LayoutItemStyle}
45  * @see {@link LineStyle}
46  * @see {@link Length}
47  * @see {@link PixelGridAlignment}
48  * @see {@link VerticalLine}
49  */
50 export interface VerticalLineStyle
51   extends SystemStyle, BoxStyle, LayoutItemStyle, Omit<LineStyle, 'coords'> {
52   /**
53    * Horizontal coordinate or displacement in the containing coordinate system. See {@link Length}
54    * .
55    */
56   x: Exclude<Length, 'auto'>;
57   /** Vertical coordinate of the first endpoint. See {@link Length}. */
58   y1?: Exclude<Length, 'auto'>;
59   /** Vertical coordinate of the second endpoint. See {@link Length}. */
60   y2?: Exclude<Length, 'auto'>;
61   /**
62    * Pixel-grid alignment policy applied to the resolved geometry. See {@link PixelGridAlignment}.
63    */
64   alignToPixelGrid?: PixelGridAlignment;
65   /**
66    * Width used for line hit testing independently of the visible stroke width. See
67    * {@link VerticalLineStyle}.
68    */
69   lineInteractionWidth?: number;
70 }
71 
72 type ResolvedVerticalLineStyle = ResolvedDrawingStyle<VerticalLineStyle> & {
73   x: number;
74   y1: number;
75   y2: number;
76 };
77 
78 function renderVerticalLine(
79   props: VerticalLineProps,
80   style: Readonly<ResolvedVerticalLineStyle>,
81   ctx: RenderingContext2D,
82 ) {
83   const {
84     x: initialX,
85     y1 = 0,
86     y2 = ctx.canvas.height,
87     alignToPixelGrid = 'none',
88     stroke,
89     strokeWidth,
90     opacity,
91     cursor,
92     lineInteractionWidth,
93   } = style;
94   const x = adjustForPixelGrid(
95     initialX,
96     strokeWidth,
97     alignToPixelGrid,
98   );
99   const coords: [number, number][] = [
100     [x, y1],
101     [x, y2],
102   ];
103 
104   return renderLine(
105     props,
106     {
107       coords,
108       stroke,
109       strokeWidth,
110       opacity,
111       cursor,
112       lineInteractionWidth,
113     },
114     ctx,
115   );
116 }
117 
118 /**
119  * Describes a vertical-line primitive for JSX or createElement authoring.
120  *
121  * @param props - Authored component inputs, supplied through JSX or createElement. See the linked
122  * props and style types.
123  * @throws When called directly; Pibbl mounts this component through JSX or createElement.
124  *
125  * @see {@link VerticalLineProps}
126  * @see {@link VerticalLineStyle}
127  */
128 export const VerticalLine = definePrimitive<
129   VerticalLineProps,
130   VerticalLineStyle,
131   VerticalLineStyle,
132   ResolvedVerticalLineStyle
133 >(renderVerticalLine, {
134   resolveStyle: (style, context) => ({
135     ...stripLayoutParticipation(style),
136     x: resolveRequiredLength(
137       style.x,
138       context.percentageBasis.width,
139       'x',
140       context,
141     ),
142     y1: resolveLocalOffset(
143       style.y1,
144       context.percentageBasis.height,
145       'y1',
146       context,
147     ),
148     y2: resolveRequiredLength(
149       style.y2 ?? context.allocation.height,
150       context.percentageBasis.height,
151       'y2',
152       context,
153     ),
154   }) as ResolvedVerticalLineStyle,
155 });
156 registerOpaqueStyleProperties(VerticalLine, ['stroke', 'cursor']);
157
Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.