forge-select 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -10,6 +10,11 @@ interface Option {
     description?: string;
     /** Arbitrary payload for custom templates; ForgeSelect never reads it. */
     meta?: Record<string, unknown>;
+    /**
+     * Nested options, making this a tree node. Purely additive: lists where
+     * no option has `children` render and behave exactly as a flat list.
+     */
+    children?: Option[];
 }
 interface OptionGroup {
     label: string;
@@ -17,11 +22,24 @@ interface OptionGroup {
 }
 type DataItem = Option | OptionGroup;
 interface AjaxConfig {
-    url: string | ((query: string) => string);
-    params?: (query: string) => Record<string, unknown>;
+    url: string | ((query: string, page: number) => string);
+    params?: (query: string, page: number) => Record<string, unknown>;
     /** Debounce in milliseconds. Default 250. */
     debounce?: number;
-    transform?: (response: unknown) => Option[];
+    /**
+     * Opt in to loading additional pages as the user scrolls near the bottom
+     * of the dropdown, instead of only reloading on search. Default false.
+     */
+    pagination?: boolean;
+    /**
+     * Return a plain array (page-replace behavior, unchanged from before
+     * `pagination` existed) or `{ options, hasMore }` so ForgeSelect knows
+     * whether to keep requesting further pages when `pagination` is true.
+     */
+    transform?: (response: unknown) => Option[] | {
+        options: Option[];
+        hasMore: boolean;
+    };
 }
 interface ForgeSelectPlugin {
     name: string;
@@ -37,6 +55,13 @@ 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;
     theme?: string;
     disabled?: boolean;
     data?: DataItem[];
@@ -54,7 +79,11 @@ interface ForgeSelectOptions {
     plugins?: ForgeSelectPlugin[];
 }
 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;
+}
+type ForgeSelectEvent = "change" | "open" | "close" | "search" | "clear" | "error";
 
 declare class ForgeSelect {
     /** The original element ForgeSelect was mounted on. */
@@ -64,6 +93,7 @@ declare class ForgeSelect {
     private data;
     private selected;
     private selectedOptions;
+    private suppressNextTagClick;
     private emitter;
     private plugins;
     private uid;
@@ -74,6 +104,7 @@ declare class ForgeSelect {
     private dropdown;
     private searchInput;
     private list;
+    private liveRegion;
     private isOpen;
     private isDisabled;
     private destroyed;
@@ -82,26 +113,56 @@ declare class ForgeSelect {
     private navItems;
     private highlightedIndex;
     private rowContentCache;
+    private expandedValues;
     private loading;
+    private loadingMore;
+    private page;
+    private hasMore;
     private ajaxTimer;
     private ajaxRequestId;
+    private ajaxController;
     private remoteLoaded;
+    private loadError;
+    private originalDisplay;
+    private originalDisabled;
+    private nativeSelect;
+    private nativeForm;
+    private syncingNative;
     private onDocumentMouseDown;
+    private onNativeChange;
+    private applyNativeValues;
+    private onFormReset;
     constructor(target: string | HTMLElement, options?: ForgeSelectOptions);
     open(): void;
     close(): void;
     destroy(): void;
     getValue(): ForgeSelectValue;
-    setValue(value: ForgeSelectValue): void;
+    setValue(value: ForgeSelectValue, options?: SetValueOptions): void;
     enable(): void;
     disable(): void;
     on(event: ForgeSelectEvent, handler: Handler): void;
     off(event: ForgeSelectEvent, handler: Handler): 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 buildDom;
     private bindEvents;
     private handleKeydown;
     private selectValue;
     private deselectValue;
+    /**
+     * Keeps every tree parent's own membership in `selected` consistent with
+     * its descendants (post-order, so parents see already-corrected children):
+     * a parent counts as selected only when `computeCheckState` says "all".
+     * No-op for data with no `children` anywhere.
+     */
+    private syncTreeAncestors;
     private clearSelection;
     private afterSelectionChange;
     private syncNativeSelect;
@@ -109,11 +170,25 @@ declare class ForgeSelect {
     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;
     /**
@@ -124,9 +199,17 @@ declare class ForgeSelect {
      */
     private optionContent;
     private moveHighlight;
+    private focusNavIndex;
+    private navigateTree;
     private updateActiveDescendant;
     private scheduleRemoteLoad;
+    /**
+     * Fires on every list scroll. Only acts when pagination is opted into via
+     * `ajax.pagination`; reads real scroll geometry rather than row counts so
+     * it works whether or not virtual scrolling is active for this list.
+     */
+    private maybeLoadNextPage;
     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 ForgeSelectOptions, type ForgeSelectPlugin, type ForgeSelectValue, type Option, type OptionGroup, type SetValueOptions, type TemplateFn, ForgeSelect as default };