vlist 2.2.0 → 2.3.0

package/dist/plugins/a11y/plugin.d.ts

@@ -9,5 +9,14 @@
  */
 import type { VListItem } from "../../types";
 import type { VListPlugin } from "../../core/types";
-export declare function a11y<T extends VListItem = VListItem>(): VListPlugin<T>;
+export interface A11yPluginConfig {
+    /**
+     * Whether this plugin handles arrow/Home/End/PageUp-Down/Enter/Space
+     * keyboard navigation. Default true. Set false to keep click-selection,
+     * focus management, and ARIA while letting an outer system own keyboard
+     * navigation (e.g. a global, focus-independent hotkey layer).
+     */
+    keyboard?: boolean;
+}
+export declare function a11y<T extends VListItem = VListItem>(config?: A11yPluginConfig): VListPlugin<T>;
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/search/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vlist - Search Domain
+ * Ready-to-use search bar with client-side filtering, match navigation,
+ * and `<mark>` highlighting.
+ */
+export { search, DEFAULT_SEARCH_TEXT, type SearchPluginConfig, type SearchPluginInstance, type SearchText, } from "./plugin";
+export { makeGetText, type FieldAccessor } from "./match";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/search/match.d.ts

@@ -0,0 +1,34 @@
+/**
+ * vlist/search — Matching & highlighting helpers
+ *
+ * Pure, DOM-light utilities used by the search plugin:
+ * - text extraction from items (field accessor or all string values)
+ * - substring matching
+ * - idempotent `<mark>` highlighting of a rendered element
+ */
+import type { VListItem } from "../../types";
+/** Field(s) to search — a property key or a custom accessor. */
+export type FieldAccessor<T> = string | ((item: T) => string);
+/**
+ * Build a text accessor for an item.
+ * - function: used as-is
+ * - string: reads `item[field]`
+ * - undefined: concatenates all string-valued properties
+ */
+export declare const makeGetText: <T extends VListItem>(field?: FieldAccessor<T>) => ((item: T) => string);
+/** Whether `text` contains `query` (query already normalized to the right case). */
+export declare const textMatches: (text: string, query: string, caseSensitive: boolean) => boolean;
+/**
+ * Remove all `<mark>` elements with `matchClass` inside `root`, replacing
+ * each with its text content. Adjacent text nodes are merged so the DOM
+ * returns to its pre-highlight state.
+ */
+export declare const clearHighlights: (root: HTMLElement, matchClass: string) => void;
+/**
+ * Wrap every occurrence of `query` inside `root`'s text nodes in
+ * `<mark class="${matchClass}">`. Existing marks are cleared first so
+ * the function is safe to call on every render commit — stale marks from
+ * a previous query are replaced, not accumulated.
+ */
+export declare const highlightElement: (root: HTMLElement, query: string, caseSensitive: boolean, matchClass: string) => void;
+//# sourceMappingURL=match.d.ts.map

package/dist/plugins/search/plugin.d.ts

@@ -0,0 +1,84 @@
+/**
+ * vlist — Search Plugin (RFC-008, Phase 1)
+ *
+ * A ready-to-use search bar with client-side filtering, match navigation, and
+ * `<mark>` highlighting. Operates at the data layer (no `setRenderFn`), so it
+ * composes with any layout.
+ *
+ * - **filter** mode (default): virtually hides non-matching items via
+ *   `setGetItemFn` + `setVirtualTotalFn` (non-destructive — clear restores).
+ * - **navigate** mode: keeps all items, scrolls between matches, highlights
+ *   the current one.
+ *
+ * Phase 2 (server-side search via `data()`, column-aware, fuzzy, query syntax)
+ * is out of scope here.
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+import { type FieldAccessor } from "./match";
+/**
+ * Consumer-facing UI text for the search bar (RFC-010 — Externalized UI Text).
+ * This is the plugin's entire human-language surface: static accessible names
+ * plus the dynamic counter formatters. All fields are optional; unset fields
+ * fall back to {@link DEFAULT_SEARCH_TEXT} (English). Consumers localizing for a
+ * non-English document should override these *and* set `lang` on the page.
+ */
+export interface SearchText {
+    /** Input placeholder + accessible name. */
+    placeholder?: string;
+    /** Accessible name for the clear (×) button. */
+    clear?: string;
+    /** Accessible name for the previous-match button (navigate mode). */
+    previous?: string;
+    /** Accessible name for the next-match button (navigate mode). */
+    next?: string;
+    /** Counter text when there are no matches. */
+    noResults?: string;
+    /** Counter text in filter mode — total match count. */
+    results?: (count: number) => string;
+    /** Counter text in navigate mode — current position within matches. */
+    position?: (current: number, total: number) => string;
+    /** Accessible name for the `role="search"` landmark. Unnamed when omitted. */
+    region?: string;
+}
+/**
+ * Default English UI text for the search plugin. The single, documented,
+ * fully-overridable language surface (RFC-010): the only place human-readable
+ * strings live in the library.
+ */
+export declare const DEFAULT_SEARCH_TEXT: Required<SearchText>;
+export interface SearchPluginConfig<T extends VListItem = VListItem> {
+    /** Hide non-matching items ("filter") or jump between matches ("navigate"). Default "filter". */
+    mode?: "filter" | "navigate";
+    /** Where to place the search bar. "none" = invisible, keyboard-only. Default "top". */
+    position?: "top" | "bottom" | "none";
+    /** Field(s) to search — a property key, accessor, or (default) all string values. */
+    field?: FieldAccessor<T>;
+    /** Case-sensitive matching. Default false. */
+    caseSensitive?: boolean;
+    /**
+     * Highlight matched substrings in rendered rows by wrapping them in
+     * `<mark class="{prefix}-search-match">`. Default `true`.
+     *
+     * - `false` — disable highlighting.
+     * - `{ within }` — restrict highlighting to descendants matching the CSS
+     *   selector (e.g. `".person__name"`) instead of the whole row. Useful when
+     *   the query can coincidentally appear in fields you didn't search.
+     */
+    highlight?: boolean | {
+        within?: string;
+    };
+    /** Minimum query length to trigger search. Default 1. */
+    minLength?: number;
+    /** Auto-close the search bar after N ms of inactivity (0 = never). Default 0. */
+    cancelTimeout?: number;
+    /** Visual style of the search bar. `"md3"` applies a Material Design 3 pill
+     *  (requires the search stylesheet). Default `"default"`. */
+    variant?: "default" | "md3";
+    /** Consumer-supplied UI text / localization. Falls back to {@link DEFAULT_SEARCH_TEXT}. */
+    text?: SearchText;
+}
+export interface SearchPluginInstance<T extends VListItem = VListItem> extends VListPlugin<T> {
+}
+export declare function search<T extends VListItem = VListItem>(config?: SearchPluginConfig<T>): SearchPluginInstance<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/search/searchbar.d.ts

@@ -0,0 +1,57 @@
+/**
+ * vlist/search — Search bar DOM
+ *
+ * A modular, MD3-aligned structure (mirrors mtrl `_search.scss`):
+ *
+ *   .{p}-search .{p}-search--bar .{p}-search--{top|bottom}   (role="search")
+ *   └── .{p}-search__container
+ *       ├── span.{p}-search__leading-icon       (magnifier — decorative)
+ *       ├── .{p}-search__input-wrapper
+ *       │   └── input.{p}-search__input
+ *       ├── span.{p}-search__counter              (match count — empty when idle)
+ *       ├── button.{p}-search__nav-prev           (navigate mode only)
+ *       ├── button.{p}-search__nav-next           (navigate mode only)
+ *       └── button.{p}-search__clear-button       (--hidden when empty)
+ *
+ * Per RFC-010, the bar carries no inline human-language text: all accessible
+ * names come from the `text` parameter (consumer-supplied, with English
+ * defaults resolved in the plugin). The leading magnifier is decorative
+ * (`aria-hidden`, not focusable, no accessible name) — the input is the
+ * meaningful control. The `role="search"` landmark is unnamed unless the
+ * consumer passes `text.region`.
+ *
+ * Invisible mode (`position: "none"`) renders no bar — the plugin drives the
+ * query from keystrokes only.
+ */
+export interface SearchBarCallbacks {
+    onInput(value: string): void;
+    onClear(): void;
+    onPrev(): void;
+    onNext(): void;
+    /** Forwarded keydown from the input (Enter / Escape / arrows). */
+    onKeydown(event: KeyboardEvent): void;
+}
+/**
+ * Resolved accessible names for the bar (consumer-supplied via the plugin's
+ * `text` config; the plugin fills English defaults). `region` is `""` when the
+ * search landmark should stay unnamed (the default).
+ */
+export interface SearchBarText {
+    placeholder: string;
+    clear: string;
+    previous: string;
+    next: string;
+    region: string;
+}
+export interface SearchBar {
+    readonly root: HTMLElement;
+    readonly input: HTMLInputElement;
+    setCounter(text: string): void;
+    /** Show/hide the prev/next buttons (navigate mode only). */
+    showNav(show: boolean): void;
+    focus(): void;
+    setValue(value: string): void;
+    destroy(): void;
+}
+export declare const createSearchBar: (parent: HTMLElement, before: HTMLElement | null, classPrefix: string, position: "top" | "bottom", text: SearchBarText, listId: string | undefined, cb: SearchBarCallbacks) => SearchBar;
+//# sourceMappingURL=searchbar.d.ts.map

package/dist/plugins/selection/plugin.d.ts

@@ -11,6 +11,13 @@ export interface SelectionPluginConfig {
     initial?: Array<string | number>;
     followFocus?: boolean;
     focusOnClick?: boolean;
+    /**
+     * Whether this plugin handles arrow/Home/End/PageUp-Down/Enter/Space
+     * keyboard navigation. Default true. Set false to keep click-selection and
+     * the selection model while letting an outer system own keyboard navigation
+     * (e.g. a global, focus-independent hotkey layer).
+     */
+    keyboard?: boolean;
 }
 export declare function selection<T extends VListItem = VListItem>(config?: SelectionPluginConfig): VListPlugin<T>;
 //# sourceMappingURL=plugin.d.ts.map

package/dist/size.json

@@ -1 +1 @@
-{"base":{"minified":"22.2","gzipped":"8.2","minBytes":22725,"gzBytes":8357},"a11y":{"minified":"25.2","gzipped":"9.3","minBytes":25848,"gzBytes":9486},"selection":{"minified":"30.8","gzipped":"10.7","minBytes":31532,"gzBytes":10910},"data":{"minified":"35.8","gzipped":"13.0","minBytes":36694,"gzBytes":13294},"scrollbar":{"minified":"29.3","gzipped":"10.2","minBytes":30038,"gzBytes":10423},"sortable":{"minified":"31.6","gzipped":"11.1","minBytes":32330,"gzBytes":11320},"groups":{"minified":"37.7","gzipped":"13.4","minBytes":38615,"gzBytes":13682},"scale":{"minified":"35.5","gzipped":"12.1","minBytes":36357,"gzBytes":12383},"page":{"minified":"24.6","gzipped":"8.9","minBytes":25211,"gzBytes":9146},"snapshots":{"minified":"25.9","gzipped":"9.4","minBytes":26486,"gzBytes":9663},"transition":{"minified":"29.0","gzipped":"10.0","minBytes":29660,"gzBytes":10236},"autosize":{"minified":"24.6","gzipped":"9.0","minBytes":25208,"gzBytes":9241},"grid":{"minified":"30.5","gzipped":"11.1","minBytes":31230,"gzBytes":11320},"table":{"minified":"41.7","gzipped":"14.4","minBytes":42719,"gzBytes":14765},"masonry":{"minified":"32.4","gzipped":"11.9","minBytes":33172,"gzBytes":12141},"tree":{"minified":"38.1","gzipped":"13.5","minBytes":39025,"gzBytes":13849}}
+{"base":{"minified":"22.5","gzipped":"8.3","minBytes":22998,"gzBytes":8485},"a11y":{"minified":"25.5","gzipped":"9.4","minBytes":26152,"gzBytes":9632},"selection":{"minified":"31.2","gzipped":"10.8","minBytes":31986,"gzBytes":11110},"data":{"minified":"36.2","gzipped":"13.1","minBytes":37020,"gzBytes":13429},"scrollbar":{"minified":"29.6","gzipped":"10.3","minBytes":30313,"gzBytes":10547},"sortable":{"minified":"31.8","gzipped":"11.2","minBytes":32604,"gzBytes":11439},"groups":{"minified":"38.3","gzipped":"13.6","minBytes":39267,"gzBytes":13901},"scale":{"minified":"36.5","gzipped":"12.5","minBytes":37365,"gzBytes":12768},"page":{"minified":"24.9","gzipped":"9.1","minBytes":25484,"gzBytes":9269},"snapshots":{"minified":"26.1","gzipped":"9.6","minBytes":26759,"gzBytes":9789},"transition":{"minified":"29.2","gzipped":"10.1","minBytes":29935,"gzBytes":10365},"autosize":{"minified":"24.9","gzipped":"9.1","minBytes":25481,"gzBytes":9367},"grid":{"minified":"31.0","gzipped":"11.3","minBytes":31754,"gzBytes":11532},"table":{"minified":"42.0","gzipped":"14.5","minBytes":42997,"gzBytes":14880},"masonry":{"minified":"33.4","gzipped":"12.2","minBytes":34165,"gzBytes":12538},"tree":{"minified":"38.5","gzipped":"13.6","minBytes":39386,"gzBytes":13975},"search":{"minified":"31.6","gzipped":"11.5","minBytes":32314,"gzBytes":11745}}

package/dist/types.d.ts

@@ -370,11 +370,23 @@ export interface TreeState {
     isLastChild: boolean;
     loading: boolean;
 }
+/** Search-specific state available in templates when the search plugin is active */
+export interface SearchState {
+    /** Whether this item matches the current query */
+    matched: boolean;
+    /** Current search query (empty string when no search is active) */
+    query: string;
+    /** This item's position in the match list (-1 if not matched) */
+    matchIndex: number;
+    /** Whether this is the currently focused match (navigate mode) */
+    isCurrent: boolean;
+}
 /** State passed to template */
 export interface ItemState {
     selected: boolean;
     focused: boolean;
     tree?: TreeState;
+    search?: SearchState;
 }
 /** Selection mode */
 export type SelectionMode = "none" | "single" | "multiple";
@@ -601,6 +613,23 @@ export interface VListEvents<T extends VListItem = VListItem> extends EventMap {
         item: T;
         error: unknown;
     };
+    /** Search bar opened / focused */
+    "search:open": undefined;
+    /** Search bar closed and query cleared */
+    "search:close": undefined;
+    /** Query or results changed */
+    "search:change": {
+        query: string;
+        matches: number;
+        total: number;
+    };
+    /** Navigated to a match (navigate mode) */
+    "search:match": {
+        index: number;
+        item: T | undefined;
+        matchIndex: number;
+        matches: number;
+    };
     /** Destroy — fired just before the instance is torn down */
     destroy: undefined;
 }

package/dist/vlist-search.css

@@ -0,0 +1 @@
+:root{--vlist-search-match-bg:#fde047;--vlist-search-match-current-bg:#f59e0b;--vlist-search-md3-surface:#ececf1;--vlist-search-md3-state:rgba(0,0,0,0.08)}[data-theme-mode="dark"]{--vlist-search-match-bg:#92710b;--vlist-search-match-current-bg:#b45309;--vlist-search-md3-surface:#2b3039;--vlist-search-md3-state:rgba(255,255,255,0.08)}@media (prefers-color-scheme:dark){:root:not([data-theme-mode="light"]):not([data-theme-mode="dark"]){--vlist-search-match-bg:#92710b;--vlist-search-match-current-bg:#b45309;--vlist-search-md3-surface:#2b3039;--vlist-search-md3-state:rgba(255,255,255,0.08)}}.dark{--vlist-search-match-bg:#92710b;--vlist-search-match-current-bg:#b45309;--vlist-search-md3-surface:#2b3039;--vlist-search-md3-state:rgba(255,255,255,0.08)}.vlist--has-search{display:flex;flex-direction:column}.vlist--has-search .vlist-viewport{flex:1 1 auto;min-height:0}.vlist-search{flex:0 0 auto;box-sizing:border-box;display:flex}.vlist-search__container{display:flex;align-items:center;gap:6px;width:100%;box-sizing:border-box;padding:6px 8px;background-color:var(--vlist-bg);border-bottom:1px solid var(--vlist-border)}.vlist-search--bottom .vlist-search__container{border-bottom:none;border-top:1px solid var(--vlist-border)}.vlist-search__leading-icon,.vlist-search__nav-prev,.vlist-search__nav-next,.vlist-search__clear-button{flex:0 0 auto;display:inline-flex;align-items:center;justify-content:center;width:24px;height:24px;padding:0;border:none;border-radius:4px;background:transparent;color:var(--vlist-text-muted);cursor:pointer}.vlist-search__leading-icon svg,.vlist-search__nav-prev svg,.vlist-search__nav-next svg,.vlist-search__clear-button svg{width:18px;height:18px;fill:currentColor}.vlist-search__leading-icon:hover,.vlist-search__nav-prev:hover,.vlist-search__nav-next:hover,.vlist-search__clear-button:hover{color:var(--vlist-text);background-color:var(--vlist-bg-hover)}.vlist-search__clear-button--hidden,.vlist-search__nav-prev--hidden,.vlist-search__nav-next--hidden{display:none}.vlist-search__input-wrapper{flex:1 1 auto;min-width:0;display:flex;align-items:center}.vlist-search__input{width:100%;min-width:0;padding:4px 8px;font:inherit;color:var(--vlist-text);background-color:var(--vlist-bg);border:1px solid var(--vlist-border);border-radius:4px;outline:none;box-sizing:border-box}.vlist-search__input:focus{border-color:var(--vlist-focus-ring)}.vlist-search__input:focus,.vlist-search__input:focus-visible{outline:none}.vlist-search__counter{flex:0 0 auto;font-size:0.75rem;color:var(--vlist-text-muted);white-space:nowrap}.vlist-search__counter:empty{display:none}.vlist-search-match{color:inherit;background-color:var(--vlist-search-match-bg);border-radius:2px}.vlist-search-match--current{background-color:var(--vlist-search-match-current-bg)}.vlist-search--md3{display:flex;align-items:center;box-sizing:border-box;height:56px;padding:0 12px;border-bottom:1px solid var(--vlist-border)}.vlist-search--md3 .vlist-search__container{flex:1 1 auto;height:40px;padding:0 16px;gap:0;border:none;border-radius:20px;overflow:hidden;background-color:var(--vlist-search-md3-surface);transition:background-color 200ms cubic-bezier(0.2,0,0,1)}.vlist-search--md3 .vlist-search__leading-icon{width:24px;height:24px;margin-right:16px;border-radius:50%;color:var(--vlist-text)}.vlist-search--md3 .vlist-search__leading-icon svg{width:24px;height:24px}.vlist-search--md3 .vlist-search__input{width:100%;height:100%;padding:8px 0;border:none;background:transparent;font:inherit;font-size:16px;line-height:24px;color:var(--vlist-text);caret-color:var(--vlist-focus-ring)}.vlist-search--md3 .vlist-search__input::placeholder{color:var(--vlist-text-muted)}.vlist-search--md3 .vlist-search__counter{margin-left:16px;font-size:12px;color:var(--vlist-text-muted)}.vlist-search--md3 .vlist-search__nav-prev,.vlist-search--md3 .vlist-search__nav-next,.vlist-search--md3 .vlist-search__clear-button{width:24px;height:24px;margin-left:16px;border-radius:50%;color:var(--vlist-text-muted);transition:background-color 200ms cubic-bezier(0.2,0,0,1)}.vlist-search--md3 .vlist-search__nav-prev svg,.vlist-search--md3 .vlist-search__nav-next svg,.vlist-search--md3 .vlist-search__clear-button svg{width:20px;height:20px}.vlist-search--md3 .vlist-search__leading-icon:hover,.vlist-search--md3 .vlist-search__nav-prev:hover,.vlist-search--md3 .vlist-search__nav-next:hover,.vlist-search--md3 .vlist-search__clear-button:hover{background-color:var(--vlist-search-md3-state)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vlist",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Lightweight, high-performance virtual list with zero dependencies",
   "author": {
     "name": "Floor IO",
@@ -45,6 +45,7 @@
     "./styles/table": "./dist/vlist-table.css",
     "./styles/extras": "./dist/vlist-extras.css",
     "./styles/tree": "./dist/vlist-tree.css",
+    "./styles/search": "./dist/vlist-search.css",
     "./package.json": "./package.json"
   },
   "files": [