@rokkit/states 1.1.17 → 1.1.18

package/dist/alerts.svelte.d.ts

@@ -0,0 +1,27 @@
+export const alerts: AlertsStore;
+declare class AlertsStore {
+    get current(): {
+        id: string;
+        type: string;
+        text?: string;
+        dismissible: boolean;
+        timeout: number;
+        actions?: unknown;
+    }[];
+    push({ type, text, dismissible, timeout, actions }?: {
+        type?: string | undefined;
+        dismissible?: boolean | undefined;
+        timeout?: number | undefined;
+    }): `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * Dismiss an alert by id, cancelling its timer if any.
+     * @param {string} id
+     */
+    dismiss(id: string): void;
+    /**
+     * Clear all alerts and cancel all timers.
+     */
+    clear(): void;
+    #private;
+}
+export {};

package/dist/commands.svelte.d.ts

@@ -0,0 +1,59 @@
+/** Canonicalize a shortcut string: resolve `mod`, sort modifiers, lowercase the key. */
+export function normalizeShortcut(shortcut: any): string;
+/** Build the canonical shortcut string from a KeyboardEvent. */
+export function eventToShortcut(event: any): string;
+export const commands: CommandRegistry;
+/**
+ * App command registry — keyboard shortcuts + actions in one place.
+ * Singleton, like `vibe`/`messages`. See docs/design/19-command-system.md.
+ */
+export type Command = {
+    /**
+     * Unique id; re-registering the same id replaces (warns).
+     */
+    id: string;
+    /**
+     * Display text (consumer-localized).
+     */
+    label: string;
+    /**
+     * Executed on shortcut match or palette select.
+     */
+    run: () => void;
+    /**
+     * e.g. 'mod+k' | 'mod+shift+p' | '?'. `mod` = Cmd on macOS / Ctrl elsewhere.
+     */
+    shortcut?: string | undefined;
+    /**
+     * Palette category.
+     */
+    group?: string | undefined;
+    /**
+     * Fire even while a text input is focused (default false).
+     */
+    global?: boolean | undefined;
+    /**
+     * Optional dynamic gate.
+     */
+    enabled?: (() => boolean) | undefined;
+    /**
+     * Extra palette search terms.
+     */
+    keywords?: string[] | undefined;
+};
+declare class CommandRegistry {
+    /** @returns {Command[]} */
+    get all(): Command[];
+    /** @param {Command} cmd @returns {() => void} unregister */
+    register(cmd: Command): () => void;
+    /** @param {Command[]} cmds @returns {() => void} */
+    registerMany(cmds: Command[]): () => void;
+    /** @param {string} id */
+    unregister(id: string): void;
+    /** @param {string} id */
+    execute(id: string): void;
+    /** @param {KeyboardEvent} event @returns {Command | null} */
+    resolve(event: KeyboardEvent): Command | null;
+    #private;
+}
+export {};

package/dist/constants.d.ts

@@ -0,0 +1,28 @@
+export namespace DEFAULT_EVENTS {
+    export { noop as move };
+    export { noop as select };
+    export { noop as expand };
+    export { noop as collapse };
+}
+export const VALID_DENSITIES: string[];
+export const VALID_MODES: string[];
+export const VALID_DIRECTIONS: string[];
+/** @type {string[]} */
+export const DEFAULT_STYLES: string[];
+export namespace DEFAULT_VIBE_OPTIONS {
+    export { DEFAULT_STYLES as allowed };
+    export let style: string;
+    export let mode: string;
+    export let density: string;
+}
+export namespace DEFAULT_VIBE_PALETTE {
+    let primary: string;
+    let secondary: string;
+    let success: string;
+    let info: string;
+    let warning: string;
+    let danger: string;
+    let light: string;
+    let dark: string;
+}
+import { noop } from '@rokkit/core';

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { alerts } from "./alerts.svelte.js";
+export { vibe } from "./vibe.svelte.js";
+export { messages } from "./messages.svelte.js";
+export { ProxyTree } from "./proxy-tree.svelte.js";
+export { ProxyTable } from "./proxy-table.svelte.js";
+export { ProxyTableTree } from "./proxy-table-tree.svelte.js";
+export { Wrapper } from "./wrapper.svelte.js";
+export { LazyWrapper } from "./lazy-wrapper.svelte.js";
+export { commands, normalizeShortcut, eventToShortcut } from "./commands.svelte.js";
+export { ProxyItem, LazyProxyItem, BASE_FIELDS } from "./proxy-item.svelte.js";
+export { watchMedia, defaultBreakpoints } from "./media.svelte.js";

package/dist/lazy-wrapper.svelte.d.ts

@@ -0,0 +1,18 @@
+export class LazyWrapper extends Wrapper {
+    /**
+     * @param {import('./proxy-tree.svelte.js').ProxyTree} proxyTree
+     * @param {{ onselect?: Function, onchange?: Function, onlazyload?: Function }} [options]
+     */
+    constructor(proxyTree: import("./proxy-tree.svelte.js").ProxyTree, options?: {
+        onselect?: Function;
+        onchange?: Function;
+        onlazyload?: Function;
+    });
+    /**
+     * Load more root-level items via the onlazyload callback.
+     * Appends results to the proxy tree.
+     */
+    loadMore(): Promise<void>;
+    #private;
+}
+import { Wrapper } from './wrapper.svelte.js';

package/dist/media.svelte.d.ts

@@ -0,0 +1,5 @@
+/** @param {Record<string, string>} breakpoints */
+export function watchMedia(breakpoints?: Record<string, string>): Record<string, MediaQuery>;
+/** @type {Record<string, string>} */
+export const defaultBreakpoints: Record<string, string>;
+import { MediaQuery } from 'svelte/reactivity';

package/dist/messages.svelte.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Reactive messages store. Access strings directly: `messages.select`, `messages.tree.expand`.
+ * Configure locale: `messages.register('de', {...})` + `messages.setLocale('de')`.
+ */
+export const messages: MessagesStore;
+declare class MessagesStore {
+    emptyList: any;
+    emptyTree: any;
+    loading: any;
+    noResults: any;
+    select: any;
+    search: any;
+    list: any;
+    tree: any;
+    toolbar: any;
+    menu: any;
+    toggle: any;
+    rating: any;
+    stepper: any;
+    breadcrumbs: any;
+    carousel: any;
+    tabs: any;
+    table: any;
+    code: any;
+    range: any;
+    search_: any;
+    filter: any;
+    grid: any;
+    uploadProgress: any;
+    floatingNav: any;
+    mode: any;
+    command: any;
+    /** Currently active locale tag (read-only). */
+    get locale(): string;
+    /**
+     * Register translation overrides for a locale. Unspecified keys fall back to English defaults.
+     * @param {string} locale — BCP 47 tag or any identifier (e.g. 'de', 'fr-CA')
+     * @param {Partial<import('./types').Messages>} overrides
+     */
+    register(locale: string, overrides: Partial<any>): void;
+    /**
+     * Switch to a previously registered locale. Use 'en' to restore English defaults.
+     * @param {string} locale
+     */
+    setLocale(locale: string): void;
+    /**
+     * Apply one-off overrides without naming a locale (convenience / backward compat).
+     * @param {Partial<import('./types').Messages>} overrides
+     */
+    set(overrides: Partial<any>): void;
+    /**
+     * Reset to English defaults and clear all registered locales.
+     */
+    reset(): void;
+    #private;
+}
+export {};

package/dist/proxy-item.svelte.d.ts

@@ -0,0 +1,117 @@
+export { BASE_FIELDS };
+export class ProxyItem {
+    constructor(raw: any, fields?: {}, key?: string, level?: number);
+    /**
+     * Factory method for creating child proxies. Override in subclasses
+     * to produce specialised children (e.g. LazyProxyItem).
+     * @param {*} raw
+     * @param {Partial<typeof BASE_FIELDS>} fields
+     * @param {string} key
+     * @param {number} level
+     * @returns {ProxyItem}
+     */
+    _createChild(raw: any, fields: Partial<typeof BASE_FIELDS>, key: string, level: number): ProxyItem;
+    get key(): string;
+    get level(): number;
+    /** Stable unique identifier — from item's id field, or auto-generated. */
+    get id(): any;
+    /** The original input passed to the constructor — never mutated. */
+    get original(): any;
+    /** The merged field-mapping configuration. */
+    get fields(): {
+        id: string;
+        value: string;
+        label: string;
+        icon: string;
+        avatar: string;
+        subtext: string;
+        tooltip: string;
+        badge: string;
+        shortcut: string;
+        children: string;
+        type: string;
+        snippet: string;
+        href: string;
+        hrefTarget: string;
+        disabled: string;
+        expanded: string;
+        selected: string;
+    };
+    /**
+     * @param {string} fieldName  Semantic name, e.g. 'icon', 'href', 'description'
+     * @returns {*}
+     */
+    get(fieldName: string): any;
+    /**
+     * Write a value back to the underlying item through the field mapping.
+     * For object items, this modifies the original raw item (since #item === #raw).
+     * Increments the version counter so $derived(#buildChildren()) re-computes.
+     *
+     * @param {string} fieldName  Semantic name, e.g. 'children', 'text'
+     * @param {*} value
+     */
+    set(fieldName: string, value: any): void;
+    /**
+     * Write directly to the original raw item, bypassing field mapping.
+     * Advanced operation for when the caller needs to update the source data.
+     * Accepts either (field, value) or an object for batch updates.
+     * Increments version so $derived(#buildChildren()) re-computes.
+     *
+     * @param {string|object} fieldOrBatch  Raw key name, or { key: value, … }
+     * @param {*} [value]
+     */
+    mutate(fieldOrBatch: string | object, value?: any): void;
+    get label(): any;
+    get value(): any;
+    get disabled(): boolean;
+    /** True only for object items with a non-empty children array. */
+    get hasChildren(): boolean;
+    /** Returns wrapped ProxyItem children (empty array for primitives and leaf items). */
+    get children(): ProxyItem[];
+    get type(): any;
+    set expanded(v: boolean);
+    get expanded(): boolean;
+    set selected(v: boolean);
+    get selected(): boolean;
+    #private;
+}
+/**
+ * LazyProxyItem
+ *
+ * Extends ProxyItem with lazy-loading support. When a lazyLoad function
+ * is provided, children are fetched on demand via fetch().
+ *
+ * #lazyLoad  — async function (value, raw) => children[] — null when not lazy
+ * #loaded    — true when: lazyLoad is null, or node already has children array,
+ *              or after successful fetch(). false only for sentinel nodes
+ *              (children === true) that need fetching.
+ * #loading   — true during async fetch(), false otherwise. Used for spinner UI.
+ *
+ * After fetch(), uses set('children', result) to update the underlying item
+ * and trigger #children recomputation via the version counter.
+ *
+ * The lazyLoad function is propagated to all children automatically via
+ * _createChild override.
+ */
+export class LazyProxyItem extends ProxyItem {
+    /**
+     * @param {*} raw
+     * @param {Partial<typeof BASE_FIELDS>} [fields]
+     * @param {string} [key]
+     * @param {number} [level]
+     * @param {((value: unknown, raw: unknown) => Promise<unknown[]>) | null} [lazyLoad]
+     */
+    constructor(raw: any, fields?: Partial<typeof BASE_FIELDS>, key?: string, level?: number, lazyLoad?: ((value: unknown, raw: unknown) => Promise<unknown[]>) | null);
+    get loaded(): boolean;
+    get loading(): boolean;
+    /**
+     * Fetch children via the lazyLoad function.
+     * No-op if lazyLoad is null, already loaded, or currently loading.
+     * After fetching, writes children to the underlying item via set().
+     */
+    fetch(): Promise<void>;
+    /** @override — propagate lazyLoad to children */
+    override _createChild(raw: any, fields: any, key: any, level: any): LazyProxyItem;
+    #private;
+}
+import { BASE_FIELDS } from '@rokkit/core';

package/dist/proxy-table-tree.svelte.d.ts

@@ -0,0 +1,4 @@
+export class ProxyTableTree extends ProxyTable {
+    #private;
+}
+import { ProxyTable } from './proxy-table.svelte.js';

package/dist/proxy-table.svelte.d.ts

@@ -0,0 +1,60 @@
+export class ProxyTable extends ProxyTree {
+    /**
+     * @param {Array<Record<string, unknown>>} [data]
+     * @param {{ columns?: Array, fields?: object, onsort?: Function }} [options]
+     */
+    constructor(data?: Array<Record<string, unknown>>, options?: {
+        columns?: any[];
+        fields?: object;
+        onsort?: Function;
+    });
+    columns: any[];
+    sortState: any[];
+    /**
+     * Replace underlying data. Re-applies any active sort so the visible
+     * rows stay in their sorted order.
+     * @param {Array<Record<string, unknown>>} data
+     */
+    update(data: Array<Record<string, unknown>>): void;
+    /**
+     * Protected accessor for subclasses that need to re-sort the underlying
+     * data (e.g. ProxyTableTree on column-update).
+     */
+    get _rawData(): Record<string, unknown>[];
+    /**
+     * Replace column definitions. Preserves any existing sort indicators
+     * for columns that survive the rename.
+     * @param {Array} columns
+     */
+    updateColumns(columns: any[]): void;
+    /**
+     * Toggle sort on a column. Direction cycle: none → ascending → descending → none.
+     * Pass `extend=true` (Shift+click) to push onto the multi-column stack.
+     * Fires the `onsort` callback after applying.
+     *
+     * @param {string} columnName
+     * @param {boolean} [extend]
+     */
+    sortBy(columnName: string, extend?: boolean): void;
+    /** Clear all sort state and restore the original data order. */
+    clearSort(): void;
+    /**
+     * Apply the current sortState to a row array. Subclasses (ProxyTableTree)
+     * override to walk hierarchical structures.
+     *
+     * @param {Array<Record<string, unknown>>} rows
+     * @returns {Array<Record<string, unknown>>}
+     */
+    _sortedData(rows: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+    /**
+     * Compare two rows under the current sortState. Used by `_sortedData()`
+     * and by subclasses that sort over a hierarchical row tree.
+     *
+     * @param {Record<string, unknown>} a
+     * @param {Record<string, unknown>} b
+     * @returns {number}
+     */
+    _compareRows(a: Record<string, unknown>, b: Record<string, unknown>): number;
+    #private;
+}
+import { ProxyTree } from './proxy-tree.svelte.js';

package/dist/proxy-tree.svelte.d.ts

@@ -0,0 +1,35 @@
+export class ProxyTree {
+    constructor(items?: any[], fields?: {}, options?: {});
+    flatView: any[];
+    /** @returns {ProxyItem[]} Root proxy array */
+    get roots(): ProxyItem[];
+    /** @returns {Map<string, ProxyItem>} Lookup map of all proxies by key */
+    get lookup(): Map<string, ProxyItem>;
+    /**
+     * Append new root items. Creates proxies with keys continuing from
+     * the current length. Reassigns #rootProxies to trigger $derived.
+     *
+     * @param {unknown[]} items  Raw items to append as roots
+     */
+    append(items: unknown[]): void;
+    /**
+     * Replace all root items. Reassigns #rootProxies to trigger $derived.
+     * Keys are regenerated from the new item positions — focusedKey
+     * continuity across replace is the caller's concern.
+     *
+     * @param {unknown[]} items  Raw items to use as new roots
+     */
+    replace(items: unknown[]): void;
+    /**
+     * Add children to an existing proxy node.
+     * Uses proxy.set('children', rawItems) so ProxyItem's version counter
+     * triggers #buildChildren() recomputation. The flatView and lookup
+     * derive from proxy.children reactively.
+     *
+     * @param {ProxyItem} proxy  The proxy to add children to
+     * @param {unknown[]} items  Raw child items
+     */
+    addChildren(proxy: ProxyItem, items: unknown[]): void;
+    #private;
+}
+import { ProxyItem } from './proxy-item.svelte.js';

package/dist/tabular.svelte.d.ts

@@ -0,0 +1,5 @@
+export class TableWrapper {
+    constructor(items: any);
+    data: null;
+    headers: any[];
+}

package/dist/vibe.svelte.d.ts

@@ -0,0 +1,58 @@
+export const vibe: Vibe;
+export type ThemeMode = "light" | "dark";
+export type Density = "cozy" | "compact" | "comfortable";
+export type Direction = "ltr" | "rtl";
+/**
+ * Vibe - Theme management
+ */
+declare class Vibe {
+    /**
+     * Private constructor to enforce singleton pattern
+     * @param {VibeOptions} [options={}]
+     */
+    constructor(options?: VibeOptions);
+    set mode(value: string);
+    get mode(): string;
+    set style(value: string);
+    get style(): string;
+    set density(value: string);
+    get density(): string;
+    set colorMap(value: typeof DEFAULT_THEME_MAPPING);
+    get colorMap(): typeof DEFAULT_THEME_MAPPING;
+    set colors(value: any);
+    get colors(): any;
+    set allowedStyles(input: string[]);
+    get allowedStyles(): string[];
+    set allowedSkins(input: string[]);
+    get allowedSkins(): string[];
+    set skin(value: string);
+    get skin(): string;
+    set direction(value: "ltr" | "rtl");
+    get direction(): "ltr" | "rtl";
+    /** @returns {boolean} */
+    get isRTL(): boolean;
+    get palette(): {};
+    /**
+     * Load theme from storage
+     * @param {string} key
+     */
+    load(key: string): void;
+    /**
+     * Save current theme to storage
+     * @param {string} key
+     */
+    save(key: string): void;
+    /**
+     * Update theme with new values
+     * @param {Partial<Theme>} value
+     */
+    update(value: Partial<Theme>): void;
+    /**
+     * Re-detect direction from document
+     * Useful when lang attribute changes dynamically
+     */
+    detectDirection(): void;
+    #private;
+}
+import { DEFAULT_THEME_MAPPING } from '@rokkit/core';
+export {};

package/dist/wrapper.svelte.d.ts

@@ -0,0 +1,111 @@
+export class Wrapper {
+    /**
+     * @param {import('./proxy-tree.svelte.js').ProxyTree} proxyTree
+     * @param {{ onselect?: Function, onchange?: Function, collapsible?: boolean, multiselect?: boolean }} [options]
+     */
+    constructor(proxyTree: import("./proxy-tree.svelte.js").ProxyTree, options?: {
+        onselect?: Function;
+        onchange?: Function;
+        collapsible?: boolean;
+        multiselect?: boolean;
+    });
+    flatView: any[];
+    get focusedKey(): null;
+    /** Move focus to the next navigable item; clamp at end. */
+    next(_path: any): void;
+    /** Move focus to the previous navigable item; clamp at start. */
+    prev(_path: any): void;
+    /** Move focus to the first navigable item. */
+    first(_path: any): void;
+    /** Move focus to the last navigable item. */
+    last(_path: any): void;
+    /**
+     * Expand focused group, or move focus into it if already open.
+     * No-op on leaf items. When collapsible=false groups are always open,
+     * so this only ever moves focus into the first child.
+     */
+    expand(_path: any): void;
+    /**
+     * Collapse focused group, or move focus to parent if already collapsed / leaf.
+     * At root level with no parent: no-op.
+     * When collapsible=false, skips closing the group but still moves focus to parent.
+     */
+    collapse(_path: any): void;
+    select(path: any): void;
+    /**
+     * Toggle expansion of group at path — called by Navigator for accordion-trigger clicks.
+     * Unlike select(), this only applies to groups and never fires onselect.
+     * No-op when collapsible=false.
+     */
+    toggle(path: any): void;
+    /**
+     * Sync focused state to path — called by Navigator on focusin and typeahead match.
+     */
+    moveTo(path: any): void;
+    /**
+     * Sync focused key to the item matching this semantic value.
+     * Used by controlled components (Toggle, Select) to keep navigation
+     * in sync when the bound value changes externally.
+     *
+     * @param {unknown} v
+     */
+    moveToValue(v: unknown): void;
+    /** Persistent list: no dropdown to close. Override in dropdown wrappers. */
+    cancel(_path: any): void;
+    /** Persistent list: no-op. Override in dropdown wrappers to close + restore trigger focus. */
+    blur(): void;
+    /**
+     * Multi-select toggle — Ctrl/Cmd-click or Ctrl/Cmd-Space.
+     * When `multiselect: false` (default) this is a no-op so single-select
+     * consumers see the same behavior as before.
+     *
+     * Toggles `path` in `selectedKeys`, sets anchor for subsequent range select,
+     * and fires `onselect` for leaf targets. Group targets update focus + anchor
+     * but do not toggle into selectedKeys (groups aren't selectable values).
+     *
+     * @param {string|null} path
+     */
+    extend(path: string | null): void;
+    /**
+     * Multi-select range — Shift-click or Shift-Space.
+     * Selects every navigable item from the anchor (last single-click target,
+     * or the focused item if no anchor) to `path`, inclusive. Replaces any
+     * existing selection.
+     *
+     * When `multiselect: false` (default) this is a no-op.
+     *
+     * @param {string|null} path
+     */
+    range(path: string | null): void;
+    /**
+     * Return the key of the first navigable item whose text starts with query
+     * (case-insensitive). Wraps around. startAfterKey enables cycling.
+     * Returns null if no match.
+     *
+     * @param {string} query
+     * @param {string|null} [startAfterKey]
+     * @returns {string|null}
+     */
+    findByText(query: string, startAfterKey?: string | null): string | null;
+    /** @returns {Map<string, import('./proxy-item.svelte.js').ProxyItem>} */
+    get lookup(): Map<string, import("./proxy-item.svelte.js").ProxyItem>;
+    /** @returns {import('./proxy-tree.svelte.js').ProxyTree} */
+    get proxyTree(): import("./proxy-tree.svelte.js").ProxyTree;
+    /**
+     * Reactive set of selected keys. Tracks meaningfully only when
+     * `multiselect: true` — in single-select mode it mirrors the most
+     * recent `select()` target (one key at a time).
+     *
+     * @returns {SvelteSet<string>}
+     */
+    get selectedKeys(): SvelteSet<string>;
+    /**
+     * In multi-select mode: array of selected leaf values (in selectedKeys order).
+     * In single-select mode: the last selected value (back-compat with `select()`).
+     *
+     * @returns {unknown[] | unknown}
+     */
+    get selected(): unknown[] | unknown;
+    #private;
+}
+import { SvelteSet } from 'svelte/reactivity';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/states",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "Contains generic data manipulation functions that can be used in various components.",
   "repository": {
     "type": "git",
@@ -24,7 +24,9 @@
   "files": [
     "src/**/*.js",
     "src/**/*.svelte",
+    "dist/**/*.d.ts",
     "README.md",
+    "package.json",
     "LICENSE"
   ],
   "exports": {
@@ -37,8 +39,8 @@
     }
   },
   "dependencies": {
-    "@rokkit/core": "1.1.17",
-    "@rokkit/data": "1.1.17",
+    "@rokkit/core": "1.1.18",
+    "@rokkit/data": "1.1.18",
     "d3-array": "^3.2.4",
     "ramda": "^0.32.0",
     "svelte": "^5.53.5"