@websublime/line-components 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,140 @@
1
+ /**
2
+ * The Button press machine, shared by `<line-button>` and `<line-icon-button>`
3
+ * (spec `0002-button.md` States; Phase 1 spec §6.C.5; ARCH §13.1).
4
+ *
5
+ * The press is the only finite state: `idle → active`. `disabled`, `loading`
6
+ * and `pressed` are props that the `isInteractive` guard and the actions read
7
+ * at event time. `ACTIVATE` flips a toggle through `onPressedChange`. A `watch`
8
+ * cancels a running press when `disabled` or `loading` turns true. The module
9
+ * knows nothing about forms or DOM events and imports no component
10
+ * (MANIFESTO Law 4).
11
+ *
12
+ * @module shared/button-machine
13
+ */
14
+
15
+ import { createMachine, type Service } from '@zag-js/core';
16
+
17
+ /** Machine props. A component passes them as a live function of its own properties. */
18
+ export interface ButtonMachineProps {
19
+ disabled?: boolean | undefined;
20
+ loading?: boolean | undefined;
21
+ /** `undefined` means the button is not a toggle. */
22
+ pressed?: boolean | undefined;
23
+ /** Called with the next pressed state when an activation flips a toggle. */
24
+ onPressedChange?: ((next: boolean) => void) | undefined;
25
+ }
26
+
27
+ export type ButtonMachineEvent =
28
+ | { type: 'PRESS_START' }
29
+ | { type: 'PRESS_END' }
30
+ | { type: 'PRESS_CANCEL' }
31
+ | { type: 'ACTIVATE' }
32
+ | { type: 'FOCUS'; visible: boolean }
33
+ | { type: 'BLUR' };
34
+
35
+ export interface ButtonMachineSchema {
36
+ props: ButtonMachineProps;
37
+ context: { focusVisible: boolean };
38
+ state: 'idle' | 'active';
39
+ guard: 'isInteractive';
40
+ action: 'togglePressed' | 'setFocusVisible' | 'clearFocusVisible';
41
+ event: ButtonMachineEvent;
42
+ }
43
+
44
+ export type ButtonService = Service<ButtonMachineSchema>;
45
+
46
+ export const buttonMachine = createMachine<ButtonMachineSchema>({
47
+ initialState: () => 'idle',
48
+ context: ({ bindable }) => ({
49
+ focusVisible: bindable<boolean>(() => ({ defaultValue: false })),
50
+ }),
51
+ watch({ track, prop, guard, send }) {
52
+ track([() => prop('disabled'), () => prop('loading')], () => {
53
+ if (!guard('isInteractive')) send({ type: 'PRESS_CANCEL' });
54
+ });
55
+ },
56
+ on: {
57
+ ACTIVATE: { guard: 'isInteractive', actions: ['togglePressed'] },
58
+ FOCUS: { actions: ['setFocusVisible'] },
59
+ BLUR: { actions: ['clearFocusVisible'] },
60
+ },
61
+ states: {
62
+ idle: {
63
+ on: { PRESS_START: { target: 'active', guard: 'isInteractive' } },
64
+ },
65
+ active: {
66
+ on: {
67
+ PRESS_END: { target: 'idle' },
68
+ PRESS_CANCEL: { target: 'idle' },
69
+ },
70
+ },
71
+ },
72
+ implementations: {
73
+ guards: {
74
+ isInteractive: ({ prop }) => !(prop('disabled') || prop('loading')),
75
+ },
76
+ actions: {
77
+ togglePressed({ prop }) {
78
+ const pressed = prop('pressed');
79
+ if (pressed !== undefined) prop('onPressedChange')?.(!pressed);
80
+ },
81
+ setFocusVisible({ context, event }) {
82
+ context.set('focusVisible', event.type === 'FOCUS' && event.visible === true);
83
+ },
84
+ clearFocusVisible({ context }) {
85
+ context.set('focusVisible', false);
86
+ },
87
+ },
88
+ },
89
+ });
90
+
91
+ /** What the inner native `<button>` and the host reflection read. */
92
+ export interface ButtonApi {
93
+ active: boolean;
94
+ /** `true` only on a pressed toggle. */
95
+ pressed: boolean;
96
+ loading: boolean;
97
+ disabled: boolean;
98
+ focusVisible: boolean;
99
+ /** `!disabled && !loading`: whether an activation runs now. */
100
+ interactive: boolean;
101
+ /** ARIA and `disabled` for the inner `<button>`; an `undefined` attribute is left off. */
102
+ buttonAttrs: {
103
+ 'aria-pressed': 'true' | 'false' | undefined;
104
+ 'aria-disabled': 'true' | undefined;
105
+ disabled: boolean;
106
+ };
107
+ }
108
+
109
+ function api(props: ButtonMachineProps, active: boolean, focusVisible: boolean): ButtonApi {
110
+ const disabled = props.disabled === true;
111
+ const loading = props.loading === true;
112
+ return {
113
+ active,
114
+ pressed: props.pressed === true,
115
+ loading,
116
+ disabled,
117
+ focusVisible,
118
+ interactive: !(disabled || loading),
119
+ buttonAttrs: {
120
+ 'aria-pressed': props.pressed === undefined ? undefined : (String(props.pressed) as 'true' | 'false'),
121
+ 'aria-disabled': loading && !disabled ? 'true' : undefined,
122
+ disabled,
123
+ },
124
+ };
125
+ }
126
+
127
+ /** Reads the running machine at call time. */
128
+ export function connect(service: ButtonService): ButtonApi {
129
+ const { prop } = service;
130
+ return api(
131
+ { disabled: prop('disabled'), loading: prop('loading'), pressed: prop('pressed') },
132
+ service.state.matches('active'),
133
+ service.context.get('focusVisible'),
134
+ );
135
+ }
136
+
137
+ /** The same view without a machine, for the controller's static fallback (MANIFESTO Law 9). */
138
+ export function connectStatic(props: ButtonMachineProps): ButtonApi {
139
+ return api(props, false, false);
140
+ }
@@ -0,0 +1,3 @@
1
+ // biome-ignore lint/performance/noBarrelFile: the `./stack` subpath entry registers `line-stack` and exposes its class and types (spec 0018-stack.md Bundle).
2
+ export { LineStack } from './stack.js';
3
+ export type { StackAlign, StackGap, StackJustify, StackOrientation } from './stack.types.js';
@@ -0,0 +1,169 @@
1
+ import { LineElement } from '@websublime/line-core';
2
+ import { commonReset } from '@websublime/line-core/styles';
3
+ import { type ComplexAttributeConverter, css, html, type PropertyDeclarations, type TemplateResult } from 'lit';
4
+ import type { StackAlign, StackGap, StackJustify, StackOrientation } from './stack.types.js';
5
+
6
+ const ORIENTATIONS: readonly StackOrientation[] = ['horizontal', 'vertical'];
7
+ const JUSTIFIES: readonly StackJustify[] = [
8
+ 'start',
9
+ 'center',
10
+ 'end',
11
+ 'spaceBetween',
12
+ 'spaceAround',
13
+ 'spaceEvenly',
14
+ 'stretch',
15
+ ];
16
+ const ALIGNS: readonly StackAlign[] = ['start', 'center', 'end', 'stretch'];
17
+ const GAPS: readonly StackGap[] = ['0', '1', '2', '3', '4', '5'];
18
+
19
+ /** An unknown value behaves as `fallback`; the attribute keeps what the author wrote. */
20
+ function enumConverter<T extends string>(values: readonly T[], fallback: T): ComplexAttributeConverter<T> {
21
+ return { fromAttribute: (value) => values.find((entry) => entry === value) ?? fallback };
22
+ }
23
+
24
+ /** An unknown `gap` behaves as no attribute, so the default step applies. */
25
+ const gapConverter: ComplexAttributeConverter<StackGap | undefined> = {
26
+ fromAttribute: (value) => GAPS.find((gap) => gap === value),
27
+ };
28
+
29
+ /**
30
+ * `<line-stack>` lays out its children in one row or one column with a gap
31
+ * between them. The host is the flex container and the slotted children are
32
+ * its flex items. It adds no role, so it stays `generic`; put `role="list"`
33
+ * on the host and `role="listitem"` on the children to build a list.
34
+ *
35
+ * @summary A layout container that places its children in one row or column with even spacing.
36
+ *
37
+ * @slot - The children; each element becomes a flex item.
38
+ *
39
+ * @cssprop [--line-stack-gap=var(--line-layout-gap-2)] - Space between items; `gap="0"` uses `0` and `gap="N"` uses `var(--line-layout-gap-N)`.
40
+ */
41
+ export class LineStack extends LineElement {
42
+ static override properties: PropertyDeclarations = {
43
+ orientation: { reflect: true, useDefault: true, converter: enumConverter(ORIENTATIONS, 'vertical') },
44
+ justify: { reflect: true, useDefault: true, converter: enumConverter(JUSTIFIES, 'start') },
45
+ align: { reflect: true, useDefault: true, converter: enumConverter(ALIGNS, 'stretch') },
46
+ gap: { reflect: true, converter: gapConverter },
47
+ wrap: { type: Boolean, reflect: true, useDefault: true },
48
+ };
49
+
50
+ static override styles = [
51
+ commonReset,
52
+ css`
53
+ :host {
54
+ --line-stack-gap: var(--line-layout-gap-2);
55
+
56
+ display: flex;
57
+ flex-direction: column;
58
+ justify-content: flex-start;
59
+ align-items: stretch;
60
+ flex-wrap: nowrap;
61
+ gap: var(--line-stack-gap);
62
+ }
63
+
64
+ :host([hidden]) {
65
+ display: none;
66
+ }
67
+
68
+ :host([orientation='horizontal']) {
69
+ flex-direction: row;
70
+ }
71
+
72
+ :host([justify='center']) {
73
+ justify-content: center;
74
+ }
75
+
76
+ :host([justify='end']) {
77
+ justify-content: flex-end;
78
+ }
79
+
80
+ :host([justify='spaceBetween']) {
81
+ justify-content: space-between;
82
+ }
83
+
84
+ :host([justify='spaceAround']) {
85
+ justify-content: space-around;
86
+ }
87
+
88
+ :host([justify='spaceEvenly']) {
89
+ justify-content: space-evenly;
90
+ }
91
+
92
+ :host([justify='stretch']) ::slotted(*) {
93
+ flex-grow: 1;
94
+ }
95
+
96
+ :host([align='start']) {
97
+ align-items: flex-start;
98
+ }
99
+
100
+ :host([align='center']) {
101
+ align-items: center;
102
+ }
103
+
104
+ :host([align='end']) {
105
+ align-items: flex-end;
106
+ }
107
+
108
+ :host([wrap]) {
109
+ flex-wrap: wrap;
110
+ }
111
+
112
+ :host([gap='0']) {
113
+ --line-stack-gap: 0;
114
+ }
115
+
116
+ :host([gap='1']) {
117
+ --line-stack-gap: var(--line-layout-gap-1);
118
+ }
119
+
120
+ :host([gap='2']) {
121
+ --line-stack-gap: var(--line-layout-gap-2);
122
+ }
123
+
124
+ :host([gap='3']) {
125
+ --line-stack-gap: var(--line-layout-gap-3);
126
+ }
127
+
128
+ :host([gap='4']) {
129
+ --line-stack-gap: var(--line-layout-gap-4);
130
+ }
131
+
132
+ :host([gap='5']) {
133
+ --line-stack-gap: var(--line-layout-gap-5);
134
+ }
135
+ `,
136
+ ];
137
+
138
+ /** Main axis; an unknown value behaves as `vertical`. A horizontal stack follows the writing direction. */
139
+ declare orientation: StackOrientation;
140
+ /** Distribution on the main axis; `stretch` grows every item. An unknown value behaves as `start`. */
141
+ declare justify: StackJustify;
142
+ /** Alignment on the cross axis; an unknown value behaves as `stretch`. */
143
+ declare align: StackAlign;
144
+ /** Gap step from `0` to `5`; `undefined` or an unknown value gives step `2`. */
145
+ declare gap: StackGap | undefined;
146
+ /** Lets the items flow onto more lines when they run out of space. */
147
+ declare wrap: boolean;
148
+
149
+ constructor() {
150
+ super();
151
+ // `useDefault` keeps these initial values out of the attributes, so an unknown author value stays (C8).
152
+ this.orientation = 'vertical';
153
+ this.justify = 'start';
154
+ this.align = 'stretch';
155
+ this.wrap = false;
156
+ }
157
+
158
+ override render(): TemplateResult {
159
+ return html`<slot></slot>`;
160
+ }
161
+ }
162
+
163
+ customElements.define('line-stack', LineStack);
164
+
165
+ declare global {
166
+ interface HTMLElementTagNameMap {
167
+ 'line-stack': LineStack;
168
+ }
169
+ }
@@ -0,0 +1,11 @@
1
+ /** Main axis of `<line-stack>`; the A2UI basic v0.9 `List.direction` values. */
2
+ export type StackOrientation = 'horizontal' | 'vertical';
3
+
4
+ /** Main-axis distribution of `<line-stack>`; the A2UI basic v0.9 `justify` values. */
5
+ export type StackJustify = 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround' | 'spaceEvenly' | 'stretch';
6
+
7
+ /** Cross-axis alignment of `<line-stack>`; the A2UI basic v0.9 `align` values without `baseline`. */
8
+ export type StackAlign = 'start' | 'center' | 'end' | 'stretch';
9
+
10
+ /** Gap step of `<line-stack>` on the `--line-layout-gap-*` scale (ARCH §17.2 C6). */
11
+ export type StackGap = '0' | '1' | '2' | '3' | '4' | '5';