@happyvertical/smrt-ui 0.42.6 → 0.43.0

package/README.md

@@ -39,8 +39,10 @@ pnpm add @happyvertical/smrt-ui
 | Collections | `CollectionToolbar`, `CollectionList`/`ContentList`, `DataTable`, `Pagination` |
 | Layout and navigation | `Container`, `Grid`, `Header`, `Footer`, `PageHeader`, `EmptyState`, `Tabs`, `FilterChips` |
 
-Use the focused subpaths (`/forms`, `/ui`, `/feedback`, `/data`, `/layout`,
-`/themes`) to keep imports explicit. The package root remains a compatibility
+Use the focused subpaths (`/forms`, `/ui`, `/feedback`, `/data`,
+`/data-surface`, `/layout`, `/themes`) to keep imports explicit. The
+Svelte-free `/data-surface` entry exposes the registry contracts and shared
+protocol limits for server adapters. The package root remains a compatibility
 barrel.
 
 ## Component standard
@@ -376,6 +378,57 @@ adapter, and authentication, tenancy, confirmation-token verification, and
 durable actions remain server-side. URL state and saved views also remain
 application-owned persistence adapters.
 
+### DataTable and CollectionToolbar integration
+
+Registration is opt-in. Pass `dataSurface` with an explicit descriptor and a
+registry; existing `DataTable` and `CollectionToolbar` consumers do not
+register or change behavior. Registration follows reactive `dataSurface` and
+controller prop replacement, so registry commands never retain a prior mounted
+instance. A DataTable descriptor must only name effective, visible columns,
+except for its stable `rowKey`, which may remain non-rendered. Mounted tables
+always require that `rowKey` to be an explicit string field; the index fallback
+and functional key callbacks are never addressable across pages or refreshes.
+
+```svelte
+<script lang="ts">
+  import { DataTable, createDataSurfaceRegistry } from '@happyvertical/smrt-ui/data';
+
+  const registry = createDataSurfaceRegistry();
+  const dataSurface = {
+    registry,
+    descriptor: {
+      // descriptor omitted: give this mounted instance a stable identity,
+      // policy-visible columns, controls, query limits, and action descriptors
+    },
+  };
+</script>
+
+<DataTable {dataSurface} data={rows} {columns} rowKey="id" />
+```
+
+Declared controller controls include search, filters, multi-sort, page/page
+size, column layout, selection, expansion, reset, focus/reveal/highlight, and
+optional refresh/retry callbacks. The component maps controller controls to the
+same `DataTableController.dispatch()` path used by buttons and checkboxes. A
+controlled table supplies `applyControlledState(candidate, command)`; the
+registry acknowledges only after that callback settles the candidate state.
+
+`CollectionToolbar` accepts the same opt-in registration and an optional
+`controller`. Its `set-search` control shares that table controller; `set-view`
+remains toolbar-local. Descriptors may advertise row/bulk action contracts, but
+smrt-ui does not execute durable actions—the later authenticated action adapter
+owns preview, confirmation, authorization, and persistence.
+
+Toolbar snapshots also advance their revision when the host updates exposed
+uncontrolled `search` or `view` props, so a command based on an earlier view is
+rejected as stale instead of overwriting host state.
+
+DataSurface columns may also carry domain-neutral policy metadata (`fieldName`,
+`visibility`, `order`, `role`, `responsivePriority`, `readable`, and per-column
+operator allowlists). Domain packages such as `@happyvertical/smrt-fields`
+apply their effective policy above this package; `smrt-ui` validates and
+serializes the metadata without owning field authorization or policy rules.
+
 ## Themes
 
 `@happyvertical/smrt-ui/themes` is the canonical theme API and includes the

package/dist/components/data/CollectionToolbar.svelte

@@ -1,7 +1,17 @@
 <script lang="ts">
-import type { Snippet } from 'svelte';
+import { onDestroy, type Snippet, untrack } from 'svelte';
 import Input from '../forms/Input.svelte';
 import SegmentedControl from '../forms/SegmentedControl.svelte';
+import type {
+  DataTableController,
+  DataTableViewState,
+} from './DataTableController.js';
+import {
+  type DataSurfaceJsonValue,
+  type DataSurfaceRegistry,
+  normalizeDataSurfaceDescriptor,
+} from './data-surface.js';
+import type { CollectionToolbarDataSurfaceOptions } from './types.js';
 
 export interface Props {
   search?: string;
@@ -16,6 +26,10 @@ export interface Props {
   bulkActions?: Snippet;
   onsearchchange?: (value: string) => void;
   onviewchange?: (view: 'list' | 'grid' | 'table') => void;
+  /** Shares search state with a DataTable controller when supplied. */
+  controller?: DataTableController;
+  /** Registers this toolbar only when explicitly supplied. */
+  dataSurface?: CollectionToolbarDataSurfaceOptions;
   class?: string;
 }
 
@@ -32,9 +46,36 @@ let {
   bulkActions,
   onsearchchange,
   onviewchange,
+  controller,
+  dataSurface,
   class: className = '',
 }: Props = $props();
 
+let controllerState = $state<DataTableViewState | undefined>(undefined);
+let toolbarElement = $state<HTMLDivElement>();
+let surfaceHighlighted = $state(false);
+let surfaceRegistration:
+  | {
+      surface: CollectionToolbarDataSurfaceOptions;
+      registry: DataSurfaceRegistry;
+      descriptorSignature: string;
+      controller: DataTableController | undefined;
+      cleanup: () => void;
+    }
+  | undefined;
+
+$effect(() => {
+  if (!controller) {
+    controllerState = undefined;
+    return;
+  }
+  controllerState = controller.getState();
+  return controller.subscribe((transition) => {
+    if (!transition.changed) return;
+    controllerState = transition.next.state;
+  });
+});
+
 const viewOptions = $derived(
   views.map((value) => ({
     value,
@@ -43,14 +84,172 @@ const viewOptions = $derived(
 );
 
 function changeView(next: string | number) {
-  view = String(next) as typeof view;
+  const candidate = String(next);
+  if (!views.includes(candidate as typeof view)) return;
+  view = candidate as typeof view;
   onviewchange?.(view);
 }
+
+function changeSearch(next: string) {
+  if (controller) {
+    const transition = controller.dispatch({ type: 'setSearch', search: next });
+    if (!transition.changed) return;
+  } else {
+    if (search === next) return;
+    search = next;
+  }
+  onsearchchange?.(next);
+}
+
+function payloadObject(
+  value: DataSurfaceJsonValue | undefined,
+): Record<string, DataSurfaceJsonValue> | undefined {
+  return value && !Array.isArray(value) && typeof value === 'object'
+    ? value
+    : undefined;
+}
+
+$effect(() => {
+  const surface = dataSurface;
+  const surfaceController = controller;
+  if (!surface) {
+    surfaceRegistration?.cleanup();
+    surfaceRegistration = undefined;
+    return;
+  }
+  const descriptorSignature = JSON.stringify(
+    normalizeDataSurfaceDescriptor(surface.descriptor),
+  );
+  if (
+    surfaceRegistration?.registry === surface.registry &&
+    surfaceRegistration?.descriptorSignature === descriptorSignature &&
+    surfaceRegistration?.controller === surfaceController
+  ) {
+    surfaceRegistration.surface = surface;
+    return;
+  }
+  surfaceRegistration?.cleanup();
+  surfaceRegistration = undefined;
+  const registration = {
+    surface,
+    registry: surface.registry,
+    descriptorSignature,
+    controller: surfaceController,
+    cleanup: () => {},
+  };
+  const cleanup = untrack(() => {
+    let revision = 0;
+    let previousStateSignature: string | undefined;
+    const readState = () => {
+      const state = {
+        search: surfaceController?.getState().search ?? search,
+        view,
+      };
+      const signature = JSON.stringify(state);
+      if (
+        previousStateSignature !== undefined &&
+        previousStateSignature !== signature
+      ) {
+        revision += 1;
+      }
+      previousStateSignature = signature;
+      return state;
+    };
+    let highlightTimer: ReturnType<typeof setTimeout> | undefined;
+    const unregister = surface.registry.register({
+      descriptor: surface.descriptor,
+      getSnapshot: () => {
+        const state = readState();
+        return { revision, state, selection: null };
+      },
+      execute: async (command) => {
+        const payload = payloadObject(command.payload);
+        if (
+          command.controlId === 'set-search' &&
+          typeof payload?.search === 'string'
+        ) {
+          if (surfaceController) {
+            const transition = surfaceController.dispatch({
+              type: 'setSearch',
+              search: payload.search,
+            });
+            if (surfaceController.isControlled() && transition.changed) {
+              const settled = await registration.surface.applyControlledState?.(
+                transition.next.state,
+                { type: 'setSearch', search: payload.search },
+              );
+              if (settled) surfaceController.replaceState(settled);
+              if (
+                JSON.stringify(surfaceController.getState()) !==
+                JSON.stringify(transition.next.state)
+              ) {
+                return { ok: false };
+              }
+            }
+            onsearchchange?.(payload.search);
+            return;
+          }
+          changeSearch(payload.search);
+          return;
+        }
+        if (
+          command.controlId === 'set-view' &&
+          typeof payload?.view === 'string'
+        ) {
+          const prior = view;
+          changeView(payload.view);
+          return view === prior && payload.view !== prior
+            ? { ok: false }
+            : undefined;
+        }
+        switch (command.controlId) {
+          case 'focus':
+            toolbarElement?.focus();
+            return;
+          case 'reveal':
+            toolbarElement?.scrollIntoView({ block: 'nearest' });
+            return;
+          case 'highlight':
+            surfaceHighlighted = true;
+            if (highlightTimer) clearTimeout(highlightTimer);
+            highlightTimer = setTimeout(() => {
+              surfaceHighlighted = false;
+            }, 1_000);
+            return;
+          case 'refresh':
+            if (!registration.surface.onRefresh) return { ok: false };
+            await registration.surface.onRefresh();
+            return;
+          case 'retry':
+            if (!registration.surface.onRetry) return { ok: false };
+            await registration.surface.onRetry();
+            return;
+          default:
+            return { ok: false };
+        }
+      },
+    });
+    return () => {
+      if (highlightTimer) clearTimeout(highlightTimer);
+      unregister();
+    };
+  });
+  registration.cleanup = cleanup;
+  surfaceRegistration = registration;
+});
+
+onDestroy(() => surfaceRegistration?.cleanup());
 </script>
 
-<div class="toolbar {className}" role="search">
+<div
+  bind:this={toolbarElement}
+  class="toolbar {className}"
+  class:toolbar--highlighted={surfaceHighlighted}
+  role="search"
+  tabindex="-1"
+>
   <div class="search">
-    <Input type="search" name="collection-search" aria-label={searchLabel} placeholder={searchPlaceholder} bind:value={search} oninput={(event) => onsearchchange?.(event.currentTarget.value)} />
+    <Input type="search" name="collection-search" aria-label={searchLabel} placeholder={searchPlaceholder} value={controllerState?.search ?? search} oninput={(event) => changeSearch(event.currentTarget.value)} />
   </div>
   {#if filters}<div class="filters">{@render filters()}</div>{/if}
   {#if resultCount !== undefined}<span class="count" aria-live="polite">{resultCount} {resultCount === 1 ? 'result' : 'results'}</span>{/if}
@@ -64,6 +263,7 @@ function changeView(next: string | number) {
 
 <style>
   .toolbar { display: flex; flex-wrap: wrap; align-items: center; gap: var(--smrt-spacing-2); padding: var(--smrt-spacing-2) 0; color: var(--smrt-color-on-surface); }
+  .toolbar--highlighted { outline: 2px solid var(--smrt-color-primary, #2563eb); outline-offset: 3px; }
   .search { flex: 1 1 14rem; max-width: 24rem; }
   .filters, .actions, .bulk { display: flex; align-items: center; gap: var(--smrt-spacing-2); }
   .bulk { padding: var(--smrt-spacing-1) var(--smrt-spacing-2); border-radius: var(--smrt-radius-small); background: var(--smrt-color-secondary-container); color: var(--smrt-color-on-secondary-container); }

package/dist/components/data/CollectionToolbar.svelte.d.ts

@@ -1,4 +1,6 @@
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
+import type { DataTableController } from './DataTableController.js';
+import type { CollectionToolbarDataSurfaceOptions } from './types.js';
 export interface Props {
     search?: string;
     searchLabel?: string;
@@ -12,6 +14,10 @@ export interface Props {
     bulkActions?: Snippet;
     onsearchchange?: (value: string) => void;
     onviewchange?: (view: 'list' | 'grid' | 'table') => void;
+    /** Shares search state with a DataTable controller when supplied. */
+    controller?: DataTableController;
+    /** Registers this toolbar only when explicitly supplied. */
+    dataSurface?: CollectionToolbarDataSurfaceOptions;
     class?: string;
 }
 declare const CollectionToolbar: import("svelte").Component<Props, {}, "view" | "search">;

package/dist/components/data/CollectionToolbar.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CollectionToolbar.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/data/CollectionToolbar.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKtC,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,KAAK,IAAI,CAAC;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAsDD,QAAA,MAAM,iBAAiB,0DAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"CollectionToolbar.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/data/CollectionToolbar.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,OAAO,EAAW,MAAM,QAAQ,CAAC;AAG1D,OAAO,KAAK,EACV,mBAAmB,EAEpB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,YAAY,CAAC;AAGtE,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,KAAK,IAAI,CAAC;IACzD,qEAAqE;IACrE,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,mCAAmC,CAAC;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA4OD,QAAA,MAAM,iBAAiB,0DAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}