@rokkit/ui 1.4.2 → 1.6.0

package/dist/types/index.js

@@ -91,3 +91,11 @@ export * from './stepper.js';
 export * from './tilt.js';
 // Chat Types
 export * from './chat.js';
+// Shared snippet types for the item-rendering components
+export * from './snippets.js';
+// Grid
+export * from './grid.js';
+// CommandPalette
+export * from './command-palette.js';
+// Swatch
+export * from './swatch.js';

package/dist/types/list.d.ts

@@ -5,6 +5,8 @@
  * Supports navigation links, button items, and grouped items with collapsible sections.
  * Field mapping and data access is handled by ProxyItem from @rokkit/states.
  */
+import type { ProxyItem } from '@rokkit/states';
+import type { ItemSnippets } from './snippets.js';
 /**
  * Field mapping configuration for list data.
  */
@@ -43,72 +45,37 @@ export declare const defaultListFields: Required<Omit<ListFields, 'fields'>>;
  */
 export type ListItem = Record<string, unknown>;
 /**
- * Handlers passed to custom item snippets
- */
-export interface ListItemHandlers {
-    /** Call to trigger item selection (for button items) */
-    onclick: () => void;
-    /** Forward keyboard events for accessibility */
-    onkeydown: (event: KeyboardEvent) => void;
-}
-/**
- * Snippet type for rendering list items.
- * Parameters: item, fields, handlers, isActive
- */
-export type ListItemSnippet = import('svelte').Snippet<[
-    ListItem,
-    ListFields,
-    ListItemHandlers,
-    boolean
-]>;
-/**
- * Snippet type for rendering group labels
- * Parameters: item (group), fields, toggleExpanded, isExpanded
- */
-export type ListGroupLabelSnippet = import('svelte').Snippet<[
-    ListItem,
-    ListFields,
-    () => void,
-    boolean
-]>;
-/**
- * Props for the List component
+ * Props for the List component.
+ *
+ * `List.svelte` annotates its own `$props()` with this interface, so the two
+ * cannot drift — which is how the previous version of this type came to
+ * describe `item` / `groupLabel` snippets and `multiselect` / `expanded` /
+ * `selected` props the component never read.
+ *
+ * Extends {@link ItemSnippets} for `itemContent` / `groupContent` plus the open
+ * index signature that per-item named snippets (`item.snippet = 'name'`) need.
  */
-export interface ListProps {
+export interface ListProps extends ItemSnippets {
     /** Array of list items or groups */
-    items?: ListItem[];
+    items?: unknown[];
     /** Field mapping configuration */
-    fields?: ListFields;
-    /** Currently selected value (for highlighting button items) */
+    fields?: Record<string, string>;
+    /** Selected value (bindable) — matched against each item's value field */
     value?: unknown;
     /** Size variant */
-    size?: 'sm' | 'md' | 'lg';
+    size?: string;
     /** Whether the entire list is disabled */
     disabled?: boolean;
     /** Whether groups can be collapsed */
     collapsible?: boolean;
-    /** Enable multiple item selection (Ctrl+click toggle, Shift+click range) */
-    multiselect?: boolean;
-    /** Which groups are expanded (bindable) - keyed by group value/text */
-    expanded?: Record<string, boolean>;
-    /** Selected items array (bindable) - populated in multiselect mode */
-    selected?: unknown[];
-    /** Active item value - List looks up item by this value to highlight it */
-    active?: unknown;
-    /** Called when a button item is selected */
-    onselect?: (value: unknown, item: ListItem) => void;
-    /** Called when selected items change in multiselect mode */
-    onselectedchange?: (selected: unknown[]) => void;
-    /** Called when expanded state changes (for bindable expanded) */
-    onexpandedchange?: (expanded: Record<string, boolean>) => void;
-    /** Additional CSS classes */
-    class?: string;
+    /** Accessible name for the list */
+    label?: string;
     /** Icons for list group states (expand/collapse arrow) */
     icons?: ListStateIcons;
-    /** Custom snippet for rendering list items */
-    item?: ListItemSnippet;
-    /** Custom snippet for rendering group labels/headers */
-    groupLabel?: ListGroupLabelSnippet;
+    /** Called when an item is selected, with the item's `ProxyItem` */
+    onselect?: (value: unknown, proxy: ProxyItem) => void;
+    /** Additional CSS classes */
+    class?: string;
 }
 /**
  * Icons configuration for list collapsible group states.

package/dist/types/menu.d.ts

@@ -5,12 +5,19 @@
  * Trigger action manages open/close. Dropdown content is identical to List.
  */
 import type { ProxyItem } from '@rokkit/states';
+import type { ItemSnippets } from './snippets.js';
 /**
  * Props for the Menu component.
  * Content props (items, fields, value, size, disabled, collapsible, icons, onselect, class, snippets)
  * are identical to List. Additional props: label, icon, showArrow, align, direction.
  */
-export interface MenuProps {
+/**
+ * Props for the Menu component.
+ *
+ * `Menu.svelte` annotates its own `$props()` with this interface, so the two
+ * cannot drift.
+ */
+export interface MenuProps extends ItemSnippets {
     /** Array of items (same as List: supports groups, separators, nested children) */
     items?: unknown[];
     /** Field mapping — overrides BASE_FIELDS defaults (label → 'label', value → 'value', …) */
@@ -18,7 +25,7 @@ export interface MenuProps {
     /** Current active value (highlights matching item) */
     value?: unknown;
     /** Size variant */
-    size?: 'sm' | 'md' | 'lg';
+    size?: string;
     /** Whether the entire menu is disabled */
     disabled?: boolean;
     /** Whether groups are collapsible (same as List) */

package/dist/types/select.d.ts

@@ -4,94 +4,84 @@
  * Provides types for the data-driven Select and MultiSelect components.
  * Field mapping and data access is handled by ProxyItem from @rokkit/states.
  */
-import type { Snippet } from 'svelte';
-import type { ProxyItem } from '@rokkit/states';
+import type { ItemSnippets } from './snippets.js';
 /**
  * Generic select item - can be any object with mapped fields
  */
 export type SelectItem = Record<string, unknown>;
-/** @deprecated Legacy handlers — will be removed when PaletteManager migrates to Navigator stack */
-export interface SelectItemHandlers {
-    onclick: () => void;
-    onkeydown: (event: KeyboardEvent) => void;
-}
-/**
- * Snippet type for rendering a single option in the dropdown.
- * The component renders the focusable wrapper; the snippet renders the inner content.
- * Navigator handles click selection via data-path — no handlers needed in snippet.
- */
-export type SelectOptionSnippet = Snippet<[ProxyItem]>;
-/**
- * Snippet type for rendering a group header label.
- */
-export type SelectGroupLabelSnippet = Snippet<[ProxyItem]>;
-/**
- * Snippet type for rendering the selected value display in the trigger button.
- */
-export type SelectValueSnippet = Snippet<[ProxyItem]>;
 /**
- * Snippet type for rendering selected values in MultiSelect trigger.
- * Receives the array of selected ProxyItems.
- */
-export type MultiSelectValueSnippet = Snippet<[ProxyItem[]]>;
-/**
- * Common props shared between Select and MultiSelect
+ * Common props shared between Select, MultiSelect and Dropdown.
+ *
+ * Each component annotates its own `$props()` with the derived interface, so
+ * they cannot drift — which is how the previous version came to name the data
+ * prop `options` when every component takes `items`, and to declare
+ * `option` / `groupLabel` snippets the components never read.
  */
 export interface SelectBaseProps {
-    /** Array of select options or groups */
-    options?: SelectItem[];
-    /** Field mapping — overrides BASE_FIELDS defaults (text → 'label', value → 'value', …) */
+    /** Array of options or groups */
+    items?: unknown[];
+    /** Field mapping — overrides BASE_FIELDS defaults */
     fields?: Record<string, string>;
     /** Placeholder text when no selection */
     placeholder?: string;
     /** Size variant */
-    size?: 'sm' | 'md' | 'lg';
+    size?: string;
+    /** Whether the control is disabled */
+    disabled?: boolean;
     /** Dropdown alignment relative to trigger */
-    align?: 'left' | 'right' | 'start' | 'end';
+    align?: 'start' | 'end';
     /** Dropdown slide direction */
     direction?: 'up' | 'down';
-    /** Maximum visible rows in dropdown (default: 5) */
-    maxRows?: number;
-    /** Whether the select is disabled */
-    disabled?: boolean;
+    /** Icons for dropdown arrow, check and remove */
+    icons?: SelectStateIcons;
     /** Additional CSS classes on root element */
     class?: string;
-    /** Icons for select states (dropdown arrow, check, remove) */
-    icons?: SelectStateIcons;
-    /** Custom snippet for rendering options in dropdown */
-    option?: SelectOptionSnippet;
-    /** Custom snippet for rendering group labels */
-    groupLabel?: SelectGroupLabelSnippet;
-    /** Enable typeahead filter input in dropdown header */
-    filterable?: boolean;
-    /** Placeholder text for the filter input */
-    filterPlaceholder?: string;
 }
 /**
- * Props for the Select component (single selection)
+ * Props for the Select component (single selection).
  */
-export interface SelectProps extends SelectBaseProps {
-    /** Currently selected value (bindable) — extracted via item[fields.value] */
+export interface SelectProps extends SelectBaseProps, ItemSnippets {
+    /** Selected value (bindable) — extracted via item[fields.value] */
     value?: unknown;
-    /** Currently selected raw item (bindable) — full object from options array */
-    selected?: SelectItem | null;
+    /** Selected raw item (bindable) */
+    selected?: unknown;
+    /** Enable the typeahead filter input in the dropdown header */
+    filterable?: boolean;
+    /** Placeholder for the filter input */
+    filterPlaceholder?: string;
+    /** Maximum visible rows in the dropdown */
+    maxRows?: number;
     /** Called when selection changes */
-    onchange?: (value: unknown, item: SelectItem) => void;
-    /** Custom snippet for rendering the selected value in the trigger */
-    selectedValue?: SelectValueSnippet;
+    onchange?: (value: unknown, item: unknown) => void;
 }
 /**
- * Props for the MultiSelect component (multiple selection)
+ * Props for the MultiSelect component (multiple selection).
  */
-export interface MultiSelectProps extends SelectBaseProps {
-    /** Currently selected values (bindable) - extracted primitives */
+export interface MultiSelectProps extends SelectBaseProps, ItemSnippets {
+    /** Selected values (bindable) */
     value?: unknown[];
-    /** Currently selected items (bindable) - full item objects for convenience */
-    selected?: SelectItem[];
-    /** Called when selection changes */
-    onchange?: (values: unknown[], items: SelectItem[]) => void;
-    /** Maximum number of tags to show before collapsing to count */
+    /** Selected items (bindable) */
+    selected?: unknown[];
+    /** Maximum tags shown before collapsing to a count */
     maxDisplay?: number;
+    /** Called when selection changes */
+    onchange?: (values: unknown[], items: unknown[]) => void;
+}
+/**
+ * Props for the Dropdown component.
+ *
+ * Unlike Select and MultiSelect it does not spread snippets, so it takes the
+ * base props only.
+ */
+export interface DropdownProps extends SelectBaseProps {
+    /** Selected value (bindable) */
+    value?: unknown;
+    /** Trigger icon class */
+    icon?: string;
+    /** Whether to show the dropdown arrow indicator on the trigger */
+    showArrow?: boolean;
+    /** Called when selection changes */
+    onchange?: (value: unknown, item: unknown) => void;
 }
 /**
  * Icons configuration for select expand/collapse and selection states.

package/dist/types/snippets.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared snippet types for the item-rendering components.
+ *
+ * List / Tree / Menu / Select / Grid and friends collect their snippets with a
+ * rest element (`...snippets`) behind an index signature, because a data item
+ * can name its own snippet (`item.snippet = 'name'`, resolved by
+ * `resolveSnippet`) — so arbitrary keys must stay accepted.
+ *
+ * The index signature alone typed every snippet as `unknown`, which made each
+ * consumer's snippet parameter implicitly `any`: a snippet body could read any
+ * property off `proxy` or pass it somewhere expecting a different type, and
+ * nothing complained until runtime. Declaring the documented snippets
+ * explicitly fixes that — TypeScript prefers an explicit member over the index
+ * signature, so the common case is checked while named snippets still work.
+ */
+import type { Snippet } from 'svelte';
+import type { ProxyItem } from '@rokkit/states';
+/**
+ * Renders one item's inner content, given its `ProxyItem`.
+ *
+ * This is the shape of `itemContent` and `groupContent` — the fallbacks
+ * `resolveSnippet` reaches for (`ITEM_SNIPPET` / `GROUP_SNIPPET`), and the
+ * shape any per-item named snippet must also have.
+ */
+export type ItemSnippet = Snippet<[ProxyItem]>;
+/**
+ * Renders one item's inner content plus whether it is currently selected.
+ *
+ * Used where selection is part of the item's own rendering rather than the
+ * wrapper's — Tabs and Toggle both call their content snippet as
+ * `content(proxy, selected)`.
+ */
+export type SelectableItemSnippet = Snippet<[ProxyItem, boolean]>;
+/**
+ * The snippet bag an item-rendering component accepts.
+ *
+ * Spread into a component's props type so the documented snippets are typed
+ * while `item.snippet = 'name'` keeps working:
+ *
+ * ```ts
+ * let { items = [], ...snippets }: { items?: unknown[] } & ItemSnippets = $props()
+ * ```
+ */
+export interface ItemSnippets<S = ItemSnippet> {
+    /** Inner content for a leaf item. */
+    itemContent?: S;
+    /** Inner content for a group/parent item. Falls back to `itemContent`. */
+    groupContent?: S;
+    /**
+     * Per-item named snippets, selected via the item's `snippet` field:
+     *
+     * ```svelte
+     * {#snippet pinned(proxy)}…{/snippet}
+     * <List items={[{ label: 'A', snippet: 'pinned' }]} snippets={{ pinned }} />
+     * ```
+     *
+     * A declared prop rather than an index signature. An index signature would
+     * have to admit every other prop too — TypeScript requires each declared
+     * member to conform to it — which forced it to `unknown` and silently
+     * accepted any misspelled prop name (`itemcontnt`, `onSelect`) on every
+     * component that used it.
+     */
+    snippets?: Record<string, S>;
+}

package/dist/types/snippets.js

@@ -0,0 +1,16 @@
+/**
+ * Shared snippet types for the item-rendering components.
+ *
+ * List / Tree / Menu / Select / Grid and friends collect their snippets with a
+ * rest element (`...snippets`) behind an index signature, because a data item
+ * can name its own snippet (`item.snippet = 'name'`, resolved by
+ * `resolveSnippet`) — so arbitrary keys must stay accepted.
+ *
+ * The index signature alone typed every snippet as `unknown`, which made each
+ * consumer's snippet parameter implicitly `any`: a snippet body could read any
+ * property off `proxy` or pass it somewhere expecting a different type, and
+ * nothing complained until runtime. Declaring the documented snippets
+ * explicitly fixes that — TypeScript prefers an explicit member over the index
+ * signature, so the common case is checked while named snippets still work.
+ */
+export {};

package/dist/types/swatch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Swatch Component Types
+ *
+ * A group of selectable colour swatches. Options may be primitives (hex or
+ * colour-name strings) or objects whose fill/stroke/value are read through the
+ * usual field mapping.
+ */
+import type { Snippet } from 'svelte';
+import type { ProxyItem } from '@rokkit/states';
+/**
+ * Props for the Swatch component.
+ *
+ * `Swatch.svelte` annotates its own `$props()` with this interface, so the two
+ * cannot drift.
+ */
+export interface SwatchProps {
+    /** Color options — primitives (hex/name strings) or objects with mapped fields */
+    options?: Array<string | number | Record<string, unknown>>;
+    /** Field mapping for object options (value, fill, stroke, …) */
+    fields?: Record<string, string>;
+    /** Selected value (bindable). Array when `multiple`. */
+    value?: unknown;
+    /** Allow multiple selection */
+    multiple?: boolean;
+    /** Swatch shape */
+    shape?: 'square' | 'circle';
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Disable the whole group */
+    disabled?: boolean;
+    /** Accessible group label */
+    label?: string;
+    /** Additional CSS classes */
+    class?: string;
+    /** Called when selection changes */
+    onchange?: (value: unknown, item: unknown) => void;
+    /** Custom snippet for rendering a swatch (receives proxy + selected) */
+    item?: Snippet<[ProxyItem, boolean]>;
+}

package/dist/types/swatch.js

@@ -0,0 +1,8 @@
+/**
+ * Swatch Component Types
+ *
+ * A group of selectable colour swatches. Options may be primitives (hex or
+ * colour-name strings) or objects whose fill/stroke/value are read through the
+ * usual field mapping.
+ */
+export {};

package/dist/types/table.d.ts

@@ -143,6 +143,11 @@ export interface TableProps {
     row?: TableRowSnippet;
     /** Custom cell snippet */
     cell?: TableCellSnippet;
+    /**
+     * Per-column named snippets, selected via a column's `snippet` field. Takes
+     * precedence over `cell` for the columns that name one.
+     */
+    snippets?: Record<string, TableCellSnippet>;
     /** Empty state snippet */
     empty?: TableEmptySnippet;
 }

package/dist/types/toolbar.d.ts

@@ -85,6 +85,11 @@ export interface ToolbarProps {
     class?: string;
     /** Custom snippet for rendering toolbar items */
     item?: ToolbarItemSnippet;
+    /**
+     * Per-item named snippets, selected via the item's `snippet` field. A declared
+     * prop rather than an index signature — see types/snippets.ts for why.
+     */
+    snippets?: Record<string, ToolbarItemSnippet>;
     /** Slot for start section content */
     start?: import('svelte').Snippet;
     /** Slot for center section content */

package/dist/types/tree.d.ts

@@ -5,7 +5,8 @@
  * Supports hierarchical data with expand/collapse, tree lines, and custom icons.
  * Field mapping and data access is handled by ProxyItem from @rokkit/states.
  */
-import type { Snippet } from 'svelte';
+import type { ItemSnippets } from './snippets.js';
+import type { ProxyItem } from '@rokkit/states';
 /**
  * Field mapping configuration for tree data — what the consumer passes
  * to the Tree component. Both `expanded` and `level` are optional here
@@ -87,82 +88,49 @@ export interface TreeStateIcons {
  */
 export declare const defaultTreeStateIcons: TreeStateIcons;
 /**
- * Handlers passed to custom item snippets
- */
-export interface TreeItemHandlers {
-    /** Call to trigger item selection */
-    onclick: () => void;
-    /** Call to toggle expand/collapse */
-    ontoggle: () => void;
-    /** Forward keyboard events for accessibility */
-    onkeydown: (event: KeyboardEvent) => void;
-}
-/**
- * Snippet type for rendering tree nodes.
- * Parameters: item, fields, handlers, isActive, isExpanded, level
- */
-export type TreeItemSnippet = Snippet<[
-    TreeItem,
-    TreeFields,
-    TreeItemHandlers,
-    boolean,
-    boolean,
-    number
-]>;
-/**
- * Snippet type for rendering the expand/collapse icon
- * Parameters: isExpanded, hasChildren, icons
- */
-export type TreeToggleSnippet = Snippet<[boolean, boolean, TreeStateIcons]>;
-/**
- * Snippet type for rendering tree line connectors
- * Parameters: lineType
+ * Props for the Tree component
  */
-export type TreeConnectorSnippet = Snippet<[TreeLineType]>;
 /**
- * Props for the Tree component
+ * Props for the Tree component.
+ *
+ * `Tree.svelte` annotates its own `$props()` with this interface, so the two
+ * cannot drift — which is how the previous version came to describe
+ * `multiselect`, `expanded`, `selected`, `expandAll`, `active` and four
+ * callbacks the component never read.
  */
-export interface TreeProps {
+export interface TreeProps extends ItemSnippets {
     /** Array of tree items (hierarchical) */
-    items?: TreeItem[];
+    items?: unknown[];
     /** Field mapping configuration */
-    fields?: TreeFields;
-    /** Currently selected value */
+    fields?: Record<string, string>;
+    /** Selected value (bindable) */
     value?: unknown;
     /** Size variant */
-    size?: 'sm' | 'md' | 'lg';
-    /** Tree line connector style — 'none' hides lines, 'solid'|'dashed'|'dotted' set the line style */
+    size?: string;
+    /** Connector style — 'none' hides the lines */
     lineStyle?: 'none' | 'solid' | 'dashed' | 'dotted';
-    /** Enable multiple item selection (Ctrl+click toggle, Shift+click range) */
-    multiselect?: boolean;
-    /** Which nodes are expanded (bindable) - keyed by node value */
-    expanded?: Record<string, boolean>;
-    /** Selected items array (bindable) - populated in multiselect mode */
-    selected?: unknown[];
-    /** Expand all nodes by default */
-    expandAll?: boolean;
-    /** Active item value - Tree looks up item by this value to highlight it */
-    active?: unknown;
+    /** Accessible label overrides */
+    labels?: Record<string, string>;
     /** Icons for expand/collapse states */
-    icons?: TreeStateIcons;
-    /** Called when an item is selected */
-    onselect?: (value: unknown, item: TreeItem) => void;
-    /** Called when selected items change in multiselect mode */
-    onselectedchange?: (selected: unknown[]) => void;
-    /** Called when expanded state changes */
-    onexpandedchange?: (expanded: Record<string, boolean>) => void;
-    /** Called when a node is toggled */
-    ontoggle?: (value: unknown, item: TreeItem, isExpanded: boolean) => void;
-    /** Called when expanding a node with unloaded children (children: true). Returns the children array. */
-    onloadchildren?: (value: unknown, item: TreeItem) => Promise<TreeItem[]>;
+    icons?: {
+        opened?: string;
+        closed?: string;
+    };
+    /** Called when an item is selected, with the item's `ProxyItem` */
+    onselect?: (value: unknown, proxy: ProxyItem) => void;
     /** Additional CSS classes */
     class?: string;
-    /** Custom snippet for rendering tree items */
-    item?: TreeItemSnippet;
-    /** Custom snippet for rendering expand/collapse toggle */
-    toggle?: TreeToggleSnippet;
-    /** Custom snippet for rendering tree line connectors */
-    connector?: TreeConnectorSnippet;
+}
+/**
+ * Props for the LazyTree component — Tree plus on-demand child loading.
+ */
+export interface LazyTreeProps extends TreeProps {
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Called to fetch the children of a node being expanded */
+    onlazyload?: (current?: unknown) => Promise<unknown[]>;
+    /** Whether more nodes remain to load */
+    hasMore?: boolean;
 }
 /**
  * Constructs an array of line types for tree visualization.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/ui",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "description": "Data driven UI components for Rokkit applications",
   "repository": {
     "type": "git",
@@ -45,10 +45,10 @@
     "dropdown"
   ],
   "dependencies": {
-    "@rokkit/core": "1.4.2",
-    "@rokkit/data": "1.4.2",
-    "@rokkit/states": "1.4.2",
-    "@rokkit/actions": "1.4.2",
+    "@rokkit/core": "1.6.0",
+    "@rokkit/data": "1.6.0",
+    "@rokkit/states": "1.6.0",
+    "@rokkit/actions": "1.6.0",
     "marked": "^15.0.0",
     "dompurify": "^3.4.13"
   },