tyrell-components 1.0.0-RC13 → 1.0.0-RC15

package/lib/components/select.d.ts

@@ -1,57 +1,18 @@
 /**
- * TySelect Web Component
- *
- * The select control — replaces ty-dropdown and ty-multiselect.
- *
- * Cardinality (native <select> semantics):
- * - default: SINGLE select — scalar value, picking an option closes the popup
- * - `multiple`: multi select — comma value / repeated FormData entries,
- *   options toggle and the popup stays open
- *
- * Skins:
- * - default: form FIELD — full width, --ty-input-* tokens, matches ty-input;
- *   shows the selected label(s) inline
- * - `compact`: content-hugging trigger for toolbars/filter bars; single shows
- *   the selected label, multiple shows placeholder + count badge (pair with
- *   <ty-selected-options>)
- * - slot="trigger": consumer skin — replaces field/compact chrome entirely,
- *   behavior/ARIA/form participation unchanged
- *
- * - ty-option children (ty-tag also accepted)
- * - Desktop popup with smart positioning, mobile full-screen modal
- * - Search / external-search / debounce, keyboard navigation
- * - Form association: single submits one entry, multiple submits repeated
- *   `name=` entries (HTMX-ready)
- * - change event detail: { value, values, items: [{value, label, flavor}], action, item }
- *   (`value` is a scalar for single, array for multiple)
- *
- * @example
- * ```html
- * <!-- Single select, field skin -->
- * <ty-select label="Robot" name="robot">
- *   <ty-option value="bobo">Bobo Robot</ty-option>
- *   <ty-option value="eywa">EYWA Dataset Example</ty-option>
- * </ty-select>
- *
- * <!-- Multi select, compact skin + out-of-band chips -->
- * <ty-select multiple compact label="Robots" name="robots" id="robots">...</ty-select>
- * <ty-selected-options for="robots"></ty-selected-options>
- * ```
+ * TySelect Web Component — THE select control (replaces ty-dropdown/ty-multiselect).
+ * Cardinality follows native <select>: default single (scalar value, picking closes
+ * the popup), `multiple` toggles options and submits repeated `name=` FormData entries.
+ * Skins: default form field, `compact` content-hugging trigger, slot="trigger" custom.
  */
 import type { Flavor, Size } from "../types/common.js";
+import { type Placement } from "../utils/positioning.js";
 import { TyComponent } from "../base/ty-component.js";
 import type { PropertyChange } from "../utils/property-manager.js";
-/**
- * Tag data structure
- */
 interface TagData {
     value: string;
     text: string;
     element: HTMLElement;
 }
-/**
- * Component state structure
- */
 interface SelectState {
     open: boolean;
     search: string;
@@ -145,23 +106,27 @@ export declare class TySelect extends TyComponent<SelectState> {
             };
             coerce: (v: any) => "none" | "slug";
         };
-        searchable: {
-            type: "string";
+        notSearchable: {
+            type: "boolean";
             visual: boolean;
-            default: string;
-            coerce: (v: any) => "auto" | "always" | "never";
+            default: boolean;
         };
         align: {
             type: "string";
             visual: boolean;
             default: string;
             validate: (v: any) => boolean;
-            coerce: (v: any) => "start" | "end";
+            coerce: (v: any) => "start" | "end" | "center";
         };
-        size: {
+        placement: {
             type: "string";
             visual: boolean;
             default: string;
+        };
+        size: {
+            type: "string";
+            visual: boolean;
+            default: Size;
             validate: (v: any) => boolean;
             coerce: (v: any) => any;
         };
@@ -176,6 +141,11 @@ export declare class TySelect extends TyComponent<SelectState> {
             visual: boolean;
             default: string;
         };
+        "selected-label": {
+            type: "string";
+            visual: boolean;
+            default: string;
+        };
         "no-options-message": {
             type: "string";
             visual: boolean;
@@ -204,11 +174,12 @@ export declare class TySelect extends TyComponent<SelectState> {
     private _externalSearch;
     private _allowCreate;
     private _createTransform;
-    private _searchable;
+    private _notSearchable;
     private _loading;
     private _scrollLockId;
     private _size;
     private _availableLabel;
+    private _selectedLabel;
     private _noOptionsMessage;
     private _state;
     private _stubClickHandler;
@@ -223,22 +194,12 @@ export declare class TySelect extends TyComponent<SelectState> {
     private _selectedClone;
     private _customFlavorSheet;
     constructor();
-    /**
-     * Called when component is connected to DOM
-     * TyComponent handles property capture automatically
-     */
+    /** TyComponent handles property capture automatically. */
     protected onConnect(): void;
     /** Custom (non-built-in) flavors — see utils/flavor-sheet.ts. */
     private _syncCustomFlavor;
-    /**
-     * Called when component is disconnected from DOM
-     * Clean up event listeners and timers
-     */
     protected onDisconnect(): void;
-    /**
-     * Called when properties change
-     * Handle state synchronization BEFORE render
-     */
+    /** Handle state synchronization BEFORE render. */
     protected onPropertiesChanged(changes: PropertyChange[]): void;
     /**
      * Toggle the loading visual state on the open popup.
@@ -247,27 +208,38 @@ export declare class TySelect extends TyComponent<SelectState> {
      * take effect on the next loading toggle.
      */
     private applyLoadingState;
-    /**
-     * Get the form value for this component
-     * Returns FormData with multiple entries (HTMX standard)
-     */
+    /** Form value: a plain entry for single, FormData with repeated entries for multiple (HTMX standard). */
     protected getFormValue(): FormDataEntryValue | FormData | null;
-    /**
-     * Parse select value (comma-separated string to array)
-     */
     private parseValue;
+    /** Initialize component state from the value property / pre-selected children. */
+    private initializeState;
     /**
-     * Initialize component state from attributes
-     * Reads from both property and attribute (like ClojureScript version)
+     * Declarative init: no `value` attribute, but markup pre-marked one or more
+     * options `selected` — native <select> semantics. This is the ONE place
+     * selection is read FROM the DOM rather than treated as a rendering of
+     * state (see getSelectedValues()): it seeds initial state, once. After
+     * this, `value` rules — flipping an option's `selected` property later
+     * does nothing, same as native.
+     *
+     * Called from initializeState() at connect AND from the child observer:
+     * a real HTML parser upgrades a custom element the moment its start tag is
+     * seen, BEFORE its children exist — `<ty-select>` connects with zero
+     * `<ty-option>` children when it's part of the page's own markup (as
+     * opposed to an already-built fragment attached via innerHTML/appendChild,
+     * where children exist at connect). Calling this only at connect would
+     * silently miss every option parsed after that instant, which is the
+     * common case for markup that is literally in the page's initial HTML.
+     *
+     * Safe to call repeatedly: no-ops once `value` has ever been explicitly
+     * set (attribute or property) or state is already non-empty — including
+     * after a real `.clear()`, which removes `selected` from every option via
+     * syncSelectedTags, so there is nothing left here to (re-)seed from.
      */
-    private initializeState;
+    private resolveDeclarativeSelection;
     /**
      * Get all option elements from the component (ty-option preferred, ty-tag accepted)
      */
     private getTagElements;
-    /**
-     * Extract value and text from a ty-tag element
-     */
     private getTagData;
     /**
      * Select an option - attribute only. The option stays in the list with
@@ -279,12 +251,17 @@ export declare class TySelect extends TyComponent<SelectState> {
      */
     private deselectTag;
     /**
-     * Get array of currently selected values from tags (ALWAYS reads from DOM)
+     * Get the array of currently selected values.
+     *
+     * Reads STATE (`_state.selectedValues`), not the DOM: `value` is the
+     * selection, and an option's `selected` attribute is a rendering of it
+     * (written by syncSelectedTags below), never the other way round. This
+     * matters whenever options don't fully reflect the selection — external
+     * search legitimately has a selected value with no matching option
+     * present; a DOM scan would report empty and desync .value, `required`
+     * validation and the click-toggle logic from what's actually selected.
      */
     private getSelectedValues;
-    /**
-     * Sync tag selection states with desired values
-     */
     private syncSelectedTags;
     /**
      * role="option" for every current option/tag — separate from
@@ -294,18 +271,12 @@ export declare class TySelect extends TyComponent<SelectState> {
      * on every light-DOM change.
      */
     private ensureOptionRoles;
-    /**
-     * Central update function - synchronizes everything
-     * Uses TyComponent's property system for proper lifecycle
-     */
+    /** Central update function — synchronizes everything via TyComponent's property system. */
     private updateComponentValue;
     /**
      * Build rich item info for values, read off the matching option elements
      */
     private getSelectedItems;
-    /**
-     * Calculate and set dropdown position with smart direction detection
-     */
     private calculatePosition;
     private _setupOptionsScrollbar;
     private _destroyOptionsScrollbar;
@@ -319,19 +290,9 @@ export declare class TySelect extends TyComponent<SelectState> {
      * implement.
      */
     private openDropdown;
-    /**
-     * Close dropdown dialog (desktop mode)
-     */
     private closeDropdown;
-    /**
-     * Open mobile modal (mobile mode)
-     * Now using <dialog> element for native z-index management
-     */
+    /** Open mobile modal — <dialog> handles z-index natively. */
     private openMobileModal;
-    /**
-     * Close mobile modal (mobile mode)
-     * Now using <dialog> element for native management
-     */
     private closeMobileModal;
     private handleStubClick;
     /**
@@ -375,33 +336,19 @@ export declare class TySelect extends TyComponent<SelectState> {
     private handleSearchInput;
     private handleKeyboard;
     /**
-     * Filter tags based on search query
+     * Next tag index in `direction` (-1/1) that isn't disabled, wrapping
+     * around — mirrors handleTagClick's disabled check so keyboard nav can
+     * never land on/select what a click already refuses to. Returns -1 if
+     * every tag is disabled (or there are none).
      */
+    private nextEnabledTagIndex;
     private filterTags;
-    /**
-     * Update visibility of tags based on filtered list
-     */
     private updateTagVisibility;
-    /**
-     * Show/hide the dropdown options area
-     */
     private updateOptionsVisibility;
-    /**
-     * Clear all tag highlights
-     */
     private clearHighlights;
-    /**
-     * Highlight tag at specific index
-     */
     private highlightTag;
-    /**
-     * Dispatch search event for external search handling
-     * With optional debounce support
-     */
+    /** Dispatch the search event for external search handling, with optional debounce. */
     private dispatchSearchEvent;
-    /**
-     * Fire the actual search event
-     */
     private fireSearchEvent;
     /**
      * Dispatch lifecycle events for popup open/close.
@@ -410,14 +357,7 @@ export declare class TySelect extends TyComponent<SelectState> {
      */
     private fireOpenEvent;
     private fireCloseEvent;
-    /**
-     * Dispatch custom change event
-     */
     private dispatchChangeEvent;
-    /**
-     * Main render method (required by TyComponent)
-     * Delegates to mode-specific renderer
-     */
     protected render(): void;
     /**
      * Reflect constraint validation to the owning <form> via ElementInternals.
@@ -432,49 +372,36 @@ export declare class TySelect extends TyComponent<SelectState> {
      * default field chrome so the trigger is styled entirely by the consumer.
      */
     private setupTriggerSlot;
-    /**
-     * Setup event listeners
-     */
     private setupEventListeners;
-    /**
-     * Build CSS class list for stub
-     */
     private buildStubClasses;
-    /**
-     * Render desktop mode with dialog
-     */
     private renderDesktop;
-    /**
-     * Render mobile mode with full-screen modal
-     * Following dropdown.ts mobile structure
-     */
     private renderMobile;
-    /**
-     * Setup event listeners for mobile mode
-     * Using <dialog> element - backdrop clicks handled natively
-     */
     private setupMobileEventListeners;
-    /**
-     * Handle mobile stub click - open modal
-     */
     private handleMobileStubClick;
     /** Keyboard-open the (closed) mobile stub — see handleStubKeydown for why this is needed. */
     private handleMobileStubKeydown;
-    /**
-     * Handle mobile tag click - select and potentially close
-     */
     private handleMobileTagClick;
+    private updateMobileSelectedState;
     /**
-     * Update mobile options section state (count, empty state)
+     * Hand the dialog's spare vertical space to one section or the other. Only
+     * one can own it: on a phone there isn't enough height for two scrollable
+     * lists to both be usefully tall, so tapping a header trades the space
+     * rather than splitting it. Selecting from the list hands it back to
+     * "available" — you're still picking, so that's the list you want open.
      */
-    private updateMobileSelectedState;
+    private expandMobileSection;
     /**
-     * Update selection display: count badge next to the placeholder
+     * The selected values as dismissible chips, pinned above the available
+     * list so a long list can never scroll the current selection out of sight.
+     * Rebuilt wholesale: the strip is small, and diffing it would have to
+     * track chip identity for the sake of a handful of nodes.
      */
+    private renderMobileSelectedChips;
     /**
-     * Should the popup show a search row? external-search always (the input is
-     * the mechanism); searchable always/never wins otherwise; 'auto' shows it
-     * only when the option list is long enough to need filtering.
+     * Should the popup show a search row? external-search/allow-create pin it
+     * on (the input is the only way to get a query out at all), not-searchable
+     * forces it off, and otherwise it follows the list: shown once there are
+     * more options than fit without scrolling.
      */
     private shouldShowSearch;
     /**
@@ -532,19 +459,20 @@ export declare class TySelect extends TyComponent<SelectState> {
     set clearable(value: boolean);
     get required(): boolean;
     set required(value: boolean);
-    get searchable(): "auto" | "always" | "never";
-    set searchable(value: "auto" | "always" | "never" | boolean);
+    get notSearchable(): boolean;
+    set notSearchable(value: boolean);
     get externalSearch(): boolean;
     set externalSearch(value: boolean);
     get debounce(): number;
     set debounce(value: number | string);
     get size(): Size;
     set size(value: Size);
-    get align(): "start" | "end";
-    set align(value: "start" | "end");
+    get align(): "start" | "center" | "end";
+    set align(value: "start" | "center" | "end");
+    get placement(): Placement | "";
+    set placement(value: Placement | "");
     get flavor(): Flavor;
     set flavor(value: Flavor);
     get form(): HTMLFormElement | null;
 }
 export {};
-//# sourceMappingURL=select.d.ts.map