@oddkin/components 0.0.0-stage → 1.0.0-beta.0

package/dist/chip/chip.template.d.ts

@@ -0,0 +1,4 @@
+import type { OddkinChip } from './chip.js';
+/** Anatomy: `part="base"` with the default slot and, when `removable`, `part="remove"` (a button). */
+export declare const chipTemplate: (chip: OddkinChip) => import("@oddkin/core/template").TemplateResult;
+//# sourceMappingURL=chip.template.d.ts.map

package/dist/chip/chip.template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chip.template.d.ts","sourceRoot":"","sources":["../../src/chip/chip.template.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,sGAAsG;AACtG,eAAO,MAAM,YAAY,SAAU,UAAU,mDAiBzC,CAAC"}

package/dist/chip/chip.template.js

@@ -0,0 +1,19 @@
+import { html } from '@oddkin/core/template';
+import { closeGlyph } from '../styles/glyphs.js';
+/** Anatomy: `part="base"` with the default slot and, when `removable`, `part="remove"` (a button). */
+export const chipTemplate = (chip) => html `<span part="base" class="chip"
+    ><span class="label"><slot></slot></span>${chip.removable
+    ? html `<button
+            part="remove"
+            class="remove"
+            type="button"
+            aria-label=${chip._removeLabel}
+            ?disabled=${chip.disabled}
+            @click=${chip._onRemove}
+            @keydown=${chip._onKeydown}
+          >
+            ${closeGlyph}
+          </button>`
+    : null}</span
+  >`;
+//# sourceMappingURL=chip.template.js.map

package/dist/chip/chip.template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chip.template.js","sourceRoot":"","sources":["../../src/chip/chip.template.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGjD,sGAAsG;AACtG,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAgB,EAAE,EAAE,CAC/C,IAAI,CAAA;+CAEA,IAAI,CAAC,SAAS;IACZ,CAAC,CAAC,IAAI,CAAA;;;;yBAIW,IAAI,CAAC,YAAY;wBAClB,IAAI,CAAC,QAAQ;qBAChB,IAAI,CAAC,SAAS;uBACZ,IAAI,CAAC,UAAU;;cAExB,UAAU;oBACJ;IACZ,CAAC,CAAC,IACN;IACA,CAAC"}

package/dist/chip/foundation.d.ts

@@ -0,0 +1,6 @@
+export { hostStyles } from '../styles/host.styles.js';
+export { glyphStyles } from '../styles/glyphs.js';
+export { OddkinChip } from './chip.js';
+export { chipTemplate } from './chip.template.js';
+export { chipStructuralStyles } from './chip.structural.styles.js';
+//# sourceMappingURL=foundation.d.ts.map

package/dist/chip/foundation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation.d.ts","sourceRoot":"","sources":["../../src/chip/foundation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/chip/foundation.js

@@ -0,0 +1,8 @@
+// Skin-free foundation: behavior, anatomy, and structural styles (shared host defaults first).
+// Loads no default visual styles and registers nothing (multi-product.md §4).
+export { hostStyles } from '../styles/host.styles.js';
+export { glyphStyles } from '../styles/glyphs.js';
+export { OddkinChip } from './chip.js';
+export { chipTemplate } from './chip.template.js';
+export { chipStructuralStyles } from './chip.structural.styles.js';
+//# sourceMappingURL=foundation.js.map

package/dist/chip/foundation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation.js","sourceRoot":"","sources":["../../src/chip/foundation.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/chip/index.d.ts

@@ -0,0 +1,6 @@
+export { OddkinChip } from './chip.js';
+export { chipTemplate } from './chip.template.js';
+export { chipStructuralStyles } from './chip.structural.styles.js';
+export { chipStyles } from './chip.styles.js';
+export { chipDefinition } from './chip.definition.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/chip/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chip/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/chip/index.js

@@ -0,0 +1,7 @@
+// Side-effect free. Register with `@oddkin/components/define/chip`.
+export { OddkinChip } from './chip.js';
+export { chipTemplate } from './chip.template.js';
+export { chipStructuralStyles } from './chip.structural.styles.js';
+export { chipStyles } from './chip.styles.js';
+export { chipDefinition } from './chip.definition.js';
+//# sourceMappingURL=index.js.map

package/dist/chip/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chip/index.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/collection/collection.d.ts

@@ -0,0 +1,150 @@
+import { type Readable } from '@oddkin/core/reactive';
+import type { Controller, Scope } from '@oddkin/core/scope';
+/** One choice of a value collection (`odd-select`, `odd-listbox`, `odd-combobox`, radio groups). */
+export interface OptionRecord {
+    /** Submitted and compared value. */
+    readonly value: string;
+    /** Visible text and accessible name. */
+    readonly label: string;
+    /** Secondary text; from a declarative option's `title`. */
+    readonly description?: string;
+    readonly disabled?: boolean;
+    /** Label of the group the option belongs to (a declarative `<optgroup label>`). */
+    readonly group?: string;
+    /** Icon URL, drawn as `odd-icon` draws `src` (`odd-segmented-control`; from `options` only). */
+    readonly icon?: string;
+}
+/** One entry of an action collection (`odd-menu`, `odd-split-button`). */
+export type MenuItemRecord = MenuActionRecord | MenuGroupRecord | MenuSeparatorRecord;
+/** An action; with `items`, it opens a submenu instead. */
+export interface MenuActionRecord {
+    readonly kind?: 'item';
+    /** Reported as the `odd-action` detail's `id` when the action is chosen. */
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    /** Icon URL, drawn as `odd-icon` draws `src`. */
+    readonly icon?: string;
+    /** Keyboard shortcut shown at the end, e.g. "Ctrl+S"; the host handles the keys. */
+    readonly shortcut?: string;
+    readonly disabled?: boolean;
+    readonly tone?: 'danger';
+    readonly items?: readonly MenuItemRecord[];
+}
+/** A labelled group of entries (a declarative `<optgroup label>`). */
+export interface MenuGroupRecord {
+    readonly kind: 'group';
+    readonly id?: string;
+    readonly label: string;
+    readonly items: readonly MenuItemRecord[];
+}
+/** A separator between entries (a declarative `<hr>`). */
+export interface MenuSeparatorRecord {
+    readonly kind: 'separator';
+    readonly id?: string;
+}
+/** One link of a link collection (`odd-breadcrumbs`). */
+export interface LinkRecord {
+    readonly label: string;
+    readonly href: string;
+}
+/** One item of a hierarchy (`odd-tree`); from data only, there are no declarative children. */
+export interface TreeItemRecord {
+    /** Reported as the `odd-toggle` detail's `id`, and as the selected `value`. */
+    readonly id: string;
+    readonly label: string;
+    /** Icon URL, drawn as `odd-icon` draws `src`. */
+    readonly icon?: string;
+    readonly disabled?: boolean;
+    readonly children?: readonly TreeItemRecord[];
+    /** Children not loaded yet: the item can expand, and is busy until `children` is set. */
+    readonly lazy?: boolean;
+}
+/** What a reader found in the declarative children. */
+export interface Declared<R> {
+    readonly records: readonly R[];
+    /** Values of `<option selected>` children, in order (value collections). */
+    readonly selected: readonly string[];
+}
+/** `<option value disabled selected title>` and `<optgroup label disabled>` children. */
+export declare function readOptions(host: Element): Declared<OptionRecord>;
+/** One command of `odd-command-palette` (component-contracts.md §3.6). */
+export interface CommandRecord {
+    /** Reported as `detail.id` of `odd-action` when chosen. */
+    readonly id: string;
+    /** Visible text and accessible name; the search matches it. */
+    readonly label: string;
+    /** Secondary text under the label. */
+    readonly description?: string;
+    /** Icon URL, drawn as `odd-icon` draws `src`. */
+    readonly icon?: string;
+    /** Keyboard shortcut shown at the end, such as "Ctrl K" (display only). */
+    readonly shortcut?: string;
+    /** Label of the group the command belongs to; consecutive commands with one label form a group. */
+    readonly group?: string;
+    readonly disabled?: boolean;
+}
+/** The details of `odd-query-change`. */
+export interface QueryChangeDetail {
+    /** The text in the search input. */
+    readonly query: string;
+}
+/** The user typed in a filtering collection's input (`odd-combobox`, `odd-command-palette`). */
+export declare const queryChangeEvent: import("@oddkin/core/element").EventDefinition<QueryChangeDetail>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'odd-query-change': CustomEvent<QueryChangeDetail>;
+    }
+}
+/** A record and its index in the collection. */
+export interface OptionRow<R = OptionRecord> {
+    readonly option: R;
+    readonly index: number;
+}
+/** A run of records; `label` is the group's, or undefined for a record outside any group. */
+export interface OptionGroup<R = OptionRecord> {
+    readonly label: string | undefined;
+    readonly rows: OptionRow<R>[];
+}
+/** Consecutive records with the same `group` form one group; records without one stand alone. */
+export declare function groupsOf<R extends {
+    readonly group?: string;
+}>(options: readonly R[]): OptionGroup<R>[];
+/** `<option value disabled title>` (value = item id), `<optgroup label>`, and `<hr>` children. */
+export declare function readMenuItems(host: Element): Declared<MenuItemRecord>;
+/**
+ * Assigns the host's child nodes that are not collection entries (`<option>`, `<optgroup>`, `<hr>`)
+ * to `slot`, in a shadow root with `slotAssignment: 'manual'`, and again whenever the children
+ * change while `scope` lives: an element whose default slot holds its own content (a trigger's
+ * label) never renders its entries.
+ */
+export declare function assignContent(scope: Scope, host: HTMLElement, slot: () => HTMLSlotElement | null | undefined): void;
+/** `<a href>` descendants (text = label), so a server-rendered list of links works as it is. */
+export declare function readLinks(host: Element): Declared<LinkRecord>;
+export interface CollectionSourceOptions<R> {
+    /** The element whose light-DOM children are read. */
+    readonly host: HTMLElement;
+    /** The element's property name, for the conflict report. */
+    readonly name: string;
+    /** The property's value; `undefined` (not set) means the children are the source. */
+    readonly property: () => readonly R[] | undefined;
+    /** `readOptions`, `readMenuItems`, or `readLinks`. */
+    readonly read: (host: HTMLElement) => Declared<R>;
+}
+/**
+ * One collection from two forms: the property when it is set (even to an empty array), otherwise
+ * the declarative children. Connect it in `connected(scope)`, before the first render, so children
+ * that already exist (server-rendered, or written before the element was defined) render at once;
+ * children added, removed, or edited later are followed while connected. Both present: the
+ * property wins and `collection.source.conflict` is reported once per element.
+ */
+export declare class CollectionSource<R> implements Controller {
+    #private;
+    /** The records in use. */
+    readonly records: Readable<readonly R[]>;
+    /** Values of `<option selected>` children; empty while the property is set. */
+    readonly selected: Readable<readonly string[]>;
+    constructor(options: CollectionSourceOptions<R>);
+    connect(scope: Scope): void;
+}
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/collection/collection.ts"],"names":[],"mappings":"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"}

package/dist/collection/collection.js

@@ -0,0 +1,151 @@
+/**
+ * Authoring collections (component-contracts.md §2.2): the record types of value, action, and link
+ * collections, readers for their declarative children (read as data, never rendered), and
+ * `CollectionSource`, which normalizes the children and the element's property into one readable,
+ * following the children with a `MutationObserver` owned by the element's scope. Internal to
+ * `@oddkin/components`; elements re-export the record types they take.
+ */
+import { event } from '@oddkin/core/element';
+import { computed, signal } from '@oddkin/core/reactive';
+const text = (node) => (node.textContent ?? '').replace(/\s+/g, ' ').trim();
+function optionRecord(option, group) {
+    return {
+        value: option.value,
+        label: option.label,
+        ...(option.title ? { description: option.title } : {}),
+        ...(option.disabled || group?.disabled ? { disabled: true } : {}),
+        ...(group ? { group: group.label } : {}),
+    };
+}
+/** `<option value disabled selected title>` and `<optgroup label disabled>` children. */
+export function readOptions(host) {
+    const records = [];
+    const selected = [];
+    const add = (option, group) => {
+        records.push(optionRecord(option, group));
+        if (option.defaultSelected)
+            selected.push(option.value);
+    };
+    for (const child of host.children) {
+        if (child instanceof HTMLOptionElement)
+            add(child, null);
+        else if (child instanceof HTMLOptGroupElement)
+            for (const option of child.children)
+                if (option instanceof HTMLOptionElement)
+                    add(option, child);
+    }
+    return { records, selected };
+}
+/** The user typed in a filtering collection's input (`odd-combobox`, `odd-command-palette`). */
+export const queryChangeEvent = event('odd-query-change', {
+    bubbles: true,
+    composed: true,
+    cancelable: false,
+    intent: 'user',
+    description: 'The user typed: `detail.query` is the text in the input. With `no-filter`, replace the options or items with the matches.',
+});
+/** Consecutive records with the same `group` form one group; records without one stand alone. */
+export function groupsOf(options) {
+    const groups = [];
+    options.forEach((option, index) => {
+        const last = groups[groups.length - 1];
+        if (last && option.group !== undefined && last.label === option.group)
+            last.rows.push({ option, index });
+        else
+            groups.push({ label: option.group, rows: [{ option, index }] });
+    });
+    return groups;
+}
+function menuItem(option, group) {
+    return {
+        id: option.value,
+        label: option.label,
+        ...(option.title ? { description: option.title } : {}),
+        ...(option.disabled || group?.disabled ? { disabled: true } : {}),
+    };
+}
+/** `<option value disabled title>` (value = item id), `<optgroup label>`, and `<hr>` children. */
+export function readMenuItems(host) {
+    const records = [];
+    for (const child of host.children) {
+        if (child instanceof HTMLOptionElement)
+            records.push(menuItem(child, null));
+        else if (child instanceof HTMLHRElement)
+            records.push({ kind: 'separator' });
+        else if (child instanceof HTMLOptGroupElement)
+            records.push({
+                kind: 'group',
+                label: child.label,
+                items: [...child.children]
+                    .filter((option) => option instanceof HTMLOptionElement)
+                    .map((option) => menuItem(option, child)),
+            });
+    }
+    return { records, selected: [] };
+}
+/**
+ * Assigns the host's child nodes that are not collection entries (`<option>`, `<optgroup>`, `<hr>`)
+ * to `slot`, in a shadow root with `slotAssignment: 'manual'`, and again whenever the children
+ * change while `scope` lives: an element whose default slot holds its own content (a trigger's
+ * label) never renders its entries.
+ */
+export function assignContent(scope, host, slot) {
+    const assign = () => slot()?.assign(...[...host.childNodes].filter((node) => (node instanceof Element || node instanceof Text) &&
+        !(node instanceof HTMLOptionElement ||
+            node instanceof HTMLOptGroupElement ||
+            node instanceof HTMLHRElement)));
+    assign();
+    const observer = new MutationObserver(assign);
+    observer.observe(host, { childList: true });
+    scope.add(() => observer.disconnect(), 'slotted content');
+}
+/** `<a href>` descendants (text = label), so a server-rendered list of links works as it is. */
+export function readLinks(host) {
+    const records = [...host.querySelectorAll('a[href]')].map((link) => ({
+        label: text(link),
+        href: link.getAttribute('href'),
+    }));
+    return { records, selected: [] };
+}
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * One collection from two forms: the property when it is set (even to an empty array), otherwise
+ * the declarative children. Connect it in `connected(scope)`, before the first render, so children
+ * that already exist (server-rendered, or written before the element was defined) render at once;
+ * children added, removed, or edited later are followed while connected. Both present: the
+ * property wins and `collection.source.conflict` is reported once per element.
+ */
+export class CollectionSource {
+    #options;
+    #declared = signal({ records: [], selected: [] }, { equals: same });
+    #warned = false;
+    /** The records in use. */
+    records;
+    /** Values of `<option selected>` children; empty while the property is set. */
+    selected;
+    constructor(options) {
+        this.#options = options;
+        this.records = computed(() => options.property() ?? this.#declared.value.records);
+        this.selected = computed(() => (options.property() ? [] : this.#declared.value.selected));
+    }
+    connect(scope) {
+        const { host, read } = this.#options;
+        const refresh = () => (this.#declared.value = read(host));
+        refresh();
+        const observer = new MutationObserver(refresh);
+        observer.observe(host, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributeFilter: ['value', 'label', 'disabled', 'selected', 'title', 'href'],
+        });
+        scope.add(() => observer.disconnect(), 'collection source');
+        scope.effect(() => {
+            if (this.#warned || !this.#options.property() || !this.#declared.value.records.length)
+                return;
+            this.#warned = true;
+            console.warn(`[collection.source.conflict] <${host.localName}> has both \`${this.#options.name}\` and declarative children; \`${this.#options.name}\` wins and the children are ignored.`);
+        });
+    }
+}
+//# sourceMappingURL=collection.js.map

package/dist/collection/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../../src/collection/collection.ts"],"names":[],"mappings":"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"}

package/dist/collection/option-control.d.ts

@@ -0,0 +1,55 @@
+import { type ElementEvents } from '@oddkin/core/element';
+import { type Readable } from '@oddkin/core/reactive';
+import type { Scope } from '@oddkin/core/scope';
+import { OddkinFormControl, type FormControlOptions } from '../form-control/form-control.js';
+import { type OptionRecord } from './collection.js';
+/** The user changed the selection. */
+export declare const optionInputEvent: import("@oddkin/core/element").EventDefinition<void>;
+/** Dispatched after `input` for each user change (native `change` is not composed). */
+export declare const optionChangeEvent: import("@oddkin/core/element").EventDefinition<void>;
+declare const OddkinOptionControl_base: import("@oddkin/core/element").WithProps<typeof OddkinFormControl, {
+    readonly label: import("@oddkin/core/element").PropDefinition<string>;
+    readonly options: import("@oddkin/core/element").PropDefinition<readonly OptionRecord[] | undefined>;
+    readonly value: import("@oddkin/core/element").PropDefinition<string>;
+    readonly values: import("@oddkin/core/element").PropDefinition<readonly string[] | undefined>;
+    readonly multiple: import("@oddkin/core/element").PropDefinition<boolean>;
+    readonly required: import("@oddkin/core/element").PropDefinition<boolean>;
+    readonly loading: import("@oddkin/core/element").PropDefinition<boolean>;
+}>;
+/**
+ * What every value collection that is a form control shares (component-contracts.md §2.2, §2.4):
+ * options from `<option>`/`<optgroup>` children or `options`, one value or several (`multiple`),
+ * the declared default (the `value` attribute, then `<option selected>`), the form value (each
+ * value under `name` with `multiple`), `required` through a detached native select (the browser's
+ * own valueMissing flag and message, pointed at `_anchor()`), reset, restore, and user changes
+ * reported as `input` and `change` (an element adding events declares all of them in its own
+ * `events`, which replaces these). Under `odd-listbox` and `odd-combobox`; internal to
+ * `@oddkin/components` (import it relatively).
+ */
+export declare class OddkinOptionControl extends OddkinOptionControl_base {
+    #private;
+    static events: {
+        input: import("@oddkin/core/element").EventDefinition<void>;
+        change: import("@oddkin/core/element").EventDefinition<void>;
+    };
+    readonly _events?: ElementEvents<typeof OddkinOptionControl>;
+    /** @internal The options in use. */
+    readonly _options: Readable<readonly OptionRecord[]>;
+    /** @internal Selected values, single or multiple. */
+    readonly _selected: Readable<readonly string[]>;
+    /** @internal Where a blocked submission points and moves focus. */
+    protected _anchor(): HTMLElement | null | undefined;
+    protected _formOptions(): FormControlOptions;
+    /** @internal After the owning form's reset restored the declared selection. */
+    protected _onReset(): void;
+    /** @internal Sets the selection the user chose and reports it; false when nothing changed. */
+    _commit(next: readonly string[]): boolean;
+    /** @internal The option, when the user may choose it now. */
+    _usable(option: OptionRecord | undefined): OptionRecord | undefined;
+    /** @internal Selects the option (single) or toggles it (multiple); false when unusable or unchanged. */
+    _toggle(option: OptionRecord | undefined): boolean;
+    protected connected(scope: Scope): void;
+    protected updated(changes: ReadonlyMap<string, unknown>): void;
+}
+export {};
+//# sourceMappingURL=option-control.d.ts.map

package/dist/collection/option-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"option-control.d.ts","sourceRoot":"","sources":["../../src/collection/option-control.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC7F,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEnF,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,sDAM3B,CAAC;AACH,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,sDAK5B,CAAC;;;;;;;;;;AAKH;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,SAAQ,wBAkBvC;;IACA,OAAgB,MAAM;QAAK,KAAK;QAAoB,MAAM;MAAsB;IAChF,SAAiB,OAAO,CAAC,EAAE,aAAa,CAAC,OAAO,mBAAmB,CAAC,CAAC;IAerE,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,YAAY,EAAE,CAAC,CAAwB;IAE5E,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,SAAS,MAAM,EAAE,CAAC,CAE7C;IAEF,mEAAmE;IACnE,SAAS,CAAC,OAAO,IAAI,WAAW,GAAG,IAAI,GAAG,SAAS,CAElD;IAED,UAAmB,YAAY,IAAI,kBAAkB,CAkCpD;IAED,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,IAAI,IAAI,CAAG;IAU7B,8FAA8F;IAC9F,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAQxC;IAED,6DAA6D;IAC7D,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAGlE;IAED,wGAAwG;IACxG,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAQjD;IAED,UAAmB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAU/C;IAED,UAAmB,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAOtE;CACF"}

package/dist/collection/option-control.js

@@ -0,0 +1,168 @@
+import { event, prop } from '@oddkin/core/element';
+import { computed } from '@oddkin/core/reactive';
+import { OddkinFormControl } from '../form-control/form-control.js';
+import { CollectionSource, readOptions } from './collection.js';
+/** The user changed the selection. */
+export const optionInputEvent = event('input', {
+    bubbles: true,
+    composed: true,
+    cancelable: false,
+    syncs: 'value',
+    intent: 'user',
+});
+/** Dispatched after `input` for each user change (native `change` is not composed). */
+export const optionChangeEvent = event('change', {
+    bubbles: true,
+    composed: false,
+    cancelable: false,
+    intent: 'user',
+});
+const same = (a, b) => a.length === b.length && a.every((value) => b.includes(value));
+/**
+ * What every value collection that is a form control shares (component-contracts.md §2.2, §2.4):
+ * options from `<option>`/`<optgroup>` children or `options`, one value or several (`multiple`),
+ * the declared default (the `value` attribute, then `<option selected>`), the form value (each
+ * value under `name` with `multiple`), `required` through a detached native select (the browser's
+ * own valueMissing flag and message, pointed at `_anchor()`), reset, restore, and user changes
+ * reported as `input` and `change` (an element adding events declares all of them in its own
+ * `events`, which replaces these). Under `odd-listbox` and `odd-combobox`; internal to
+ * `@oddkin/components` (import it relatively).
+ */
+export class OddkinOptionControl extends OddkinFormControl.with({
+    label: prop.string({ default: '', description: 'Visible label; names the control.' }),
+    options: prop.object({
+        description: 'The choices; when set, `<option>` children are ignored.',
+    }),
+    value: prop.string({
+        default: '',
+        description: 'Value of the selected option; the `value` attribute sets the default.',
+    }),
+    values: prop.object({
+        description: 'Values of the selected options with `multiple`.',
+    }),
+    multiple: prop.boolean({ reflect: true, description: 'Several options can be selected.' }),
+    required: prop.boolean({ reflect: true, description: 'An option must be selected to submit.' }),
+    loading: prop.boolean({
+        reflect: true,
+        description: 'Shows a busy row and marks the options busy.',
+    }),
+}) {
+    static events = { input: optionInputEvent, change: optionChangeEvent };
+    #source = new CollectionSource({
+        host: this,
+        name: 'options',
+        property: () => this.options,
+        read: readOptions,
+    });
+    // A detached native select mirrors `required` and the selection, so the browser supplies the
+    // valueMissing flag and its own message; `_anchor()` is where the message points.
+    #mirror = document.createElement('select');
+    // Declared `<option selected>` children set the selection until the user or a script does.
+    #chosen = false;
+    #applied;
+    /** @internal The options in use. */
+    _options = this.#source.records;
+    /** @internal Selected values, single or multiple. */
+    _selected = computed(() => this.multiple ? (this.values ?? []) : this.value ? [this.value] : []);
+    /** @internal Where a blocked submission points and moves focus. */
+    _anchor() {
+        return null;
+    }
+    _formOptions() {
+        return {
+            value: () => {
+                const selected = this._selected.value;
+                if (!this.multiple)
+                    return selected[0] ?? null;
+                const name = this.name;
+                if (!name || !selected.length)
+                    return null;
+                const data = new FormData();
+                for (const value of selected)
+                    data.append(name, value);
+                return data;
+            },
+            state: () => this._selected.value.join('\n'),
+            control: () => {
+                const mirror = this.#mirror;
+                mirror.required = this.required;
+                mirror.multiple = this.multiple;
+                mirror.replaceChildren(...this._selected.value.map((value) => new Option(value, value, true, true)));
+                return mirror;
+            },
+            anchor: () => this._anchor(),
+            onReset: () => {
+                this.#chosen = false;
+                this.#applyDeclared();
+                this._onReset();
+            },
+            onRestore: (state) => {
+                if (typeof state !== 'string')
+                    return;
+                this.#chosen = true;
+                if (this.multiple)
+                    this.values = state ? state.split('\n') : [];
+                else
+                    this.value = state;
+            },
+        };
+    }
+    /** @internal After the owning form's reset restored the declared selection. */
+    _onReset() { }
+    // The declared default: `<option selected>` children, unless the `value` attribute gives one.
+    #applyDeclared() {
+        if (this.#chosen)
+            return;
+        const declared = this.#source.selected.peek();
+        if (this.multiple)
+            this.#applied = this.values = declared;
+        else
+            this.#applied = this.value = this.getAttribute('value') ?? declared[0] ?? '';
+    }
+    /** @internal Sets the selection the user chose and reports it; false when nothing changed. */
+    _commit(next) {
+        if (same(next, this._selected.peek()))
+            return false;
+        this.#chosen = true;
+        if (this.multiple)
+            this.values = next;
+        else
+            this.value = next[0] ?? '';
+        this.emit(optionInputEvent);
+        this.emit(optionChangeEvent);
+        return true;
+    }
+    /** @internal The option, when the user may choose it now. */
+    _usable(option) {
+        // `_formDisabled` covers the element's own `disabled` and a disabled fieldset.
+        return option && !option.disabled && !this._formDisabled.peek() ? option : undefined;
+    }
+    /** @internal Selects the option (single) or toggles it (multiple); false when unusable or unchanged. */
+    _toggle(option) {
+        if (!this._usable(option))
+            return false;
+        const value = option.value;
+        const before = this._selected.peek();
+        if (!this.multiple)
+            return this._commit([value]);
+        return this._commit(before.includes(value) ? before.filter((v) => v !== value) : [...before, value]);
+    }
+    connected(scope) {
+        super.connected(scope);
+        scope.use(this.#source);
+        // A selection set as a property before connecting is the author's, not a default.
+        if (this.multiple ? this.values !== undefined : this.value && !this.hasAttribute('value'))
+            this.#chosen = true;
+        scope.effect(() => {
+            void this.#source.selected.value;
+            this.#applyDeclared();
+        });
+    }
+    updated(changes) {
+        // A script's selection, unlike the declared default, stays.
+        if ((changes.has('value') && this.value !== this.#applied) ||
+            (changes.has('values') && this.values !== this.#applied))
+            this.#chosen = true;
+    }
+}
+//# sourceMappingURL=option-control.js.map