@sekiui/elements 0.1.2 → 0.1.4

package/dist/types/components/sheet/seki-sheet.d.ts

@@ -45,8 +45,12 @@ export declare class SekiSheet {
      * event shape so a consumer can listen to one event name across every overlay.
      */
     sekiOpenChange: EventEmitter<boolean>;
+    /**
+     * Internal: notifies seki-sheet-content that `_sheetContext` changed. Not
+     * part of the public API; listen to `sekiOpenChange` instead.
+     */
+    sheetContextChange: EventEmitter<void>;
     componentWillLoad(): void;
-    componentDidLoad(): void;
     handleOpenPropChange(newValue: boolean): void;
     /**
      * Opens the sheet

package/dist/types/components/slider/seki-slider.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import { FormControlState } from '../../utils/form-control';
 /**
  * @component seki-slider
  * @description An input where the user selects a value from within a given range.
@@ -14,6 +15,7 @@ export declare class SekiSlider {
     private trackEl?;
     private thumbEl?;
     private isDragging;
+    private formControl?;
     /**
      * Minimum value of the slider.
      */
@@ -75,6 +77,9 @@ export declare class SekiSlider {
         value: number;
     }>;
     componentWillLoad(): void;
+    formResetCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    formStateRestoreCallback(state: FormControlState): void;
     /**
      * Mirror an externally-assigned `value` onto the rendered value. This is what
      * keeps controlled usage working: a consumer writing `el.value = n` (or writing
@@ -88,9 +93,6 @@ export declare class SekiSlider {
      * therefore never participated in form submission.
      */
     private syncFormValue;
-    /**
-     * Get current value (controlled vs uncontrolled), clamped to valid range
-     */
     private get currentValue();
     /**
      * Clamp value to min/max range and round to step

package/dist/types/components/switch/seki-switch.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import { FormControlState } from '../../utils/form-control';
 /**
  * @component seki-switch
  * @description An accessible toggle control for binary on/off states with full keyboard navigation,
@@ -10,6 +11,9 @@ import { EventEmitter } from '../../stencil-public-runtime';
  */
 export declare class SekiSwitch {
     el: HTMLElement;
+    internals: ElementInternals;
+    private switchEl?;
+    private formControl?;
     /**
      * @description Checked state. In HTML this attribute is the *initial* state (as
      * with `<input checked>`), and the component keeps it in step with user
@@ -57,6 +61,10 @@ export declare class SekiSwitch {
      * Seed internal state from `checked` when authored, else from `defaultChecked`.
      */
     componentWillLoad(): void;
+    handleFormStateChange(): void;
+    formResetCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    formStateRestoreCallback(state: FormControlState): void;
     /**
      * Mirror externally-assigned `checked` onto the rendered state. This is what
      * keeps controlled usage working: a consumer writing `el.checked = x` (or

package/dist/types/components/textarea/seki-textarea.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import { FormControlState } from '../../utils/form-control';
 /**
  * @component seki-textarea
  * @description A multi-line text input field with full form integration, accessibility support,
@@ -10,6 +11,8 @@ import { EventEmitter } from '../../stencil-public-runtime';
 export declare class SekiTextarea {
     el: HTMLElement;
     internals: ElementInternals;
+    private textareaEl?;
+    private formControl?;
     /**
      * Current value of the textarea
      */
@@ -102,7 +105,15 @@ export declare class SekiTextarea {
     private handleFocus;
     private handleBlur;
     formResetCallback(): void;
-    formStateRestoreCallback(state: string): void;
+    formDisabledCallback(disabled: boolean): void;
+    formStateRestoreCallback(state: FormControlState): void;
+    /**
+     * Keep the inner textareaEl and the form in step with a programmatic `el.value = x`
+     * without waiting for the next render, so `form.checkValidity()` and FormData
+     * read the new value immediately.
+     */
+    handleFormStateChange(): void;
     componentWillLoad(): void;
+    componentDidRender(): void;
     render(): any;
 }

package/dist/types/components/tooltip/seki-tooltip.d.ts

@@ -86,6 +86,7 @@ export declare class SekiTooltip {
     private showTimer;
     private hideTimer;
     private triggerEl;
+    private boundTrigger;
     private longPressTimer;
     private touchStartX;
     private touchStartY;
@@ -146,13 +147,21 @@ export declare class SekiTooltip {
      */
     private onEscapeKey;
     /**
-     * Attach event listeners to trigger
+     * Bind listeners to the element currently assigned to the trigger slot.
+     * Idempotent: if the trigger is unchanged nothing is re-bound; if it was
+     * replaced, the old element is detached first.
      */
     private attachTriggerListeners;
+    private removeTriggerListeners;
     /**
-     * Remove event listeners from trigger
+     * Remove event listeners from the bound trigger
      */
     private detachTriggerListeners;
+    /**
+     * The trigger slot's assigned content changed (trigger added/replaced/removed):
+     * move the listeners over to the new trigger.
+     */
+    private onTriggerSlotChange;
     componentWillLoad(): void;
     componentDidLoad(): void;
     openChanged(newValue: boolean): void;

package/dist/types/components.d.ts

@@ -18,7 +18,7 @@ import { CarouselContext } from "./components/carousel/seki-carousel";
 import { ChartData, ChartOptions, ChartType } from "./components/chart/chart-types";
 import { ChartLegendConfig } from "./components/chart-legend/seki-chart-legend";
 import { ComboboxChangeEventDetail, ComboboxCustomValueEventDetail, ComboboxEmptyReason, ComboboxItem, ComboboxMultiSelectDisplay, ComboboxSearchEventDetail, ComboboxValue } from "./utils/combobox";
-import { ColumnDef, ColumnReorderDetail, ColumnResizeDetail, ColumnsChangeDetail, FilterChangeDetail, FilterValue, PageChangeDetail, RowClickDetail, RowExpandDetail, SelectionChangeDetail, SortChangeDetail } from "./components/data-table/interfaces";
+import { ColumnDef, ColumnReorderDetail, ColumnResizeDetail, ColumnsChangeDetail, FetchDataCallback, FilterChangeDetail, FilterValue, PageChangeDetail, RenderExpandedRowCallback, RowClickDetail, RowExpandDetail, SelectionChangeDetail, SortChangeDetail } from "./components/data-table/interfaces";
 import { DatePickerMode, DateRange as DateRange1 } from "./components/date-picker/seki-date-picker";
 import { DrawerDirection } from "./components/drawer/seki-drawer-content";
 import { DropdownMenuAlign, DropdownMenuSide } from "./components/dropdown-menu/seki-dropdown-menu";
@@ -58,7 +58,7 @@ export { CarouselContext } from "./components/carousel/seki-carousel";
 export { ChartData, ChartOptions, ChartType } from "./components/chart/chart-types";
 export { ChartLegendConfig } from "./components/chart-legend/seki-chart-legend";
 export { ComboboxChangeEventDetail, ComboboxCustomValueEventDetail, ComboboxEmptyReason, ComboboxItem, ComboboxMultiSelectDisplay, ComboboxSearchEventDetail, ComboboxValue } from "./utils/combobox";
-export { ColumnDef, ColumnReorderDetail, ColumnResizeDetail, ColumnsChangeDetail, FilterChangeDetail, FilterValue, PageChangeDetail, RowClickDetail, RowExpandDetail, SelectionChangeDetail, SortChangeDetail } from "./components/data-table/interfaces";
+export { ColumnDef, ColumnReorderDetail, ColumnResizeDetail, ColumnsChangeDetail, FetchDataCallback, FilterChangeDetail, FilterValue, PageChangeDetail, RenderExpandedRowCallback, RowClickDetail, RowExpandDetail, SelectionChangeDetail, SortChangeDetail } from "./components/data-table/interfaces";
 export { DatePickerMode, DateRange as DateRange1 } from "./components/date-picker/seki-date-picker";
 export { DrawerDirection } from "./components/drawer/seki-drawer-content";
 export { DropdownMenuAlign, DropdownMenuSide } from "./components/dropdown-menu/seki-dropdown-menu";
@@ -1449,6 +1449,11 @@ export namespace Components {
           * @default false
          */
         "expandable": boolean;
+        /**
+          * Callback to fetch data. Set it as a JS property. Assigning or replacing it (re)loads the table. Must be a
+          * @Prop : in the lazy-loader build only decorated members are proxied from the host element to the instance.
+         */
+        "fetchData"?: FetchDataCallback;
         /**
           * Get current filter state
          */
@@ -1485,6 +1490,11 @@ export namespace Components {
           * Refresh data
          */
         "refresh": () => Promise<void>;
+        /**
+          * Callback to render expanded row content (must be a
+          * @Prop , see fetchData)
+         */
+        "renderExpandedRow"?: RenderExpandedRowCallback;
         /**
           * Fixed row height for virtualization
           * @default 48
@@ -2008,7 +2018,7 @@ export namespace Components {
     }
     interface SekiFieldLabel {
         /**
-          * ID of the form control this label is for Sets the `for` attribute on the label element
+          * ID of the form control this label is for Resolved in the label's own root node (not this component's shadow root), so it reaches light-DOM controls. Falls back to the control nested in the label.
          */
         "htmlFor"?: string;
         /**
@@ -2359,7 +2369,7 @@ export namespace Components {
          */
         "disabled"?: boolean;
         /**
-          * The ID of the form element this label is associated with. Maps to the `htmlFor` attribute on the inner `<label>` element.
+          * The ID of the form element this label is associated with. Resolved in the label's own root node (document or shadow root), not in this component's shadow root, so it reaches light-DOM controls. Without it, the first control nested inside the label is used.
          */
         "for"?: string;
         /**
@@ -4710,6 +4720,7 @@ declare global {
     };
     interface HTMLSekiAlertDialogElementEventMap {
         "sekiOpenChange": boolean;
+        "sekiContextChange": void;
     }
     /**
      * Alert Dialog root component for confirmation dialogs
@@ -5480,6 +5491,7 @@ declare global {
     };
     interface HTMLSekiCollapsibleElementEventMap {
         "sekiOpenChange": boolean;
+        "sekiContextChange": void;
     }
     interface HTMLSekiCollapsibleElement extends Components.SekiCollapsible, HTMLStencilElement {
         addEventListener<K extends keyof HTMLSekiCollapsibleElementEventMap>(type: K, listener: (this: HTMLSekiCollapsibleElement, ev: SekiCollapsibleCustomEvent<HTMLSekiCollapsibleElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -5576,6 +5588,7 @@ declare global {
     interface HTMLSekiCommandElementEventMap {
         "sekiValueChange": string;
         "sekiSelect": string;
+        "sekiContextChange": void;
     }
     /**
      * Command root component - command palette for navigation
@@ -5775,6 +5788,7 @@ declare global {
     };
     interface HTMLSekiDialogElementEventMap {
         "sekiOpenChange": boolean;
+        "sekiContextChange": void;
     }
     /**
      * Dialog root component for modal dialogs
@@ -5927,6 +5941,7 @@ declare global {
         "drawerClose": void;
         "drawerSnap": { point: number };
         "sekiOpenChange": boolean;
+        "sekiContextChange": void;
     }
     /**
      * seki-drawer: Mobile-friendly drawer component with swipe gestures
@@ -7093,6 +7108,7 @@ declare global {
     };
     interface HTMLSekiPopoverElementEventMap {
         "sekiOpenChange": boolean;
+        "sekiContextChange": void;
     }
     /**
      * Popover component - floating content triggered by click
@@ -7388,6 +7404,7 @@ declare global {
         "sheetOpen": void;
         "sheetClose": void;
         "sekiOpenChange": boolean;
+        "sekiContextChange": void;
     }
     /**
      * seki-sheet: Root sheet component (slide-out panel)
@@ -8350,6 +8367,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "defaultOpen"?: boolean;
+        /**
+          * Internal: notifies alert dialog parts that `_alertDialogContext` changed. Not part of the public API; listen to `sekiOpenChange` instead.
+         */
+        "onSekiContextChange"?: (event: SekiAlertDialogCustomEvent<void>) => void;
         /**
           * Emitted when open state changes
          */
@@ -9308,6 +9329,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "disabled"?: boolean;
+        /**
+          * Internal: notifies collapsible parts that `_collapsibleContext` changed. Not part of the public API; listen to `sekiOpenChange` instead.
+         */
+        "onSekiContextChange"?: (event: SekiCollapsibleCustomEvent<void>) => void;
         /**
           * Emitted when open state changes
          */
@@ -9476,6 +9501,10 @@ declare namespace LocalJSX {
           * @default true
          */
         "filter"?: boolean;
+        /**
+          * Internal: notifies command parts (input, items, groups, empty state) that `_commandContext` changed. Not part of the public API; listen to `sekiValueChange` instead.
+         */
+        "onSekiContextChange"?: (event: SekiCommandCustomEvent<void>) => void;
         /**
           * Emitted when an item is selected
          */
@@ -9641,6 +9670,11 @@ declare namespace LocalJSX {
           * @default false
          */
         "expandable"?: boolean;
+        /**
+          * Callback to fetch data. Set it as a JS property. Assigning or replacing it (re)loads the table. Must be a
+          * @Prop : in the lazy-loader build only decorated members are proxied from the host element to the instance.
+         */
+        "fetchData"?: FetchDataCallback;
         /**
           * Show loading state
           * @default false
@@ -9697,6 +9731,11 @@ declare namespace LocalJSX {
           * @default '[25, 50, 100]'
          */
         "pageSizeOptions"?: string | number[];
+        /**
+          * Callback to render expanded row content (must be a
+          * @Prop , see fetchData)
+         */
+        "renderExpandedRow"?: RenderExpandedRowCallback;
         /**
           * Fixed row height for virtualization
           * @default 48
@@ -9839,6 +9878,10 @@ declare namespace LocalJSX {
           * @default true
          */
         "modal"?: boolean;
+        /**
+          * Internal: notifies dialog parts (content, overlay, title, description) that `_dialogContext` changed. Not part of the public API; listen to `sekiOpenChange` instead.
+         */
+        "onSekiContextChange"?: (event: SekiDialogCustomEvent<void>) => void;
         /**
           * Emitted when open state changes
          */
@@ -9950,6 +9993,10 @@ declare namespace LocalJSX {
           * Emitted when the drawer snaps to a point
          */
         "onDrawerSnap"?: (event: SekiDrawerCustomEvent<{ point: number }>) => void;
+        /**
+          * Internal: notifies seki-drawer-content that `_drawerContext` changed. Not part of the public API; listen to `sekiOpenChange` instead.
+         */
+        "onSekiContextChange"?: (event: SekiDrawerCustomEvent<void>) => void;
         /**
           * Emitted whenever the open state changes. Matches the dialog/popover/collapsible event shape so a consumer can listen to one event name across every overlay.
          */
@@ -10225,7 +10272,7 @@ declare namespace LocalJSX {
     }
     interface SekiFieldLabel {
         /**
-          * ID of the form control this label is for Sets the `for` attribute on the label element
+          * ID of the form control this label is for Resolved in the label's own root node (not this component's shadow root), so it reaches light-DOM controls. Falls back to the control nested in the label.
          */
         "htmlFor"?: string;
         /**
@@ -10628,7 +10675,7 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * The ID of the form element this label is associated with. Maps to the `htmlFor` attribute on the inner `<label>` element.
+          * The ID of the form element this label is associated with. Resolved in the label's own root node (document or shadow root), not in this component's shadow root, so it reaches light-DOM controls. Without it, the first control nested inside the label is used.
          */
         "for"?: string;
         /**
@@ -11424,6 +11471,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "defaultOpen"?: boolean;
+        /**
+          * Internal: notifies popover parts that `_popoverContext` changed. Not part of the public API; listen to `sekiOpenChange` instead.
+         */
+        "onSekiContextChange"?: (event: SekiPopoverCustomEvent<void>) => void;
         /**
           * Emitted when open state changes
          */
@@ -11864,6 +11915,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "defaultOpen"?: boolean;
+        /**
+          * Internal: notifies seki-sheet-content that `_sheetContext` changed. Not part of the public API; listen to `sekiOpenChange` instead.
+         */
+        "onSekiContextChange"?: (event: SekiSheetCustomEvent<void>) => void;
         /**
           * Emitted whenever the open state changes. Matches the dialog/popover/collapsible event shape so a consumer can listen to one event name across every overlay.
          */

package/dist/types/utils/context-bridge.d.ts

@@ -3,10 +3,25 @@
  *
  * Generalizes the "parent publishes state onto its host element + child
  * subscribes via closest()" pattern used by compound components (select,
- * toggle-group, combobox, ...). Each parent calls publishContext() from its
- * updateContextOnElement()-equivalent method; each child calls
- * subscribeToContextChange() once in componentDidLoad() and the returned
- * unsubscribe() in disconnectedCallback().
+ * toggle-group, combobox, dialog, popover, ...).
+ *
+ * Parent (provider) contract:
+ *   - call publishContext() from componentWillLoad(), so the context exists
+ *     before any child renders for the first time, and
+ *   - call it again on every state change, including changes that arrive as a
+ *     @Prop assignment (@Watch) rather than through a @Method or user input.
+ *
+ * Child (consumer) contract — use a ContextConsumer:
+ *   - call connect(this.el) from connectedCallback() (runs before the first
+ *     render, and again after the element is moved to a new parent), and
+ *   - call disconnect() from disconnectedCallback().
+ *   connect() invokes the callback once immediately, so a child that
+ *   upgrades after its parent already published still starts from the current
+ *   state; a child that upgrades before its parent (one-module-per-tag
+ *   loading, #314) hears the parent's first publish from componentWillLoad().
+ *
+ * subscribeToContextChange() is the older listener-only form (no immediate
+ * read, light-DOM closest() only); prefer ContextConsumer for new code.
  *
  * Extracted after the same bug (child freezes at mount-time state because
  * nothing told it the parent changed) was independently fixed three times
@@ -43,3 +58,52 @@ export declare function subscribeToContextChange(el: HTMLElement, parentSelector
     parent: HTMLElement | null;
     unsubscribe: () => void;
 };
+/**
+ * Nearest ancestor matching `selector`, continuing past shadow roots: when the
+ * element's own tree has no match, the search resumes from the shadow host.
+ * This lets a part rendered inside another component's shadow tree still find
+ * the provider that wraps that component.
+ */
+export declare function findContextProvider(el: Element, selector: string): HTMLElement | null;
+/**
+ * Child-side: tracks one provider (see findContextProvider) for a part.
+ *
+ *   private dialog = new ContextConsumer<DialogContext>('seki-dialog', '_dialogContext', () => this.sync());
+ *   connectedCallback() { this.dialog.connect(this.el); }
+ *   disconnectedCallback() { this.dialog.disconnect(); }
+ *
+ * connect() finds the provider, starts listening for its context-change
+ * notifications and calls `onChange` once right away, so the part starts from
+ * whatever is already published. `parent` and `context` are already set when
+ * that first call happens. Calling connect() from connectedCallback runs it
+ * before the first render and again after the part is moved to another
+ * provider.
+ *
+ * `onChange` gets no event payload by design (see SEKI_CONTEXT_CHANGE_EVENT):
+ * it reads the live `context`. Notifications bubbling up from a nested
+ * provider are ignored; only events dispatched by this part's own provider
+ * host (or retargeted to it from that host's shadow tree) count.
+ *
+ * Works whether or not the provider element has been upgraded yet: the
+ * listener sits on the element itself, so the provider's first
+ * publishContext() from componentWillLoad() reaches it.
+ */
+export declare class ContextConsumer<T> {
+    private readonly parentSelector;
+    private readonly propertyName;
+    private readonly onChange;
+    private provider;
+    constructor(parentSelector: string, propertyName: string, onChange: (context: T | null) => void);
+    /** The provider element found by the last connect(), or null. */
+    get parent(): HTMLElement | null;
+    /** The provider's current context, or null when there is none yet. */
+    get context(): T | null;
+    connect(host: HTMLElement): void;
+    disconnect(): void;
+    private handleEvent;
+}
+/**
+ * Read a context object a provider published with publishContext(). Returns
+ * null when there is no provider or it has not published yet.
+ */
+export declare function readContext<T>(parent: Element | null | undefined, propertyName: string): T | null;

package/dist/types/utils/form-control.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared form participation for every `formAssociated` SekiUI control.
+ *
+ * One `FormControl` per component instance owns the four things that kept
+ * drifting apart between components:
+ *
+ *  1. the submitted value          -> `internals.setFormValue(...)`
+ *  2. constraint validation        -> `internals.setValidity(...)`
+ *  3. the validity API on the host -> `validity`, `validationMessage`,
+ *                                     `willValidate`, `checkValidity()`,
+ *                                     `reportValidity()`
+ *  4. lifecycle callbacks          -> reset (back to the value captured at
+ *                                     load), disabled, state restore
+ *
+ * Usage inside a component:
+ *
+ * ```ts
+ * private form!: FormControl<string>;
+ *
+ * componentWillLoad() {
+ *   this.form = new FormControl(this.el, this.internals, { ...options });
+ *   this.form.captureInitial(this.value);
+ *   this.form.sync();
+ * }
+ * formResetCallback() { this.form?.reset(); }
+ * formDisabledCallback(d: boolean) { this.form?.setFieldsetDisabled(d); }
+ * formStateRestoreCallback(s: FormControlState) { this.form?.restoreState(s); }
+ * ```
+ *
+ * ## Why plain host members and not `@Method()`
+ *
+ * Stencil `@Method()`s are always async: `el.checkValidity()` would return a
+ * `Promise`, which is truthy, so the idiomatic `if (!el.checkValidity())` would
+ * silently never fire. Native parity (`validity`, `willValidate` and
+ * `validationMessage` are synchronous reads) matters more than Stencil's method
+ * proxy, so the helper defines the members directly on the host element. That
+ * works in every build target (lazy loader, CDN and custom-elements) because the
+ * host is a real `HTMLElement` instance. The one limitation is that, like any
+ * Stencil API, the members exist once the component has loaded, not before the
+ * lazy loader has hydrated the element; `form.checkValidity()` and form
+ * submission go through `ElementInternals` and are always correct.
+ */
+export type FormControlState = string | File | FormData | null;
+/**
+ * The members every form control gains on its host element. Stencil's generated
+ * `HTMLSeki*Element` types cannot be augmented with them (the generated
+ * `ariaLabel` typing clashes under interface merging), so TypeScript consumers
+ * that want typed access cast: `(el as HTMLSekiInputElement & ValidatableElement)`.
+ */
+export interface ValidatableElement {
+    readonly validity: ValidityState;
+    readonly validationMessage: string;
+    readonly willValidate: boolean;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+}
+type NativeControl = HTMLInputElement | HTMLTextAreaElement;
+export interface FormControlOptions<T> {
+    /** The value to submit. `null` means "contribute nothing". Not called while disabled. */
+    getFormValue: () => string | FormData | null;
+    /** True when the control currently holds no value (drives `valueMissing`). */
+    isEmpty: () => boolean;
+    /** Put the control back to a captured initial value. Must update its own state. */
+    restore: (initial: T) => void;
+    /** Apply a value handed back by the browser (history navigation / autofill). */
+    restoreState?: (state: FormControlState) => void;
+    isRequired?: () => boolean;
+    isDisabled?: () => boolean;
+    /** Read-only controls still submit but are barred from constraint validation. */
+    isReadonly?: () => boolean;
+    /** Message for `valueMissing`. Browsers do not expose their localized ones. */
+    requiredMessage?: string;
+    /** The focusable element the browser should focus / anchor its bubble to. */
+    getAnchor?: () => HTMLElement | null | undefined;
+    /**
+     * Constraints beyond `valueMissing` that the component models itself
+     * (e.g. a date outside min/max). Evaluated only when the value is present.
+     */
+    getConstraints?: () => {
+        flags: ValidityStateFlags;
+        message: string;
+    } | null | undefined;
+    /**
+     * An inner native `<input>`/`<textarea>`. When present its own validity
+     * (required, minlength, pattern, type=email, min/max, ...) is mirrored onto the
+     * host, so the control inherits every constraint the platform already models and
+     * the browser's localized message.
+     */
+    getNativeControl?: () => NativeControl | null | undefined;
+}
+export declare class FormControl<T = unknown> {
+    private readonly host;
+    private readonly internals;
+    private readonly opts;
+    private initial;
+    private hasInitial;
+    private fieldsetDisabled;
+    constructor(host: HTMLElement, internals: ElementInternals | undefined, opts: FormControlOptions<T>);
+    /** Remember the value the control has at load time; `reset()` restores it. */
+    captureInitial(value: T): void;
+    /** Push the current value and validity to the form. Call after any state change. */
+    sync(): void;
+    /** Body of `formResetCallback`: restore the initial value, then re-sync. */
+    reset(): void;
+    /** Body of `formDisabledCallback` (a `<fieldset disabled>` ancestor or the host attribute). */
+    setFieldsetDisabled(disabled: boolean): void;
+    /** Body of `formStateRestoreCallback`. */
+    restoreState(state: FormControlState): void;
+    private get disabled();
+    private applyValidity;
+    /**
+     * Define the native validity members on the host. They delegate to
+     * `ElementInternals`, so the browser fires `invalid`, matches `:invalid` and
+     * shows its bubble exactly as for a built-in control.
+     */
+    private installHostApi;
+}
+/**
+ * Activation behaviour for a form-associated *button* host (`seki-button`,
+ * `seki-attachment-action`). The real `<button>` lives in a shadow root, so its
+ * form owner is null and the browser never submits or resets anything for it.
+ * The host is form-associated instead, so we act on `internals.form` ourselves:
+ *
+ *  - `submit` -> `form.requestSubmit()` (keeps the `submit` event and constraint
+ *    validation, unlike `form.submit()`)
+ *  - `reset`  -> `form.reset()`
+ *
+ * Native buttons run their activation behaviour *after* the click event has
+ * finished dispatching, and skip it when a listener called `preventDefault()`.
+ * To match, the action is deferred one task so consumer click listeners (which
+ * run after ours while the event bubbles) can still cancel it.
+ *
+ * Limitation: `SubmitEvent.submitter` is `null`, because `requestSubmit()` only
+ * accepts a native submit button as the submitter.
+ */
+export declare function activateFormButton(event: Event, type: 'button' | 'submit' | 'reset', internals: ElementInternals | undefined, disabled: boolean): void;
+export {};

package/dist/types/utils/label-association.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Label association for `seki-label` and `seki-field-label`.
+ *
+ * ## Why this exists
+ *
+ * Both labels render their text inside a shadow root. A native `<label for>`
+ * resolves its `for` id inside the tree the `<label>` lives in, so a `<label>`
+ * in our shadow root can never reach a control in the page's light DOM: clicks
+ * did nothing and the control had no accessible name (#329).
+ *
+ * The host element (`<seki-label>`) *does* live in the consumer's tree, so the
+ * wiring is done from the host in script, resolving the id against
+ * `host.getRootNode()` (the label's own root, which is where an author expects
+ * `for` to point, also when the label sits inside another component's shadow
+ * root together with its control).
+ *
+ * ## Behaviour
+ *
+ * - **Activation**: a click on the label forwards to the target the way a native
+ *   label would. Toggles (checkbox, switch, radio) are clicked, text-like
+ *   controls are focused. A click that originated on the control itself (the
+ *   wrapping form `<seki-label><seki-checkbox/> Text</seki-label>`) is ignored so
+ *   the control never toggles twice.
+ * - **Accessible name**: a shadow-DOM control hides its real focusable element
+ *   (`<button role="checkbox">`, `<input>`, ...) inside its own shadow root, and
+ *   an `aria-labelledby` id reference cannot cross a shadow boundary, so
+ *   pointing the host at the label would not name the inner element. SekiUI
+ *   controls all forward their `aria-label` attribute to that inner element, so
+ *   for them the label text is passed through as `aria-label`. For native
+ *   elements the reference does resolve, so we use `aria-labelledby` and the
+ *   name tracks the label's live content.
+ *   Anything the author set explicitly (`aria-label`, `aria-labelledby`) is
+ *   never overwritten; we only manage values we wrote ourselves, tracked with a
+ *   marker attribute so they can be updated and cleaned up.
+ *   `ElementInternals.ariaLabelledByElements` is deliberately not used: it is
+ *   unavailable in Firefox and older Safari, and cannot reach the inner element
+ *   of a shadow-DOM control either.
+ */
+export declare class LabelBinding {
+    private readonly host;
+    private readonly getFor;
+    private target;
+    private observer?;
+    constructor(host: HTMLElement, getFor: () => string | undefined);
+    /** Resolve the control this label is for, in the label's own root. */
+    resolveTarget(): HTMLElement | null;
+    /** Label text, without the text of a control nested inside the label. */
+    private labelText;
+    /** (Re)apply the accessible name. Call on load, `for` change and slot change. */
+    sync(): void;
+    /** Remove anything this binding wrote on the current target. */
+    release(): void;
+    /** Re-sync when the control is added after the label (async rendering). */
+    observe(): void;
+    disconnect(): void;
+    /** Forward a click on the label to its control, as a native label would. */
+    handleClick(event: Event): void;
+}