forge-select 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,3 @@
-type Handler = (...args: unknown[]) => void;
-
 interface Option {
     value: string;
     label: string;
@@ -10,6 +8,8 @@ interface Option {
     description?: string;
     /** Arbitrary payload for custom templates; ForgeSelect never reads it. */
     meta?: Record<string, unknown>;
+    /** Extra CSS class(es) applied to this option's rendered <li>. */
+    className?: string;
     /**
      * Nested options, making this a tree node. Purely additive: lists where
      * no option has `children` render and behave exactly as a flat list.
@@ -22,7 +22,13 @@ interface OptionGroup {
 }
 type DataItem = Option | OptionGroup;
 interface AjaxConfig {
-    url: string | ((query: string) => string);
+    /** GET endpoint. Optional when `request` supplies a custom transport. */
+    url?: string | ((query: string, page: number) => string);
+    /**
+     * Custom transport for POST/authenticated/GraphQL requests. Takes precedence
+     * over `url`; the returned payload is passed through `transform`.
+     */
+    request?: (query: string, page: number, signal: AbortSignal) => Promise<unknown>;
     params?: (query: string, page: number) => Record<string, unknown>;
     /** Debounce in milliseconds. Default 250. */
     debounce?: number;
@@ -55,12 +61,62 @@ interface ForgeSelectOptions {
     multiple?: boolean;
     clearable?: boolean;
     allowCreate?: boolean;
+    /**
+     * Let the user reorder selected tags by dragging them (mouse/touch/pen via
+     * Pointer Events), or via Alt+Left/Alt+Right when a tag has focus. Only
+     * meaningful when `multiple` is true. Default false — existing multi-select
+     * behavior and tag markup are unchanged when this is left off.
+     */
+    sortable?: boolean;
+    /**
+     * Multi-select only: close the dropdown immediately after each pick
+     * instead of staying open for further selections. Default false —
+     * existing multi-select behavior (stays open) is unchanged.
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Multi-select only: caps the number of selected values. Once reached,
+     * further picks (including via allowCreate) are ignored until one is
+     * removed. Only gates interactive selection — setValue() is not clamped.
+     * Default undefined (no limit).
+     */
+    maxSelections?: number;
     theme?: string;
     disabled?: boolean;
+    /**
+     * Marks the field as required for native form validation. When mounted on
+     * a real <select>, an empty selection blocks form submission and shows
+     * inline invalid styling, mirroring native <select required> behavior.
+     * On a plain-element mount this only sets aria-required (no native form
+     * to hook into). Default false.
+     */
+    required?: boolean;
     data?: DataItem[];
     ajax?: AjaxConfig;
     templateResult?: TemplateFn;
     templateSelection?: TemplateFn;
+    /**
+     * Custom match predicate, replacing the built-in label/description
+     * substring match. Receives the trimmed (not lowercased) query.
+     */
+    filterOption?: (option: Option, query: string) => boolean;
+    /**
+     * Hides results (showing a hint row instead) until the trimmed search
+     * query reaches this length. Also delays ajax requests until the
+     * threshold is met. Default 0 (no gate).
+     */
+    minSearchLength?: number;
+    /**
+     * Hides the search field when a local list contains fewer options than
+     * this threshold. AJAX-backed lists always keep search visible. Default 0.
+     */
+    minResultsForSearch?: number;
+    /**
+     * Dynamically disables an option, in addition to its static `disabled`
+     * field. Re-evaluated on every render, so it can react to external state
+     * (e.g. a quota) without rebuilding `data` via setData().
+     */
+    isOptionDisabled?: (option: Option) => boolean;
     /**
      * false = never virtualize. true or unset = virtualize automatically
      * once the list exceeds ~100 rows.
@@ -70,9 +126,42 @@ interface ForgeSelectOptions {
     itemHeight?: number;
     language?: string | Record<string, string>;
     plugins?: ForgeSelectPlugin[];
+    /**
+     * Opens the dropdown when the control receives keyboard focus (e.g. via
+     * Tab). Default false — focusing alone still requires Enter/Space/ArrowDown
+     * to open, matching existing behavior.
+     */
+    openOnFocus?: boolean;
+    /**
+     * Optional portal container for the dropdown, useful inside overflow-hidden
+     * modals and drawers. Accepts an element or selector. Default: the root.
+     */
+    dropdownParent?: HTMLElement | string;
 }
 type ForgeSelectValue = string | string[] | null;
-type ForgeSelectEvent = "change" | "open" | "close" | "search" | "clear";
+interface SetValueOptions {
+    /** Emit Forge Select's `change` event after updating. Default true. */
+    emitChange?: boolean;
+}
+interface MaximumSelectionEvent {
+    limit: number;
+    option: Option;
+}
+interface ForgeSelectEventMap {
+    change: ForgeSelectValue;
+    open: void;
+    close: void;
+    search: string;
+    clear: void;
+    error: Error;
+    select: Option;
+    unselect: Option;
+    create: Option;
+    reorder: string[];
+    maximum: MaximumSelectionEvent;
+}
+type ForgeSelectEvent = keyof ForgeSelectEventMap;
+type ForgeSelectEventHandler<E extends ForgeSelectEvent> = ForgeSelectEventMap[E] extends void ? () => void : (payload: ForgeSelectEventMap[E]) => void;
 
 declare class ForgeSelect {
     /** The original element ForgeSelect was mounted on. */
@@ -82,6 +171,7 @@ declare class ForgeSelect {
     private data;
     private selected;
     private selectedOptions;
+    private suppressNextTagClick;
     private emitter;
     private plugins;
     private uid;
@@ -92,6 +182,8 @@ declare class ForgeSelect {
     private dropdown;
     private searchInput;
     private list;
+    private liveRegion;
+    private portalHost;
     private isOpen;
     private isDisabled;
     private destroyed;
@@ -107,21 +199,75 @@ declare class ForgeSelect {
     private hasMore;
     private ajaxTimer;
     private ajaxRequestId;
+    private ajaxController;
     private remoteLoaded;
+    private loadError;
+    private originalDisplay;
+    private originalDisabled;
+    private nativeSelect;
+    private nativeForm;
+    private syncingNative;
+    /** Combines the static `disabled` field with the dynamic `isOptionDisabled` callback. */
+    private isOptionDisabled;
+    private pointerDownOnControl;
     private onDocumentMouseDown;
+    private onWindowResize;
+    private onAncestorScroll;
+    private onNativeInvalid;
+    private onNativeChange;
+    private applyNativeValues;
+    private onFormReset;
     constructor(target: string | HTMLElement, options?: ForgeSelectOptions);
     open(): void;
     close(): void;
+    /**
+     * Flips the dropdown above the control when there isn't enough room below
+     * but there is above. Recomputed on open() and on window resize — the
+     * dropdown is positioned absolutely inside the relatively-positioned root,
+     * so it already tracks the control correctly on page scroll without
+     * needing a scroll listener.
+     */
+    private positionDropdown;
     destroy(): void;
     getValue(): ForgeSelectValue;
-    setValue(value: ForgeSelectValue): void;
+    setValue(value: ForgeSelectValue, options?: SetValueOptions): void;
+    /**
+     * Replaces the option list after construction. An open dropdown re-renders
+     * immediately; a selection whose value isn't in the new data stays
+     * selected (rendered via the already-selected option's own label/avatar,
+     * the same fallback used for values selected from a stale ajax page).
+     */
+    setData(data: DataItem[]): void;
+    /**
+     * Multi-select only: selects every currently non-disabled option, including
+     * nested tree descendants and options inside groups. If `maxSelections` is
+     * set, stops once the cap is reached rather than exceeding it. A no-op for
+     * single-select.
+     */
+    selectAll(): void;
+    /** Clears every selection. Equivalent to `setValue(null)`. */
+    clearAll(): void;
     enable(): void;
     disable(): void;
-    on(event: ForgeSelectEvent, handler: Handler): void;
-    off(event: ForgeSelectEvent, handler: Handler): void;
+    on<E extends ForgeSelectEvent>(event: E, handler: ForgeSelectEventHandler<E>): void;
+    off<E extends ForgeSelectEvent>(event: E, handler: ForgeSelectEventHandler<E>): void;
+    /**
+     * The original target (a hidden native <select> or a plain mount div) can
+     * carry an accessible name via aria-label/aria-labelledby, or via a
+     * <label for> pointing at its id — but once `this.el` is display:none it
+     * drops out of the accessibility tree, so any such association silently
+     * stops reaching assistive tech unless we forward it onto the visible,
+     * interactive `this.control` ourselves.
+     */
+    private applyAccessibleName;
+    private shouldShowSearch;
+    private updateSearchVisibility;
     private buildDom;
     private bindEvents;
     private handleKeydown;
+    private canSelectOption;
+    private hasReachedMaximum;
+    private announceMaximum;
     private selectValue;
     private deselectValue;
     /**
@@ -132,17 +278,35 @@ declare class ForgeSelect {
      */
     private syncTreeAncestors;
     private clearSelection;
+    private allSelectableValues;
     private afterSelectionChange;
     private syncNativeSelect;
     private findOption;
+    private findOptionByLabel;
+    /** Selects an existing option matching `label` exactly, or creates and selects a new one. */
+    private createTag;
     private createFromQuery;
     private activateNavItem;
     private renderValue;
-    private renderTemplate;
+    /**
+     * Pointer-based (mouse/touch/pen) reorder for a single tag. Only the real
+     * dragged DOM node is moved during the gesture — a full renderValue()
+     * mid-drag would destroy it — so the reordered `this.selected` is only
+     * committed on release. The move/up listeners and pointer capture live on
+     * the stable `this.valueEl` container rather than the tag itself: `tag`
+     * gets repositioned via `insertBefore` during the drag, and browsers treat
+     * that reparenting as detaching the node, which silently drops pointer
+     * capture (and further move events) if it were captured on `tag`.
+     */
+    private bindTagDrag;
+    /** Alt+Left/Alt+Right on a focused tag: the keyboard-operable equivalent of dragging. */
+    private handleTagKeydown;
+    private focusTagByValue;
     private buildRows;
     private hasExactMatch;
     private usesVirtualScroll;
     private renderList;
+    private announceStatus;
     private renderRows;
     private renderRow;
     /**
@@ -153,6 +317,8 @@ declare class ForgeSelect {
      */
     private optionContent;
     private moveHighlight;
+    private focusNavIndex;
+    private navigateTree;
     private updateActiveDescendant;
     private scheduleRemoteLoad;
     /**
@@ -164,4 +330,4 @@ declare class ForgeSelect {
     private loadRemote;
 }
 
-export { type AjaxConfig, type DataItem, ForgeSelect, type ForgeSelectEvent, type ForgeSelectOptions, type ForgeSelectPlugin, type ForgeSelectValue, type Option, type OptionGroup, type TemplateFn, ForgeSelect as default };
+export { type AjaxConfig, type DataItem, ForgeSelect, type ForgeSelectEvent, type ForgeSelectEventHandler, type ForgeSelectEventMap, type ForgeSelectOptions, type ForgeSelectPlugin, type ForgeSelectValue, type MaximumSelectionEvent, type Option, type OptionGroup, type SetValueOptions, type TemplateFn, ForgeSelect as default };

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-type Handler = (...args: unknown[]) => void;
-
 interface Option {
     value: string;
     label: string;
@@ -10,6 +8,8 @@ interface Option {
     description?: string;
     /** Arbitrary payload for custom templates; ForgeSelect never reads it. */
     meta?: Record<string, unknown>;
+    /** Extra CSS class(es) applied to this option's rendered <li>. */
+    className?: string;
     /**
      * Nested options, making this a tree node. Purely additive: lists where
      * no option has `children` render and behave exactly as a flat list.
@@ -22,7 +22,13 @@ interface OptionGroup {
 }
 type DataItem = Option | OptionGroup;
 interface AjaxConfig {
-    url: string | ((query: string) => string);
+    /** GET endpoint. Optional when `request` supplies a custom transport. */
+    url?: string | ((query: string, page: number) => string);
+    /**
+     * Custom transport for POST/authenticated/GraphQL requests. Takes precedence
+     * over `url`; the returned payload is passed through `transform`.
+     */
+    request?: (query: string, page: number, signal: AbortSignal) => Promise<unknown>;
     params?: (query: string, page: number) => Record<string, unknown>;
     /** Debounce in milliseconds. Default 250. */
     debounce?: number;
@@ -55,12 +61,62 @@ interface ForgeSelectOptions {
     multiple?: boolean;
     clearable?: boolean;
     allowCreate?: boolean;
+    /**
+     * Let the user reorder selected tags by dragging them (mouse/touch/pen via
+     * Pointer Events), or via Alt+Left/Alt+Right when a tag has focus. Only
+     * meaningful when `multiple` is true. Default false — existing multi-select
+     * behavior and tag markup are unchanged when this is left off.
+     */
+    sortable?: boolean;
+    /**
+     * Multi-select only: close the dropdown immediately after each pick
+     * instead of staying open for further selections. Default false —
+     * existing multi-select behavior (stays open) is unchanged.
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Multi-select only: caps the number of selected values. Once reached,
+     * further picks (including via allowCreate) are ignored until one is
+     * removed. Only gates interactive selection — setValue() is not clamped.
+     * Default undefined (no limit).
+     */
+    maxSelections?: number;
     theme?: string;
     disabled?: boolean;
+    /**
+     * Marks the field as required for native form validation. When mounted on
+     * a real <select>, an empty selection blocks form submission and shows
+     * inline invalid styling, mirroring native <select required> behavior.
+     * On a plain-element mount this only sets aria-required (no native form
+     * to hook into). Default false.
+     */
+    required?: boolean;
     data?: DataItem[];
     ajax?: AjaxConfig;
     templateResult?: TemplateFn;
     templateSelection?: TemplateFn;
+    /**
+     * Custom match predicate, replacing the built-in label/description
+     * substring match. Receives the trimmed (not lowercased) query.
+     */
+    filterOption?: (option: Option, query: string) => boolean;
+    /**
+     * Hides results (showing a hint row instead) until the trimmed search
+     * query reaches this length. Also delays ajax requests until the
+     * threshold is met. Default 0 (no gate).
+     */
+    minSearchLength?: number;
+    /**
+     * Hides the search field when a local list contains fewer options than
+     * this threshold. AJAX-backed lists always keep search visible. Default 0.
+     */
+    minResultsForSearch?: number;
+    /**
+     * Dynamically disables an option, in addition to its static `disabled`
+     * field. Re-evaluated on every render, so it can react to external state
+     * (e.g. a quota) without rebuilding `data` via setData().
+     */
+    isOptionDisabled?: (option: Option) => boolean;
     /**
      * false = never virtualize. true or unset = virtualize automatically
      * once the list exceeds ~100 rows.
@@ -70,9 +126,42 @@ interface ForgeSelectOptions {
     itemHeight?: number;
     language?: string | Record<string, string>;
     plugins?: ForgeSelectPlugin[];
+    /**
+     * Opens the dropdown when the control receives keyboard focus (e.g. via
+     * Tab). Default false — focusing alone still requires Enter/Space/ArrowDown
+     * to open, matching existing behavior.
+     */
+    openOnFocus?: boolean;
+    /**
+     * Optional portal container for the dropdown, useful inside overflow-hidden
+     * modals and drawers. Accepts an element or selector. Default: the root.
+     */
+    dropdownParent?: HTMLElement | string;
 }
 type ForgeSelectValue = string | string[] | null;
-type ForgeSelectEvent = "change" | "open" | "close" | "search" | "clear";
+interface SetValueOptions {
+    /** Emit Forge Select's `change` event after updating. Default true. */
+    emitChange?: boolean;
+}
+interface MaximumSelectionEvent {
+    limit: number;
+    option: Option;
+}
+interface ForgeSelectEventMap {
+    change: ForgeSelectValue;
+    open: void;
+    close: void;
+    search: string;
+    clear: void;
+    error: Error;
+    select: Option;
+    unselect: Option;
+    create: Option;
+    reorder: string[];
+    maximum: MaximumSelectionEvent;
+}
+type ForgeSelectEvent = keyof ForgeSelectEventMap;
+type ForgeSelectEventHandler<E extends ForgeSelectEvent> = ForgeSelectEventMap[E] extends void ? () => void : (payload: ForgeSelectEventMap[E]) => void;
 
 declare class ForgeSelect {
     /** The original element ForgeSelect was mounted on. */
@@ -82,6 +171,7 @@ declare class ForgeSelect {
     private data;
     private selected;
     private selectedOptions;
+    private suppressNextTagClick;
     private emitter;
     private plugins;
     private uid;
@@ -92,6 +182,8 @@ declare class ForgeSelect {
     private dropdown;
     private searchInput;
     private list;
+    private liveRegion;
+    private portalHost;
     private isOpen;
     private isDisabled;
     private destroyed;
@@ -107,21 +199,75 @@ declare class ForgeSelect {
     private hasMore;
     private ajaxTimer;
     private ajaxRequestId;
+    private ajaxController;
     private remoteLoaded;
+    private loadError;
+    private originalDisplay;
+    private originalDisabled;
+    private nativeSelect;
+    private nativeForm;
+    private syncingNative;
+    /** Combines the static `disabled` field with the dynamic `isOptionDisabled` callback. */
+    private isOptionDisabled;
+    private pointerDownOnControl;
     private onDocumentMouseDown;
+    private onWindowResize;
+    private onAncestorScroll;
+    private onNativeInvalid;
+    private onNativeChange;
+    private applyNativeValues;
+    private onFormReset;
     constructor(target: string | HTMLElement, options?: ForgeSelectOptions);
     open(): void;
     close(): void;
+    /**
+     * Flips the dropdown above the control when there isn't enough room below
+     * but there is above. Recomputed on open() and on window resize — the
+     * dropdown is positioned absolutely inside the relatively-positioned root,
+     * so it already tracks the control correctly on page scroll without
+     * needing a scroll listener.
+     */
+    private positionDropdown;
     destroy(): void;
     getValue(): ForgeSelectValue;
-    setValue(value: ForgeSelectValue): void;
+    setValue(value: ForgeSelectValue, options?: SetValueOptions): void;
+    /**
+     * Replaces the option list after construction. An open dropdown re-renders
+     * immediately; a selection whose value isn't in the new data stays
+     * selected (rendered via the already-selected option's own label/avatar,
+     * the same fallback used for values selected from a stale ajax page).
+     */
+    setData(data: DataItem[]): void;
+    /**
+     * Multi-select only: selects every currently non-disabled option, including
+     * nested tree descendants and options inside groups. If `maxSelections` is
+     * set, stops once the cap is reached rather than exceeding it. A no-op for
+     * single-select.
+     */
+    selectAll(): void;
+    /** Clears every selection. Equivalent to `setValue(null)`. */
+    clearAll(): void;
     enable(): void;
     disable(): void;
-    on(event: ForgeSelectEvent, handler: Handler): void;
-    off(event: ForgeSelectEvent, handler: Handler): void;
+    on<E extends ForgeSelectEvent>(event: E, handler: ForgeSelectEventHandler<E>): void;
+    off<E extends ForgeSelectEvent>(event: E, handler: ForgeSelectEventHandler<E>): void;
+    /**
+     * The original target (a hidden native <select> or a plain mount div) can
+     * carry an accessible name via aria-label/aria-labelledby, or via a
+     * <label for> pointing at its id — but once `this.el` is display:none it
+     * drops out of the accessibility tree, so any such association silently
+     * stops reaching assistive tech unless we forward it onto the visible,
+     * interactive `this.control` ourselves.
+     */
+    private applyAccessibleName;
+    private shouldShowSearch;
+    private updateSearchVisibility;
     private buildDom;
     private bindEvents;
     private handleKeydown;
+    private canSelectOption;
+    private hasReachedMaximum;
+    private announceMaximum;
     private selectValue;
     private deselectValue;
     /**
@@ -132,17 +278,35 @@ declare class ForgeSelect {
      */
     private syncTreeAncestors;
     private clearSelection;
+    private allSelectableValues;
     private afterSelectionChange;
     private syncNativeSelect;
     private findOption;
+    private findOptionByLabel;
+    /** Selects an existing option matching `label` exactly, or creates and selects a new one. */
+    private createTag;
     private createFromQuery;
     private activateNavItem;
     private renderValue;
-    private renderTemplate;
+    /**
+     * Pointer-based (mouse/touch/pen) reorder for a single tag. Only the real
+     * dragged DOM node is moved during the gesture — a full renderValue()
+     * mid-drag would destroy it — so the reordered `this.selected` is only
+     * committed on release. The move/up listeners and pointer capture live on
+     * the stable `this.valueEl` container rather than the tag itself: `tag`
+     * gets repositioned via `insertBefore` during the drag, and browsers treat
+     * that reparenting as detaching the node, which silently drops pointer
+     * capture (and further move events) if it were captured on `tag`.
+     */
+    private bindTagDrag;
+    /** Alt+Left/Alt+Right on a focused tag: the keyboard-operable equivalent of dragging. */
+    private handleTagKeydown;
+    private focusTagByValue;
     private buildRows;
     private hasExactMatch;
     private usesVirtualScroll;
     private renderList;
+    private announceStatus;
     private renderRows;
     private renderRow;
     /**
@@ -153,6 +317,8 @@ declare class ForgeSelect {
      */
     private optionContent;
     private moveHighlight;
+    private focusNavIndex;
+    private navigateTree;
     private updateActiveDescendant;
     private scheduleRemoteLoad;
     /**
@@ -164,4 +330,4 @@ declare class ForgeSelect {
     private loadRemote;
 }
 
-export { type AjaxConfig, type DataItem, ForgeSelect, type ForgeSelectEvent, type ForgeSelectOptions, type ForgeSelectPlugin, type ForgeSelectValue, type Option, type OptionGroup, type TemplateFn, ForgeSelect as default };
+export { type AjaxConfig, type DataItem, ForgeSelect, type ForgeSelectEvent, type ForgeSelectEventHandler, type ForgeSelectEventMap, type ForgeSelectOptions, type ForgeSelectPlugin, type ForgeSelectValue, type MaximumSelectionEvent, type Option, type OptionGroup, type SetValueOptions, type TemplateFn, ForgeSelect as default };