@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/intent/layouts/SearchLayout.svelte

@@ -0,0 +1,65 @@
+<!--
+  SearchLayout.svelte — designed search layout for intent='search' (Wave 3: layouts).
+  Created 2026-06-07.
+  Updated 2026-06-09 — removed redundant role="searchbox" from <input type="search">
+  (<input type="search"> already carries the searchbox role implicitly; recipe 4).
+  Adapted from ocean-flow's SearchLayout. A search field above a results region that
+  COMPOSES CardGridLayout (or, dense, ListLayout) for the matches — so search reuses
+  the same ItemCard rendering path as browse/select. The input is presentational:
+  the host owns the query + the (already-filtered) results, surfaced via onSearch.
+
+  PURE: reads only the adapter's `input` for results; query/selection state are
+  host-owned. No fetch, no service.
+-->
+<script lang="ts">
+  import CardGridLayout from './CardGridLayout.svelte';
+  import ListLayout from './ListLayout.svelte';
+  import type { LayoutInput } from '../layout-adapter.js';
+
+  interface Props {
+    input: LayoutInput;
+    /** Current query text (host-owned). */
+    query?: string;
+    /** Fired on each query change so the host can filter/fetch results. */
+    onSearch?: (q: string) => void;
+    /** Selected result ids (when the search results are selectable). */
+    selectedIds?: string[];
+    onSelect?: (id: string, item: Record<string, unknown>) => void;
+  }
+
+  let { input, query = '', onSearch, selectedIds = [], onSelect }: Props = $props();
+
+  const placeholder = $derived(input.spec.description ?? 'Search…');
+  // A single-column (list) result layout reads better for text-only results.
+  const dense = $derived(!input.meta.showImages);
+</script>
+
+<div class="flex flex-col gap-4">
+  <div class="flex items-center gap-2 rounded-ripple border border-ripple-border bg-ripple-input px-3 py-2.5 focus-within:border-ripple-accent">
+    <svg
+      class="h-4 w-4 shrink-0 text-muted-foreground"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
+    </svg>
+    <input
+      type="search"
+      class="flex-1 bg-transparent text-sm text-ripple-input-foreground outline-none placeholder:text-muted-foreground"
+      {placeholder}
+      value={query}
+      oninput={(e) => onSearch?.(e.currentTarget.value)}
+    />
+  </div>
+
+  {#if dense}
+    <ListLayout {input} {selectedIds} {onSelect} />
+  {:else}
+    <CardGridLayout {input} {selectedIds} {onSelect} />
+  {/if}
+</div>

package/dist/intent/layouts/SearchLayout.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { LayoutInput } from '../layout-adapter.js';
+interface Props {
+    input: LayoutInput;
+    /** Current query text (host-owned). */
+    query?: string;
+    /** Fired on each query change so the host can filter/fetch results. */
+    onSearch?: (q: string) => void;
+    /** Selected result ids (when the search results are selectable). */
+    selectedIds?: string[];
+    onSelect?: (id: string, item: Record<string, unknown>) => void;
+}
+declare const SearchLayout: import("svelte").Component<Props, {}, "">;
+type SearchLayout = ReturnType<typeof SearchLayout>;
+export default SearchLayout;

package/dist/intent/layouts/SelectLayout.svelte

@@ -0,0 +1,131 @@
+<!--
+  SelectLayout.svelte — designed selection layout for intent='select' (Wave 3: layouts).
+
+  Two sub-modes unified here:
+
+  RAW-UI OPTION SET (issue-c fix): A flow `select` step whose raw `ui` tree
+  contains buttons that each emit a flow.next/flow.submit with a `selection` payload
+  is an "option set". extractFlowOptions() finds those buttons and promotes them into
+  OptionList choice cards (layout 'cards': icon from the button's CHOICE_ICONS `icon`
+  key or guessed from its label, `description` as the hint). `display.layout: 'list'`
+  on the step keeps the older one-column rows. Selecting a card re-dispatches the button's EXACT original
+  on_click handler through the live EventDispatcher (same effect as pressing the pill
+  button) — so the FlowRunner advance / chain_map branch works byte-for-byte
+  identically. The rest of the tree (headings, text, images) renders via
+  NodeRenderer above the OptionList, from pruneFlowOptions(): a copy of the tree
+  with those same option buttons removed at any depth and emptied containers
+  dropped, so no choice shows as both a button and a card.
+
+  STREAMING: while the step is still streaming in ('ui-streaming' context), every
+  button is held back, since a button whose on_click has not arrived yet may turn
+  out to be an option. Non-option buttons appear when the stream is done.
+
+  RAW-UI FALLBACK: When the tree has no extractable options (step has a Continue
+  button but not selection buttons), render the (pruned) tree via NodeRenderer so
+  the flow never blocks.
+
+  DATA MODE: When the spec carries structured data (data.items), compose
+  CardGridLayout/ListLayout + selection indicators — the classic browse-with-pick
+  layout used when the AI sends a proper select spec.
+
+  PURE: UI only. No fetch, no service. Selection state is host-owned or is delegated
+  to the EventDispatcher via the existing flow verb contract.
+-->
+<script lang="ts">
+	import { getContext } from 'svelte';
+	import NodeRenderer from '../../components/NodeRenderer.svelte';
+	import OptionList from '../../organisms/OptionList.svelte';
+	import CardGridLayout from './CardGridLayout.svelte';
+	import ListLayout from './ListLayout.svelte';
+	import { extractFlowOptions, pruneFlowOptions } from '../flow-options.js';
+	import type { LayoutInput } from '../layout-adapter.js';
+	import type { EventDispatcher } from '@ripple-ui/core';
+	import type { StateManager } from '../../core/state-manager.svelte.js';
+
+	interface Props {
+		input: LayoutInput;
+		/** Currently selected ids (data mode). */
+		selectedIds?: string[];
+		/** Fired on card selection (data mode). */
+		onSelect?: (id: string, item: Record<string, unknown>) => void;
+	}
+
+	let { input, selectedIds = [], onSelect }: Props = $props();
+
+	// Contexts set by the parent Ripple for every node rendered inside a flow step.
+	const eventDispatcher = getContext<EventDispatcher | undefined>('ui-events');
+	const stateManager = getContext<StateManager | undefined>('ui-state');
+
+	// --- Raw-ui option-set detection -------------------------------------------
+	// In raw-ui mode, attempt to extract flow-option buttons. If any are found we
+	// promote them to OptionList. Non-option siblings (heading, text, etc.) in the
+	// tree still render via NodeRenderer above the list.
+	const rawOptions = $derived(
+		input.mode === 'raw-ui' ? extractFlowOptions(input.spec.ui) : []
+	);
+	const hasOptions = $derived(rawOptions.length > 0);
+
+	// The tree minus the promoted option buttons (any depth), rendered above the
+	// OptionList; the whole tree minus every button while the step streams in.
+	const streamPhase = getContext<(() => 'active' | 'done' | undefined) | undefined>('ui-streaming');
+	const restOfTree = $derived(
+		input.mode === 'raw-ui'
+			? pruneFlowOptions(input.spec.ui, { all: streamPhase?.() === 'active' })
+			: undefined
+	);
+
+	// Tracks the selected option id for aria-checked reflection in OptionList.
+	let selectedOptionId = $state<string | string[]>('');
+	const selectionMode = $derived<'single' | 'multiple'>(
+		input.spec.selection === 'multiple' ? 'multiple' : 'single'
+	);
+
+	function handleOptionSelect(id: string) {
+		// Update local reflection (a toggle in multiple mode).
+		if (selectionMode === 'multiple') {
+			const arr = Array.isArray(selectedOptionId) ? selectedOptionId : [];
+			selectedOptionId = arr.includes(id) ? arr.filter((v) => v !== id) : [...arr, id];
+		} else selectedOptionId = id;
+
+		// Find the matching flow option and re-dispatch its on_click handler through
+		// the live EventDispatcher — same as if the user had clicked the pill button.
+		const opt = rawOptions.find((o) => o.id === id);
+		if (!opt) return;
+		if (eventDispatcher) {
+			void eventDispatcher.dispatch(
+				opt.onClick as Parameters<typeof eventDispatcher.dispatch>[0],
+				{ state: stateManager?.state ?? {} }
+			);
+		}
+	}
+
+	// --- Data mode --------------------------------------------------------------
+	const dense = $derived(input.meta.columns === 1 || !input.meta.showImages);
+</script>
+
+{#if input.mode === 'raw-ui'}
+	{#if hasOptions}
+		<!-- Render any non-option nodes (heading, description text) above the list. -->
+		{#if restOfTree}
+			<NodeRenderer node={restOfTree} />
+		{/if}
+		<!-- Promoted option set: polished cards instead of raw pill buttons. -->
+		<OptionList
+			options={rawOptions.map((o) => ({ id: o.id, text: o.label, description: o.description, icon: o.icon }))}
+			selection={selectionMode}
+			layout={input.spec.display?.layout === 'list' ? 'list' : 'cards'}
+			label={input.spec.title}
+			selected={selectedOptionId}
+			onSelect={handleOptionSelect}
+		/>
+	{:else}
+		<!-- Fallback: no extractable options. The tree as written once streamed in. -->
+		{#if restOfTree}
+			<NodeRenderer node={restOfTree} />
+		{/if}
+	{/if}
+{:else if dense}
+	<ListLayout {input} {selectedIds} {onSelect} />
+{:else}
+	<CardGridLayout {input} {selectedIds} {onSelect} />
+{/if}

package/dist/intent/layouts/SelectLayout.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { LayoutInput } from '../layout-adapter.js';
+interface Props {
+    input: LayoutInput;
+    /** Currently selected ids (data mode). */
+    selectedIds?: string[];
+    /** Fired on card selection (data mode). */
+    onSelect?: (id: string, item: Record<string, unknown>) => void;
+}
+declare const SelectLayout: import("svelte").Component<Props, {}, "">;
+type SelectLayout = ReturnType<typeof SelectLayout>;
+export default SelectLayout;

package/dist/intent/layouts/SlidesLayout.svelte

@@ -0,0 +1,252 @@
+<!--
+  SlidesLayout.svelte — designed layout for the `slides` intent (SP-4).
+  Created 2026-06-28.
+
+  Renders a UniversalSpec as a presentation DECK: one slide per top-level
+  section, one slide visible at a time, with Prev / Next buttons, an "n / total"
+  counter, clickable dots, and Left/Right arrow-key navigation. This is the
+  in-app render-as-deck surface; the later PPTX/MP4 export reads the same
+  partition (slides-partition.ts) so the rendered deck and the exported deck
+  agree on slide boundaries.
+
+  Slide boundaries come from the pure `partitionSlides` helper (spec.sections →
+  spec.ui.children → whole spec.ui → none). Each slide node is rendered through
+  NodeRenderer, so the Ripple context set up by the hosting <Ripple> (state,
+  events, widget resolver) applies unchanged. Only the active slide is mounted —
+  "one slide at a time" is literal, not CSS-hidden — and `{#key}` remounts it on
+  change so no widget state leaks between slides.
+
+  Navigation clamps (no wrap): Prev is disabled on the first slide, Next on the
+  last. Keyboard is wired via <svelte:window> so arrows work without the deck
+  holding focus; it is a11y-safe (no static-element interaction handlers — all
+  on-screen controls are real <button>s).
+
+  PURE render: reads only `spec`. No fetch, no service. The deck index is the
+  one piece of local UI state.
+-->
+<script lang="ts">
+  import NodeRenderer from '../../components/NodeRenderer.svelte';
+  import EmptyState from '../../widgets/display/EmptyState.svelte';
+  import { partitionSlides, clampIndex } from '../slides-partition.js';
+  import type { UniversalSpec } from '@ripple-ui/core';
+
+  interface Props {
+    /** The spec to present. Sections come from ui.children / sections / ui. */
+    spec: UniversalSpec;
+  }
+
+  let { spec }: Props = $props();
+
+  // Ordered slide nodes (pure). Re-derives if the spec changes.
+  const slides = $derived(partitionSlides(spec));
+  const total = $derived(slides.length);
+
+  // The only local state: which slide is showing. Held raw and re-clamped via a
+  // derived so a shrinking deck (fewer slides) can never strand the index out of
+  // range — `current` is always read through `index`.
+  let current = $state(0);
+  const index = $derived(clampIndex(current, total));
+  const activeSlide = $derived(slides[index]);
+
+  function go(to: number) {
+    current = clampIndex(to, total);
+  }
+  function next() {
+    go(index + 1);
+  }
+  function prev() {
+    go(index - 1);
+  }
+
+  // Arrow-key navigation. Window-scoped so the deck doesn't need focus; guarded
+  // to the two arrow keys so it never swallows other input. preventDefault stops
+  // the arrows from also scrolling the page while presenting.
+  function onKeydown(event: KeyboardEvent) {
+    if (total <= 1) return;
+    if (event.key === 'ArrowRight') {
+      event.preventDefault();
+      next();
+    } else if (event.key === 'ArrowLeft') {
+      event.preventDefault();
+      prev();
+    }
+  }
+</script>
+
+<svelte:window onkeydown={onKeydown} />
+
+{#if total === 0}
+  <EmptyState
+    title="No slides"
+    description="This deck has no sections to present. Add children to the spec's ui to create slides."
+    icon="file"
+  />
+{:else}
+  <div class="slides-layout">
+    {#if spec.title || spec.description}
+      <header class="slides-layout__head">
+        {#if spec.title}<h2 class="slides-layout__deck-title">{spec.title}</h2>{/if}
+        {#if spec.description}<p class="slides-layout__deck-sub">{spec.description}</p>{/if}
+      </header>
+    {/if}
+
+    <!-- The stage: one slide at a time. {#key} remounts on slide change so no
+         widget state bleeds across slides. -->
+    <div class="slides-layout__stage">
+      {#key index}
+        <section
+          class="slides-layout__slide"
+          aria-roledescription="slide"
+          aria-label={`Slide ${index + 1} of ${total}`}
+        >
+          {#if activeSlide}
+            <NodeRenderer node={activeSlide} />
+          {/if}
+        </section>
+      {/key}
+    </div>
+
+    <nav class="slides-layout__controls" aria-label="Slide navigation">
+      <button
+        type="button"
+        class="slides-layout__nav"
+        onclick={prev}
+        disabled={index === 0}
+        aria-label="Previous slide"
+      >
+        <span aria-hidden="true">&lsaquo;</span> Prev
+      </button>
+
+      <div class="slides-layout__dots">
+        {#each slides as _slide, i (i)}
+          <button
+            type="button"
+            class="slides-layout__dot"
+            class:is-active={i === index}
+            data-slide-dot={i}
+            aria-label={`Go to slide ${i + 1}`}
+            aria-current={i === index ? 'true' : undefined}
+            onclick={() => go(i)}
+          ></button>
+        {/each}
+      </div>
+
+      <span class="slides-layout__counter" data-total={total} aria-live="polite">
+        {index + 1} / {total}
+      </span>
+
+      <button
+        type="button"
+        class="slides-layout__nav"
+        onclick={next}
+        disabled={index === total - 1}
+        aria-label="Next slide"
+      >
+        Next <span aria-hidden="true">&rsaquo;</span>
+      </button>
+    </nav>
+  </div>
+{/if}
+
+<style>
+  .slides-layout {
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+    width: 100%;
+    max-width: 64rem;
+    margin-inline: auto;
+  }
+  .slides-layout__head {
+    text-align: center;
+  }
+  .slides-layout__deck-title {
+    font-size: 1.125rem;
+    font-weight: 600;
+    color: var(--ripple-muted-foreground, inherit);
+    margin: 0;
+  }
+  .slides-layout__deck-sub {
+    margin: 0.25rem 0 0;
+    font-size: 0.875rem;
+    color: var(--ripple-muted-foreground, inherit);
+    opacity: 0.8;
+  }
+  /* Full-bleed slide surface — generous, centered, presentation-styled. */
+  .slides-layout__stage {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 24rem;
+    padding: 3rem;
+    border: 1px solid var(--ripple-border, var(--border));
+    border-radius: 1rem;
+    background: var(--ripple-card, var(--card));
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
+  }
+  .slides-layout__slide {
+    width: 100%;
+    max-width: 48rem;
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    text-align: center;
+  }
+  .slides-layout__controls {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 1rem;
+  }
+  .slides-layout__nav {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding: 0.5rem 1rem;
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: var(--ripple-foreground, inherit);
+    background: var(--ripple-card, var(--card));
+    border: 1px solid var(--ripple-border, var(--border));
+    border-radius: 0.5rem;
+    cursor: pointer;
+    transition: background 0.15s, border-color 0.15s;
+  }
+  .slides-layout__nav:hover:not(:disabled) {
+    background: var(--ripple-muted, var(--muted));
+  }
+  .slides-layout__nav:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+  .slides-layout__dots {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+  .slides-layout__dot {
+    width: 0.625rem;
+    height: 0.625rem;
+    padding: 0;
+    border-radius: 9999px;
+    border: none;
+    background: var(--ripple-border, var(--border));
+    cursor: pointer;
+    transition: background 0.15s, transform 0.15s;
+  }
+  .slides-layout__dot:hover {
+    background: var(--ripple-muted-foreground, var(--muted-foreground));
+  }
+  .slides-layout__dot.is-active {
+    background: var(--ripple-primary, var(--primary));
+    transform: scale(1.25);
+  }
+  .slides-layout__counter {
+    font-size: 0.8125rem;
+    font-variant-numeric: tabular-nums;
+    color: var(--ripple-muted-foreground, inherit);
+    min-width: 3.5rem;
+    text-align: center;
+  }
+</style>

package/dist/intent/layouts/SlidesLayout.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { UniversalSpec } from '@ripple-ui/core';
+interface Props {
+    /** The spec to present. Sections come from ui.children / sections / ui. */
+    spec: UniversalSpec;
+}
+declare const SlidesLayout: import("svelte").Component<Props, {}, "">;
+type SlidesLayout = ReturnType<typeof SlidesLayout>;
+export default SlidesLayout;

package/dist/intent/layouts/SummaryLayout.svelte

@@ -0,0 +1,84 @@
+<!--
+  SummaryLayout.svelte — designed confirm/summary layout for intent='confirm'.
+  Created 2026-06-07.
+  Updated 2026-06-07 (Wave 3: layouts) — now COMPOSES the ResultsSummary organism
+  (key/value review rows + an optional emphasised total) instead of hand-rolling the
+  row markup. The adapter's rows ({title, subtitle, price}) are mapped to
+  ResultsSummary's {label, value} shape; a row carrying a price becomes the total.
+  Adapted from ocean-flow's SummaryLayout, rendered with ripple organisms.
+
+  DUAL MODE (locked decision C):
+    - 'data'   structured rows (from `data.items`, `form_fields`, or — for a
+               confirm step — the flow's accumulated context) render as a clean
+               key/value review card via ResultsSummary.
+    - 'raw-ui' the step's own `ui` tree (which carries the confirm/Finish button
+               that fires flow.submit) renders via NodeRenderer. When the adapter
+               also surfaced accumulated context, the review rows render ABOVE the
+               tree so the user sees what they chose and the button still works.
+
+  PURE: reads only `input` from the adapter; no fetch / service.
+-->
+<script lang="ts">
+	import NodeRenderer from '../../components/NodeRenderer.svelte';
+	import ResultsSummary from '../../organisms/ResultsSummary.svelte';
+	import type { LayoutInput } from '../layout-adapter.js';
+
+	interface Props {
+		input: LayoutInput;
+	}
+
+	let { input }: Props = $props();
+
+	const fields = $derived(input.fields);
+	const rows = $derived(input.items);
+
+	function field(item: Record<string, unknown>, key: string): unknown {
+		const mapped = fields[key];
+		return mapped ? item[mapped] : undefined;
+	}
+
+	function rowLabel(item: Record<string, unknown>): string {
+		return String(field(item, 'title') ?? item.title ?? item.label ?? '');
+	}
+
+	function rowValue(item: Record<string, unknown>): string {
+		const v =
+			field(item, 'subtitle') ?? field(item, 'description') ?? item.value ?? item.subtitle ?? '';
+		return String(v);
+	}
+
+	function formatPrice(value: unknown): string {
+		if (value == null) return '';
+		const str = String(value);
+		if (str.startsWith('$') || str.startsWith('€') || str.startsWith('£')) return str;
+		return `$${str}`;
+	}
+
+	// A row carrying a price becomes the emphasised total; the rest are plain rows.
+	const totalItem = $derived(rows.find((r) => field(r, 'price') != null));
+	const summaryItems = $derived(
+		rows
+			.filter((r) => r !== totalItem)
+			.map((r) => ({ label: rowLabel(r), value: rowValue(r) }))
+	);
+	const total = $derived(
+		totalItem
+			? { label: rowLabel(totalItem) || 'Total', value: formatPrice(field(totalItem, 'price')) }
+			: undefined
+	);
+	const showSummary = $derived(rows.length > 0);
+</script>
+
+<div class="flex flex-col gap-4">
+	{#if input.spec.ui}
+		<!-- The step's own tree carries BOTH the review text AND the Finish/confirm
+		     button (→ flow.submit, the terminal hand-off to the agent). Render it so
+		     the flow can actually complete. We do NOT also render ResultsSummary here
+		     — that would duplicate the review rows. The designed ResultsSummary path
+		     below is for a pure-data confirm spec with no ui. Wiring ResultsSummary +
+		     a flow.submit button for the data path is a tracked follow-up. -->
+		<NodeRenderer node={input.spec.ui} />
+	{:else if showSummary}
+		<ResultsSummary items={summaryItems} {total} />
+	{/if}
+</div>

package/dist/intent/layouts/SummaryLayout.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { LayoutInput } from '../layout-adapter.js';
+interface Props {
+    input: LayoutInput;
+}
+declare const SummaryLayout: import("svelte").Component<Props, {}, "">;
+type SummaryLayout = ReturnType<typeof SummaryLayout>;
+export default SummaryLayout;

package/dist/intent/layouts/TableLayout.svelte

@@ -0,0 +1,100 @@
+<!--
+  TableLayout.svelte — designed table layout (Wave 3: ported layouts).
+  Created 2026-06-07.
+  Ripple-native port of ocean-flow's TableLayout. Composes ripple's existing
+  Table widget (widgets/data/Table.svelte) — no shadcn table primitives imported
+  directly here. The adapter feeds structured `items`; columns are derived from
+  the field mapping (title → Name, subtitle → Description, etc.) so any spec
+  with `display.layout='table'` renders a sortable, searchable table without
+  additional config.
+
+  Routed for the `table` display hint (display.layout='table'). PURE — reads
+  only `input` from the adapter, no fetch / service. No top-level $state
+  (child-only component — avoids the repo's mounted-entry $state flake).
+-->
+<script lang="ts">
+  import TableWidget from '../../widgets/data/Table.svelte';
+  import EmptyState from '../../widgets/display/EmptyState.svelte';
+  import type { LayoutInput } from '../layout-adapter.js';
+
+  interface Props {
+    input: LayoutInput;
+    /** Called when the user clicks a row. */
+    onRowSelect?: (item: Record<string, unknown>) => void;
+  }
+
+  let { input, onRowSelect }: Props = $props();
+
+  const fields = $derived(input.fields);
+  const items = $derived(input.items);
+
+  // Derive columns from the field mapping. We prefer a curated set (title →
+  // "Name", subtitle → "Description", price, status, location) so the table
+  // reads naturally out of the box. Keys whose mapped path doesn't exist in
+  // the data are skipped — the column array is spec-driven, not hard-coded.
+  const columns = $derived.by(() => {
+    const cols: { header: string; accessorKey: string }[] = [];
+    const SEMANTIC_COLS: [string, string][] = [
+      ['title', 'Name'],
+      ['subtitle', 'Description'],
+      ['status', 'Status'],
+      ['price', 'Price'],
+      ['location', 'Location'],
+      ['date', 'Date'],
+      ['icon', 'Icon'],
+    ];
+
+    for (const [semantic, header] of SEMANTIC_COLS) {
+      const mapped = fields[semantic];
+      if (mapped && items.some((r) => mapped in r)) {
+        cols.push({ header, accessorKey: mapped });
+      }
+    }
+
+    // Fall back to all keys of the first item when the field map yields nothing.
+    if (cols.length === 0 && items.length > 0) {
+      return Object.keys(items[0]).map((k) => ({
+        header: k.charAt(0).toUpperCase() + k.slice(1).replace(/_/g, ' '),
+        accessorKey: k,
+      }));
+    }
+
+    return cols;
+  });
+</script>
+
+{#if items.length === 0}
+  <EmptyState title="No data" description="There is nothing to display in this table." icon="table" />
+{:else}
+  <div class="table-layout">
+    {#if input.title}
+      <h2 class="table-layout__title">{input.title}</h2>
+    {/if}
+    {#if input.description}
+      <p class="table-layout__description">{input.description}</p>
+    {/if}
+    <TableWidget
+      data={items}
+      {columns}
+      sortable
+      searchable={items.length > 8}
+    />
+  </div>
+{/if}
+
+<style>
+  .table-layout {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+  .table-layout__title {
+    font-size: 1.125rem;
+    font-weight: 600;
+    color: var(--ripple-foreground, inherit);
+  }
+  .table-layout__description {
+    font-size: 0.875rem;
+    color: var(--ripple-muted-foreground, inherit);
+  }
+</style>