terminoir 0.7.0 → 0.8.0

package/README.md

@@ -14,7 +14,7 @@ To try unreleased changes in an app, `pnpm link /path/to/terminoir` from the app
 
 ### Releasing
 
-Bump `version` (semver: new component or prop → minor; breaking prop/CSS change → major), then `npm publish` (`prepublishOnly` builds and tests). Apps bump their `terminoir` range to adopt.
+Bump `version` (semver: new component or prop → minor; breaking prop/CSS change → major), then push `main`. The `Publish` workflow (`.github/workflows/publish.yml`) publishes any version not yet on npm via trusted publishing (`prepublishOnly` checks, builds and tests first); don't publish from a laptop. Apps bump their `terminoir` range to adopt.
 
 Peer dependency: **Svelte 5** (for components). Optional **React 18–19** for `terminoir/react`. CSS-only consumers can import styles without JS.
 
@@ -160,6 +160,10 @@ Building blocks so apps compose screens without CSS of their own. See the demo's
 | `CanvasStage`, `DocumentViewer` | Full-bleed canvas host with floating overlay and side panel; paged viewer with toolbar and highlight marks |
 | `AccentSwatches` | `bind:value` accent hex from `ACCENT_PALETTE` |
 | `GroupedList`, `SegmentBar` | Items in labelled groups with a colour dot and count, "Show n more" past `limit`, `collapsed` groups behind a toggle (e.g. finished items); a thin bar of proportional coloured segments |
+| `Timeline` | Gantt rows: a title column and bars from `start` to `end` (inclusive, or one day) on a shared day scale, grouped under headings, today marked; `TimelineItem` |
+| `BucketGrid` | Board columns or a 2×2 `quadrants` grid of drop zones with a heading, colour dot and count; the caller renders cards (`children(bucket)`) and sets `dragType`; `ondrop(key, payload)`, `droppable: false` refuses drops |
+| `GridLayout` | Items in reading order on a 12-column grid: drag the move handle (`children(item, handle)` renders it where you want) to reorder, drag the right edge to change span (`minSpan`); arrow keys do both; `onchange(items)` on release |
+| `ExpressionEditor` | Scratch-style block editor for a typed expression tree from an op catalogue (`ExpressionOp`: returns, slots with kinds, params); slots only offer ops whose result fits; params named `key` pick from `fields`; plain-English reading underneath (`describeExpression`) |
 
 `labelColor(name)` resolves palette names (`green`, `gray`…, see `LABEL_PALETTE`) or passes CSS colours through; `Chip`, `GroupedList` and `SegmentBar` share it.
 

package/dist/components/BucketGrid.svelte

@@ -0,0 +1,109 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { cn } from '../utils/cn.js';
+  import { labelColor } from '../utils/palette.js';
+
+  export type Bucket = {
+    key: string;
+    label: string;
+    /** Palette name or CSS colour for the heading dot. */
+    color?: string | null;
+    count: number;
+    /** False to refuse drops (e.g. an Unsorted cell that cannot be written). */
+    droppable?: boolean;
+  };
+
+  /**
+   * Board columns or a 2x2 matrix of drop zones. Callers render each bucket's cards with
+   * `children` and make them draggable with `dragType`; `ondrop` gets the dropped payload.
+   */
+  let {
+    buckets,
+    layout = 'columns',
+    dragType,
+    label,
+    ondrop,
+    children,
+    class: className = '',
+  }: {
+    buckets: Bucket[];
+    /** `columns` side by side (wrapping on phones), or `quadrants` (2x2, first four buckets). */
+    layout?: 'columns' | 'quadrants';
+    /** The `DataTransfer` type the cards set; other drags are ignored. */
+    dragType: string;
+    /** Accessible name for the grid. */
+    label: string;
+    ondrop: (bucketKey: string, payload: string) => void;
+    children: Snippet<[Bucket]>;
+    class?: string;
+  } = $props();
+
+  let over = $state<string | null>(null);
+
+  function accepts(event: DragEvent, bucket: Bucket): boolean {
+    return bucket.droppable !== false && !!event.dataTransfer?.types.includes(dragType);
+  }
+
+  function dragOver(event: DragEvent, bucket: Bucket) {
+    if (!accepts(event, bucket)) return;
+    event.preventDefault();
+    over = bucket.key;
+  }
+
+  function drop(event: DragEvent, bucket: Bucket) {
+    over = null;
+    if (!accepts(event, bucket)) return;
+    event.preventDefault();
+    const payload = event.dataTransfer?.getData(dragType);
+    if (payload) ondrop(bucket.key, payload);
+  }
+</script>
+
+<div class={cn('terminoir-buckets', `terminoir-buckets--${layout}`, className)} role="group" aria-label={label}>
+  {#each buckets as bucket (bucket.key)}
+    <section
+      class="terminoir-buckets__zone"
+      class:terminoir-buckets__zone--over={over === bucket.key}
+      aria-label={bucket.label}
+      ondragover={(event) => dragOver(event, bucket)}
+      ondragleave={() => (over = over === bucket.key ? null : over)}
+      ondrop={(event) => drop(event, bucket)}
+    >
+      <header class="terminoir-buckets__head">
+        <span class="terminoir-buckets__dot" style:background={labelColor(bucket.color) ?? 'var(--muted-foreground)'}></span>
+        <span class="terminoir-buckets__label">{bucket.label}</span>
+        <span class="terminoir-buckets__count">{bucket.count}</span>
+      </header>
+      <div class="terminoir-buckets__items">{@render children(bucket)}</div>
+    </section>
+  {/each}
+</div>
+
+<style>
+  .terminoir-buckets { display: grid; gap: var(--space-3); min-width: 0; }
+  .terminoir-buckets--columns { grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); }
+  .terminoir-buckets--quadrants { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  @media (max-width: 640px) {
+    .terminoir-buckets--quadrants { grid-template-columns: minmax(0, 1fr); }
+  }
+  .terminoir-buckets__zone {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+    min-width: 0;
+    padding: var(--space-3);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    background: color-mix(in srgb, var(--foreground) 3%, transparent);
+    transition: border-color 120ms ease, background 120ms ease;
+  }
+  .terminoir-buckets__zone--over {
+    border-color: var(--primary);
+    background: color-mix(in srgb, var(--primary) 10%, transparent);
+  }
+  .terminoir-buckets__head { display: flex; align-items: center; gap: var(--space-2); font-size: 0.8125rem; }
+  .terminoir-buckets__dot { width: 0.5rem; height: 0.5rem; border-radius: 50%; flex: none; }
+  .terminoir-buckets__label { font-weight: 600; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .terminoir-buckets__count { color: var(--muted-foreground); font-variant-numeric: tabular-nums; }
+  .terminoir-buckets__items { display: flex; flex-direction: column; gap: var(--space-2); min-height: 2.5rem; }
+</style>

package/dist/components/BucketGrid.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { Snippet } from 'svelte';
+export type Bucket = {
+    key: string;
+    label: string;
+    /** Palette name or CSS colour for the heading dot. */
+    color?: string | null;
+    count: number;
+    /** False to refuse drops (e.g. an Unsorted cell that cannot be written). */
+    droppable?: boolean;
+};
+type $$ComponentProps = {
+    buckets: Bucket[];
+    /** `columns` side by side (wrapping on phones), or `quadrants` (2x2, first four buckets). */
+    layout?: 'columns' | 'quadrants';
+    /** The `DataTransfer` type the cards set; other drags are ignored. */
+    dragType: string;
+    /** Accessible name for the grid. */
+    label: string;
+    ondrop: (bucketKey: string, payload: string) => void;
+    children: Snippet<[Bucket]>;
+    class?: string;
+};
+declare const BucketGrid: import("svelte").Component<$$ComponentProps, {}, "">;
+type BucketGrid = ReturnType<typeof BucketGrid>;
+export default BucketGrid;

package/dist/components/ExpressionEditor.svelte

@@ -0,0 +1,186 @@
+<script lang="ts">
+  import { cn } from '../utils/cn.js';
+  import {
+    describe,
+    emptyNode,
+    groupOps,
+    isComplete,
+    opsFor,
+    paramText,
+    parseParam,
+    setAt,
+    type ExpressionField,
+    type ExpressionKind,
+    type ExpressionNode,
+    type ExpressionOp,
+    type ExpressionPath,
+    type ExpressionSlot,
+  } from '../utils/expression.js';
+  import IconButton from './IconButton.svelte';
+  import NavIcon from './NavIcon.svelte';
+
+  /**
+   * Scratch-style block editor for a typed expression tree. Each block is one node; its slots only
+   * offer ops whose result fits, so the tree is always well-typed. A plain-English reading sits
+   * under the blocks.
+   */
+  let {
+    ops,
+    fields = [],
+    value,
+    kind = 'boolean',
+    label,
+    onchange,
+    class: className = '',
+  }: {
+    /** The op catalogue, e.g. Oyster's `GET /expressions/ops`. */
+    ops: ExpressionOp[];
+    /** Fields a `key` param can name. */
+    fields?: ExpressionField[];
+    value: ExpressionNode | null;
+    /** What the whole expression must return. */
+    kind?: ExpressionKind;
+    /** Accessible name for the editor. */
+    label: string;
+    onchange: (value: ExpressionNode | null) => void;
+    class?: string;
+  } = $props();
+
+  const NONE = '';
+  const reading = $derived(value ? describe(value, ops, fields) : 'Nothing yet');
+  const complete = $derived(value ? isComplete(value, ops) : true);
+
+  function specOf(node: ExpressionNode | null): ExpressionOp | undefined {
+    return node ? ops.find((o) => o.op === node.op) : undefined;
+  }
+
+  function update(path: ExpressionPath, next: unknown) {
+    onchange(setAt(value, path, next) as ExpressionNode | null);
+  }
+
+  function choose(path: ExpressionPath, opName: string) {
+    const spec = ops.find((o) => o.op === opName);
+    update(path, spec ? emptyNode(spec) : null);
+  }
+</script>
+
+{#snippet picker(slotKind: ExpressionKind, path: ExpressionPath, current: string, pickerLabel: string)}
+  <select
+    class="terminoir-select terminoir-expr__pick terminoir-focusable"
+    aria-label={pickerLabel}
+    value={current}
+    onchange={(e) => {
+      const select = e.currentTarget as HTMLSelectElement;
+      choose(path, select.value);
+      // An "add" picker (no current op) goes back to its prompt for the next entry.
+      if (!current) select.value = NONE;
+    }}
+  >
+    <option value={NONE}>{current ? 'Remove' : 'Choose…'}</option>
+    {#each groupOps(opsFor(slotKind, ops)) as group (group.group)}
+      <optgroup label={group.group}>
+        {#each group.ops as op (op.op)}<option value={op.op}>{op.label}</option>{/each}
+      </optgroup>
+    {/each}
+  </select>
+{/snippet}
+
+{#snippet param(node: ExpressionNode, name: string, path: ExpressionPath)}
+  {#if name === 'key'}
+    <select
+      class="terminoir-select terminoir-expr__pick terminoir-focusable"
+      aria-label="Field"
+      value={String(node.key ?? '')}
+      onchange={(e) => update([...path, 'key'], (e.currentTarget as HTMLSelectElement).value)}
+    >
+      <option value="">Field…</option>
+      {#each fields as field (field.key)}<option value={field.key}>{field.label ?? field.key}</option>{/each}
+    </select>
+  {:else}
+    <input
+      class="terminoir-input terminoir-expr__param terminoir-focusable"
+      aria-label={name}
+      placeholder={name === 'options' ? 'a, b, c' : name}
+      value={paramText(node[name])}
+      onchange={(e) => update([...path, name], parseParam(name, (e.currentTarget as HTMLInputElement).value))}
+    />
+  {/if}
+{/snippet}
+
+{#snippet slotView(node: ExpressionNode, slot: ExpressionSlot, path: ExpressionPath)}
+  <div class="terminoir-expr__slot">
+    <span class="terminoir-expr__slot-name">{slot.name}</span>
+    {#if slot.many}
+      {@const list = Array.isArray(node[slot.name]) ? (node[slot.name] as ExpressionNode[]) : []}
+      <div class="terminoir-expr__list">
+        {#each list as child, i (i)}
+          <div class="terminoir-expr__entry">
+            {@render block(child, slot.kind, [...path, slot.name, i])}
+            <IconButton label={`Remove ${slot.name} ${i + 1}`} size="sm" onclick={() => update([...path, slot.name, i], undefined)}>
+              <NavIcon name="xmark" />
+            </IconButton>
+          </div>
+        {/each}
+        {@render picker(slot.kind, [...path, slot.name, list.length], NONE, `Add to ${slot.name}`)}
+      </div>
+    {:else}
+      {@render block((node[slot.name] as ExpressionNode | null) ?? null, slot.kind, [...path, slot.name])}
+    {/if}
+  </div>
+{/snippet}
+
+{#snippet block(node: ExpressionNode | null, slotKind: ExpressionKind, path: ExpressionPath)}
+  {@const spec = specOf(node)}
+  <div class="terminoir-expr__block" class:terminoir-expr__block--empty={!node} data-kind={spec?.returns ?? slotKind}>
+    <div class="terminoir-expr__head">
+      {@render picker(slotKind, path, node?.op ?? NONE, path.length ? `Block at ${path.join(' ')}` : 'Expression')}
+      {#if node && spec}
+        {#each spec.params as name (name)}{@render param(node, name, path)}{/each}
+      {/if}
+    </div>
+    {#if node && spec?.slots.length}
+      <div class="terminoir-expr__slots">
+        {#each spec.slots as slot (slot.name)}{@render slotView(node, slot, path)}{/each}
+      </div>
+    {/if}
+  </div>
+{/snippet}
+
+<div class={cn('terminoir-expr', className)} role="group" aria-label={label}>
+  {@render block(value, kind, [])}
+  <p class="terminoir-expr__reading" class:terminoir-expr__reading--incomplete={!complete}>
+    {reading}{#if !complete} <span>(unfinished)</span>{/if}
+  </p>
+</div>
+
+<style>
+  .terminoir-expr { display: flex; flex-direction: column; gap: var(--space-2); min-width: 0; font-size: 0.8125rem; }
+  .terminoir-expr__block {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+    padding: var(--space-2);
+    border: 1px solid var(--border);
+    border-left: 3px solid var(--block-accent, var(--primary));
+    border-radius: var(--radius);
+    background: color-mix(in srgb, var(--foreground) 3%, transparent);
+    min-width: 0;
+  }
+  .terminoir-expr__block[data-kind='boolean'] { --block-accent: var(--primary); }
+  .terminoir-expr__block[data-kind='number'] { --block-accent: #3b82f6; }
+  .terminoir-expr__block[data-kind='date'] { --block-accent: #f59e0b; }
+  .terminoir-expr__block[data-kind='value'],
+  .terminoir-expr__block[data-kind='text'] { --block-accent: #10b981; }
+  .terminoir-expr__block--empty { border-style: dashed; background: transparent; }
+  .terminoir-expr__head { display: flex; flex-wrap: wrap; gap: var(--space-2); align-items: center; }
+  .terminoir-expr__pick { width: auto; min-width: 8rem; }
+  .terminoir-expr__param { width: 9rem; }
+  .terminoir-expr__slots { display: flex; flex-direction: column; gap: var(--space-2); padding-left: var(--space-3); }
+  .terminoir-expr__slot { display: flex; flex-direction: column; gap: var(--space-1); }
+  .terminoir-expr__slot-name { color: var(--muted-foreground); font-size: 0.6875rem; text-transform: uppercase; letter-spacing: 0.04em; }
+  .terminoir-expr__list { display: flex; flex-direction: column; gap: var(--space-2); }
+  .terminoir-expr__entry { display: flex; gap: var(--space-1); align-items: flex-start; }
+  .terminoir-expr__entry > :first-child { flex: 1; }
+  .terminoir-expr__reading { margin: 0; color: var(--muted-foreground); }
+  .terminoir-expr__reading--incomplete span { color: var(--danger, #ef4444); }
+</style>

package/dist/components/ExpressionEditor.svelte.d.ts

@@ -0,0 +1,17 @@
+import { type ExpressionField, type ExpressionKind, type ExpressionNode, type ExpressionOp } from '../utils/expression.js';
+type $$ComponentProps = {
+    /** The op catalogue, e.g. Oyster's `GET /expressions/ops`. */
+    ops: ExpressionOp[];
+    /** Fields a `key` param can name. */
+    fields?: ExpressionField[];
+    value: ExpressionNode | null;
+    /** What the whole expression must return. */
+    kind?: ExpressionKind;
+    /** Accessible name for the editor. */
+    label: string;
+    onchange: (value: ExpressionNode | null) => void;
+    class?: string;
+};
+declare const ExpressionEditor: import("svelte").Component<$$ComponentProps, {}, "">;
+type ExpressionEditor = ReturnType<typeof ExpressionEditor>;
+export default ExpressionEditor;

package/dist/components/GridLayout.svelte

@@ -0,0 +1,194 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { cn } from '../utils/cn.js';
+  import { moveTo, nearestIndex, spanAfterDrag, type GridItem } from '../utils/layout.js';
+  import NavIcon from './NavIcon.svelte';
+
+  /**
+   * Items in reading order on a column grid. Drag an item's move handle (render `handle` where it
+   * belongs, e.g. in a header) to reorder; drag its right edge to change its column span. Both
+   * have keyboard equivalents (arrow keys). `onchange` gets the new order and spans when a drag ends.
+   */
+  let {
+    items,
+    columns = 12,
+    minSpan = 3,
+    label,
+    onchange,
+    children,
+    class: className = '',
+  }: {
+    items: GridItem[];
+    columns?: number;
+    minSpan?: number;
+    /** Accessible name for the grid. */
+    label: string;
+    onchange: (items: GridItem[]) => void;
+    children: Snippet<[GridItem, Snippet]>;
+    class?: string;
+  } = $props();
+
+  let draft = $state<GridItem[] | null>(null);
+  const shown = $derived(draft ?? items);
+  let grid: HTMLDivElement | undefined = $state();
+
+  function cells(): HTMLElement[] {
+    return grid ? [...grid.querySelectorAll<HTMLElement>(':scope > .terminoir-grid__cell')] : [];
+  }
+
+  function commit() {
+    if (draft) onchange(draft);
+    draft = null;
+  }
+
+  function startMove(event: PointerEvent, id: string) {
+    const handle = event.currentTarget as HTMLElement;
+    handle.setPointerCapture(event.pointerId);
+    draft = items.slice();
+    const move = (e: PointerEvent) => {
+      const centres = cells().map((cell) => {
+        const r = cell.getBoundingClientRect();
+        return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+      });
+      if (draft) draft = moveTo(draft, id, nearestIndex(centres, e.clientX, e.clientY));
+    };
+    const end = () => {
+      handle.removeEventListener('pointermove', move);
+      handle.removeEventListener('pointerup', end);
+      handle.removeEventListener('pointercancel', end);
+      commit();
+    };
+    handle.addEventListener('pointermove', move);
+    handle.addEventListener('pointerup', end);
+    handle.addEventListener('pointercancel', end);
+  }
+
+  function startResize(event: PointerEvent, item: GridItem) {
+    const edge = event.currentTarget as HTMLElement;
+    edge.setPointerCapture(event.pointerId);
+    const startX = event.clientX;
+    const columnWidth = (grid?.clientWidth ?? 0) / columns;
+    draft = items.slice();
+    const move = (e: PointerEvent) => {
+      const span = spanAfterDrag(item.span, e.clientX - startX, columnWidth, minSpan, columns);
+      if (draft) draft = draft.map((i) => (i.id === item.id ? { ...i, span } : i));
+    };
+    const end = () => {
+      edge.removeEventListener('pointermove', move);
+      edge.removeEventListener('pointerup', end);
+      edge.removeEventListener('pointercancel', end);
+      commit();
+    };
+    edge.addEventListener('pointermove', move);
+    edge.addEventListener('pointerup', end);
+    edge.addEventListener('pointercancel', end);
+  }
+
+  function keyMove(event: KeyboardEvent, id: string) {
+    const step = { ArrowUp: -1, ArrowLeft: -1, ArrowDown: 1, ArrowRight: 1 }[event.key];
+    if (!step) return;
+    event.preventDefault();
+    const index = items.findIndex((i) => i.id === id);
+    onchange(moveTo(items, id, index + step));
+  }
+
+  function keyResize(event: KeyboardEvent, item: GridItem) {
+    const step = { ArrowLeft: -1, ArrowRight: 1 }[event.key];
+    if (!step) return;
+    event.preventDefault();
+    const span = Math.max(minSpan, Math.min(columns, item.span + step));
+    if (span !== item.span) onchange(items.map((i) => (i.id === item.id ? { ...i, span } : i)));
+  }
+</script>
+
+<div
+  bind:this={grid}
+  class={cn('terminoir-grid', draft && 'terminoir-grid--dragging', className)}
+  style:--grid-columns={columns}
+  role="list"
+  aria-label={label}
+>
+  {#each shown as item (item.id)}
+    {#snippet handle()}
+      <button
+        type="button"
+        class="terminoir-grid__move terminoir-focusable"
+        aria-label="Move (drag, or use arrow keys)"
+        title="Drag to move"
+        onpointerdown={(event) => startMove(event, item.id)}
+        onkeydown={(event) => keyMove(event, item.id)}
+      >
+        <NavIcon name="grip-vertical" />
+      </button>
+    {/snippet}
+    <div class="terminoir-grid__cell" style:--span={Math.min(item.span, columns)} role="listitem">
+      {@render children(item, handle)}
+      <button
+        type="button"
+        class="terminoir-grid__resize terminoir-focusable"
+        aria-label={`Width ${item.span} of ${columns} columns (drag, or use left and right arrows)`}
+        title="Drag to resize"
+        onpointerdown={(event) => startResize(event, item)}
+        onkeydown={(event) => keyResize(event, item)}
+      ></button>
+    </div>
+  {/each}
+</div>
+
+<style>
+  .terminoir-grid {
+    display: grid;
+    grid-template-columns: repeat(var(--grid-columns), minmax(0, 1fr));
+    gap: var(--space-4);
+    align-items: start;
+    min-width: 0;
+  }
+  .terminoir-grid__cell { position: relative; grid-column: span var(--span); min-width: 0; }
+  @media (max-width: 700px) {
+    .terminoir-grid__cell { grid-column: 1 / -1; }
+    .terminoir-grid__resize { display: none; }
+  }
+  .terminoir-grid--dragging { user-select: none; }
+  .terminoir-grid--dragging .terminoir-grid__cell { transition: none; }
+  .terminoir-grid__move {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    padding: 0;
+    border: 0;
+    border-radius: var(--radius-sm, 0.375rem);
+    background: transparent;
+    color: var(--muted-foreground);
+    cursor: grab;
+    touch-action: none;
+  }
+  .terminoir-grid__move:active { cursor: grabbing; }
+  .terminoir-grid__move:hover { color: var(--foreground); background: color-mix(in srgb, var(--foreground) 8%, transparent); }
+  .terminoir-grid__resize {
+    position: absolute;
+    top: var(--space-3);
+    bottom: var(--space-3);
+    right: calc(var(--space-2) * -1);
+    width: var(--space-3);
+    padding: 0;
+    border: 0;
+    background: transparent;
+    cursor: ew-resize;
+    touch-action: none;
+  }
+  .terminoir-grid__resize::after {
+    content: '';
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 50%;
+    width: 2px;
+    border-radius: 1px;
+    background: transparent;
+    transition: background 120ms ease;
+  }
+  .terminoir-grid__resize:hover::after,
+  .terminoir-grid__resize:focus-visible::after { background: var(--primary); }
+</style>

package/dist/components/GridLayout.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from 'svelte';
+import { type GridItem } from '../utils/layout.js';
+type $$ComponentProps = {
+    items: GridItem[];
+    columns?: number;
+    minSpan?: number;
+    /** Accessible name for the grid. */
+    label: string;
+    onchange: (items: GridItem[]) => void;
+    children: Snippet<[GridItem, Snippet]>;
+    class?: string;
+};
+declare const GridLayout: import("svelte").Component<$$ComponentProps, {}, "">;
+type GridLayout = ReturnType<typeof GridLayout>;
+export default GridLayout;

package/dist/components/Timeline.svelte

@@ -0,0 +1,130 @@
+<script lang="ts">
+  import { cn } from '../utils/cn.js';
+  import { labelColor } from '../utils/palette.js';
+  import { timelineRows, timelineScale, todayOffset, type TimelineItem } from '../utils/timeline.js';
+
+  /** Gantt-style bars over a shared day scale; one row per item, grouped under headings. */
+  let {
+    items,
+    label,
+    onItemClick,
+    class: className = '',
+  }: {
+    items: TimelineItem[];
+    /** Accessible name for the chart. */
+    label: string;
+    onItemClick?: (item: TimelineItem) => void;
+    class?: string;
+  } = $props();
+
+  const scale = $derived(timelineScale(items));
+  const rows = $derived(timelineRows(items, scale));
+  const today = $derived(todayOffset(scale));
+
+  function day(d: Date): string {
+    return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+  }
+
+  function range(item: TimelineItem): string {
+    return item.end && item.end.getTime() !== item.start.getTime() ? `${day(item.start)} – ${day(item.end)}` : day(item.start);
+  }
+</script>
+
+<div class={cn('terminoir-timeline', className)} role="group" aria-label={label}>
+  <div class="terminoir-timeline__grid">
+    <div class="terminoir-timeline__corner" aria-hidden="true"></div>
+    <div class="terminoir-timeline__scale" aria-hidden="true">
+      {#each scale.ticks as tick (tick.date.getTime())}
+        <span class="terminoir-timeline__tick" style:left={`${tick.left}%`}>{day(tick.date)}</span>
+      {/each}
+    </div>
+    {#each rows as row (row.group ?? '')}
+      {#if row.group}<div class="terminoir-timeline__group">{row.group}</div>{/if}
+      {#each row.bars as bar (bar.item.id)}
+        <div class="terminoir-timeline__label" title={bar.item.title}>{bar.item.title}</div>
+        <div class="terminoir-timeline__track">
+          {#if today !== null}<div class="terminoir-timeline__today" style:left={`${today}%`} aria-hidden="true"></div>{/if}
+          <button
+            type="button"
+            class="terminoir-timeline__bar terminoir-focusable"
+            style:left={`${bar.left}%`}
+            style:width={`${bar.width}%`}
+            style:--bar-color={labelColor(bar.item.color) ?? 'var(--primary)'}
+            aria-label={`${bar.item.title}, ${range(bar.item)}`}
+            title={`${bar.item.title} · ${range(bar.item)}`}
+            disabled={!onItemClick}
+            onclick={() => onItemClick?.(bar.item)}
+          ></button>
+        </div>
+      {/each}
+    {/each}
+  </div>
+</div>
+
+<style>
+  .terminoir-timeline {
+    --timeline-row: 1.75rem;
+    --timeline-label: minmax(8rem, 14rem);
+    font-size: 0.8125rem;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    overflow-x: auto;
+    min-width: 0;
+  }
+  .terminoir-timeline__grid {
+    display: grid;
+    grid-template-columns: var(--timeline-label) minmax(24rem, 1fr);
+    min-width: 0;
+    padding-bottom: var(--space-1);
+  }
+  .terminoir-timeline__corner,
+  .terminoir-timeline__scale { height: 1.75rem; border-bottom: 1px solid var(--border); }
+  .terminoir-timeline__scale { position: relative; color: var(--muted-foreground); font-size: 0.6875rem; }
+  .terminoir-timeline__tick {
+    position: absolute;
+    top: 0.5rem;
+    padding-left: 0.25rem;
+    border-left: 1px solid color-mix(in srgb, var(--border) 70%, transparent);
+    white-space: nowrap;
+  }
+  .terminoir-timeline__group {
+    grid-column: 1 / -1;
+    padding: var(--space-2) var(--space-2) var(--space-1);
+    color: var(--muted-foreground);
+    font-size: 0.6875rem;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+  .terminoir-timeline__label {
+    display: flex;
+    align-items: center;
+    height: var(--timeline-row);
+    padding: 0 var(--space-2);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .terminoir-timeline__track { position: relative; height: var(--timeline-row); }
+  .terminoir-timeline__today {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    width: 1px;
+    background: var(--primary);
+    opacity: 0.5;
+    pointer-events: none;
+  }
+  .terminoir-timeline__bar {
+    position: absolute;
+    top: 0.375rem;
+    bottom: 0.375rem;
+    min-width: 0.5rem;
+    padding: 0;
+    border: 1px solid color-mix(in srgb, var(--bar-color) 70%, transparent);
+    border-radius: var(--radius-pill);
+    background: color-mix(in srgb, var(--bar-color) 45%, transparent);
+    cursor: pointer;
+  }
+  .terminoir-timeline__bar:disabled { cursor: default; }
+  .terminoir-timeline__bar:hover:not(:disabled) { background: color-mix(in srgb, var(--bar-color) 65%, transparent); }
+</style>

package/dist/components/Timeline.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type TimelineItem } from '../utils/timeline.js';
+type $$ComponentProps = {
+    items: TimelineItem[];
+    /** Accessible name for the chart. */
+    label: string;
+    onItemClick?: (item: TimelineItem) => void;
+    class?: string;
+};
+declare const Timeline: import("svelte").Component<$$ComponentProps, {}, "">;
+type Timeline = ReturnType<typeof Timeline>;
+export default Timeline;

package/dist/index.d.ts

@@ -47,6 +47,14 @@ export { default as Inline } from './components/Inline.svelte';
 export { default as Text } from './components/Text.svelte';
 export { default as Disclosure } from './components/Disclosure.svelte';
 export { default as GroupedList } from './components/GroupedList.svelte';
+export { default as Timeline } from './components/Timeline.svelte';
+export type { TimelineItem } from './utils/timeline.js';
+export { default as BucketGrid } from './components/BucketGrid.svelte';
+export type { Bucket } from './components/BucketGrid.svelte';
+export { default as GridLayout } from './components/GridLayout.svelte';
+export type { GridItem } from './utils/layout.js';
+export { default as ExpressionEditor } from './components/ExpressionEditor.svelte';
+export { describe as describeExpression, isComplete as isCompleteExpression, type ExpressionField, type ExpressionKind, type ExpressionNode, type ExpressionOp, type ExpressionSlot, } from './utils/expression.js';
 export type { GroupedListGroup, GroupedListItem } from './components/GroupedList.svelte';
 export { default as SegmentBar } from './components/SegmentBar.svelte';
 export type { Segment } from './components/SegmentBar.svelte';

package/dist/index.js

@@ -46,6 +46,11 @@ export { default as Inline } from './components/Inline.svelte';
 export { default as Text } from './components/Text.svelte';
 export { default as Disclosure } from './components/Disclosure.svelte';
 export { default as GroupedList } from './components/GroupedList.svelte';
+export { default as Timeline } from './components/Timeline.svelte';
+export { default as BucketGrid } from './components/BucketGrid.svelte';
+export { default as GridLayout } from './components/GridLayout.svelte';
+export { default as ExpressionEditor } from './components/ExpressionEditor.svelte';
+export { describe as describeExpression, isComplete as isCompleteExpression, } from './utils/expression.js';
 export { default as SegmentBar } from './components/SegmentBar.svelte';
 export { default as NavSection } from './components/NavSection.svelte';
 export { default as Spacer } from './components/Spacer.svelte';

package/dist/utils/expression.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Typed expression trees for a block editor. The op catalogue (e.g. Oyster's
+ * `GET /expressions/ops`) says what each op returns and what its slots accept; the editor only
+ * offers ops whose result fits the slot, so users cannot build an ill-typed tree.
+ */
+export type ExpressionKind = 'boolean' | 'number' | 'date' | 'text' | 'value' | 'ids';
+export type ExpressionSlot = {
+    name: string;
+    kind: ExpressionKind;
+    many?: boolean;
+};
+export type ExpressionOp = {
+    op: string;
+    label: string;
+    group: string;
+    returns: ExpressionKind;
+    slots: ExpressionSlot[];
+    /** Plain fields on the node. A param named `key` picks a field; others are typed in. */
+    params: string[];
+};
+export type ExpressionField = {
+    key: string;
+    label?: string;
+    kind?: ExpressionKind;
+};
+export type ExpressionNode = {
+    op: string;
+    [key: string]: unknown;
+};
+/** A slot of `kind` accepts an op returning `returns` (`value` is the wildcard both ways, `ids` only fits `ids`). */
+export declare function fits(kind: ExpressionKind, returns: ExpressionKind): boolean;
+export declare function opsFor(kind: ExpressionKind, ops: ExpressionOp[]): ExpressionOp[];
+/** A fresh node for an op: empty single slots, one empty entry in list slots, blank params. */
+export declare function emptyNode(op: ExpressionOp): ExpressionNode;
+/** Text typed into a param, as the value it stands for (numbers and true/false become typed). */
+export declare function parseParam(param: string, text: string): unknown;
+export declare function paramText(value: unknown): string;
+/** True when every slot is filled and every key param names a field. */
+export declare function isComplete(node: unknown, ops: ExpressionOp[]): boolean;
+/** Plain-English reading of a tree, built from op labels and slot names (no per-op templates). */
+export declare function describe(node: unknown, ops: ExpressionOp[], fields?: ExpressionField[]): string;
+export type ExpressionPath = (string | number)[];
+/** A copy of `root` with the value at `path` replaced (`undefined` removes a list entry). */
+export declare function setAt(root: unknown, path: ExpressionPath, value: unknown): unknown;
+/** Ops grouped by their `group`, in first-seen order, for an `<optgroup>` picker. */
+export declare function groupOps(ops: ExpressionOp[]): {
+    group: string;
+    ops: ExpressionOp[];
+}[];

package/dist/utils/expression.js

@@ -0,0 +1,116 @@
+/**
+ * Typed expression trees for a block editor. The op catalogue (e.g. Oyster's
+ * `GET /expressions/ops`) says what each op returns and what its slots accept; the editor only
+ * offers ops whose result fits the slot, so users cannot build an ill-typed tree.
+ */
+/** A slot of `kind` accepts an op returning `returns` (`value` is the wildcard both ways, `ids` only fits `ids`). */
+export function fits(kind, returns) {
+    if (kind === 'ids' || returns === 'ids')
+        return kind === returns;
+    return kind === 'value' || returns === 'value' || kind === returns;
+}
+export function opsFor(kind, ops) {
+    return ops.filter((op) => fits(kind, op.returns));
+}
+/** A fresh node for an op: empty single slots, one empty entry in list slots, blank params. */
+export function emptyNode(op) {
+    const node = { op: op.op };
+    for (const slot of op.slots)
+        node[slot.name] = slot.many ? [] : null;
+    for (const param of op.params)
+        node[param] = param === 'options' ? [] : '';
+    return node;
+}
+/** Text typed into a param, as the value it stands for (numbers and true/false become typed). */
+export function parseParam(param, text) {
+    if (param === 'options')
+        return text.split(',').map((s) => s.trim()).filter(Boolean);
+    const trimmed = text.trim();
+    if (param === 'key')
+        return trimmed;
+    if (trimmed === 'true' || trimmed === 'false')
+        return trimmed === 'true';
+    if (trimmed !== '' && !Number.isNaN(Number(trimmed)))
+        return Number(trimmed);
+    return text;
+}
+export function paramText(value) {
+    if (Array.isArray(value))
+        return value.join(', ');
+    return value == null ? '' : String(value);
+}
+/** True when every slot is filled and every key param names a field. */
+export function isComplete(node, ops) {
+    if (!node || typeof node !== 'object')
+        return false;
+    const n = node;
+    const spec = ops.find((o) => o.op === n.op);
+    if (!spec)
+        return false;
+    if (spec.params.includes('key') && !n.key)
+        return false;
+    return spec.slots.every((slot) => {
+        const value = n[slot.name];
+        if (slot.many)
+            return Array.isArray(value) && value.length > 0 && value.every((v) => isComplete(v, ops));
+        return isComplete(value, ops);
+    });
+}
+/** Plain-English reading of a tree, built from op labels and slot names (no per-op templates). */
+export function describe(node, ops, fields = []) {
+    if (!node || typeof node !== 'object')
+        return '…';
+    const n = node;
+    const spec = ops.find((o) => o.op === n.op);
+    if (!spec)
+        return n.op;
+    const label = spec.label.toLowerCase();
+    if ('key' in n && spec.params.includes('key')) {
+        const field = fields.find((f) => f.key === n.key);
+        const name = field?.label ?? (n.key ? String(n.key) : '…');
+        return spec.slots.length ? `${label} ${name}` : spec.op === 'field' ? name : `${label} ${name}`;
+    }
+    if (spec.params.includes('value') && !spec.slots.length)
+        return JSON.stringify(n.value ?? '');
+    const part = (v) => describe(v, ops, fields);
+    const names = spec.slots.map((s) => s.name);
+    if (names.length === 2 && names[0] === 'left')
+        return `${part(n.left)} ${label} ${part(n.right)}`;
+    const many = spec.slots.find((s) => s.many);
+    if (many) {
+        const items = (Array.isArray(n[many.name]) ? n[many.name] : []).map(part);
+        return items.length > 1 ? `(${items.join(` ${label} `)})` : (items[0] ?? '…');
+    }
+    const pieces = spec.slots.map((s) => part(n[s.name]));
+    const options = spec.params.includes('options') ? ` ${paramText(n.options)}` : '';
+    if (!pieces.length)
+        return label;
+    if (pieces.length > 1)
+        return `${label} ${pieces.join(', ')}`;
+    // "is empty", "is one of" read after their argument; "not", "days until" before it.
+    return label.startsWith('is ') ? `${pieces[0]} ${label}${options}` : `${label} ${pieces[0]}`;
+}
+/** A copy of `root` with the value at `path` replaced (`undefined` removes a list entry). */
+export function setAt(root, path, value) {
+    if (!path.length)
+        return value;
+    const [head, ...rest] = path;
+    if (Array.isArray(root)) {
+        const next = root.slice();
+        const index = Number(head);
+        if (!rest.length && value === undefined)
+            next.splice(index, 1);
+        else
+            next[index] = setAt(root[index], rest, value);
+        return next;
+    }
+    const obj = (root && typeof root === 'object' ? root : {});
+    return { ...obj, [head]: setAt(obj[head], rest, value) };
+}
+/** Ops grouped by their `group`, in first-seen order, for an `<optgroup>` picker. */
+export function groupOps(ops) {
+    const groups = new Map();
+    for (const op of ops)
+        groups.set(op.group, [...(groups.get(op.group) ?? []), op]);
+    return [...groups].map(([group, list]) => ({ group, ops: list }));
+}

package/dist/utils/layout.d.ts

@@ -0,0 +1,15 @@
+/** Reading-order grid layout helpers: drag to reorder, drag an edge to change column span. */
+export type GridItem = {
+    id: string;
+    span: number;
+};
+export declare function moveTo<T extends {
+    id: string;
+}>(items: T[], id: string, index: number): T[];
+/** Index of the item whose centre is nearest to a point (ties keep the earlier one). */
+export declare function nearestIndex(centres: {
+    x: number;
+    y: number;
+}[], x: number, y: number): number;
+/** Column span after dragging an edge by `dx` pixels, snapped to whole columns and clamped. */
+export declare function spanAfterDrag(span: number, dx: number, columnWidth: number, min: number, max: number): number;

package/dist/utils/layout.js

@@ -0,0 +1,27 @@
+/** Reading-order grid layout helpers: drag to reorder, drag an edge to change column span. */
+export function moveTo(items, id, index) {
+    const from = items.findIndex((i) => i.id === id);
+    if (from < 0)
+        return items;
+    const next = items.slice();
+    const [item] = next.splice(from, 1);
+    next.splice(Math.max(0, Math.min(index, next.length)), 0, item);
+    return next;
+}
+/** Index of the item whose centre is nearest to a point (ties keep the earlier one). */
+export function nearestIndex(centres, x, y) {
+    let best = 0;
+    let bestDistance = Infinity;
+    centres.forEach((c, i) => {
+        const distance = (c.x - x) ** 2 + (c.y - y) ** 2;
+        if (distance < bestDistance)
+            [best, bestDistance] = [i, distance];
+    });
+    return best;
+}
+/** Column span after dragging an edge by `dx` pixels, snapped to whole columns and clamped. */
+export function spanAfterDrag(span, dx, columnWidth, min, max) {
+    if (columnWidth <= 0)
+        return span;
+    return Math.max(min, Math.min(max, span + Math.round(dx / columnWidth)));
+}

package/dist/utils/timeline.d.ts

@@ -0,0 +1,36 @@
+export type TimelineItem = {
+    id: string;
+    title: string;
+    start: Date;
+    /** Inclusive last day; defaults to `start` (a one-day bar). */
+    end?: Date;
+    /** Palette name or CSS colour for the bar. */
+    color?: string;
+    /** Rows sharing a group sit under one heading. */
+    group?: string;
+};
+export type TimelineBar = {
+    item: TimelineItem;
+    left: number;
+    width: number;
+};
+export type TimelineRow = {
+    group: string | null;
+    bars: TimelineBar[];
+};
+export type TimelineScale = {
+    start: Date;
+    days: number;
+    ticks: {
+        date: Date;
+        left: number;
+    }[];
+};
+/** The day range covering every bar (padded a day each side) and evenly spaced day ticks. */
+export declare function timelineScale(items: TimelineItem[], today?: Date): TimelineScale;
+/** One bar per item as left/width percentages of the scale; ends before starts are clamped. */
+export declare function timelineBar(item: TimelineItem, scale: TimelineScale): TimelineBar;
+/** Bars in groups (first-seen order; ungrouped first), each group sorted by start. */
+export declare function timelineRows(items: TimelineItem[], scale: TimelineScale): TimelineRow[];
+/** Where today falls on the scale (percent), or null when outside it. */
+export declare function todayOffset(scale: TimelineScale, today?: Date): number | null;

package/dist/utils/timeline.js

@@ -0,0 +1,48 @@
+import { addDays, startOfDay } from './calendar.js';
+const DAY_MS = 86_400_000;
+const PAD_DAYS = 1;
+const MAX_TICKS = 12;
+function dayIndex(from, d) {
+    return Math.round((startOfDay(d).getTime() - from.getTime()) / DAY_MS);
+}
+/** The day range covering every bar (padded a day each side) and evenly spaced day ticks. */
+export function timelineScale(items, today = new Date()) {
+    const starts = items.map((i) => startOfDay(i.start).getTime());
+    const ends = items.map((i) => startOfDay(i.end ?? i.start).getTime());
+    const first = starts.length ? Math.min(...starts) : startOfDay(today).getTime();
+    const last = ends.length ? Math.max(...ends) : first;
+    const start = addDays(new Date(first), -PAD_DAYS);
+    const days = Math.round((last - first) / DAY_MS) + 1 + 2 * PAD_DAYS;
+    const step = Math.max(1, Math.ceil(days / MAX_TICKS));
+    const ticks = [];
+    for (let i = 0; i < days; i += step)
+        ticks.push({ date: addDays(start, i), left: (i / days) * 100 });
+    return { start, days, ticks };
+}
+/** One bar per item as left/width percentages of the scale; ends before starts are clamped. */
+export function timelineBar(item, scale) {
+    const from = dayIndex(scale.start, item.start);
+    const to = Math.max(from, dayIndex(scale.start, item.end ?? item.start));
+    return { item, left: (from / scale.days) * 100, width: ((to - from + 1) / scale.days) * 100 };
+}
+/** Bars in groups (first-seen order; ungrouped first), each group sorted by start. */
+export function timelineRows(items, scale) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = item.group ?? null;
+        groups.set(key, [...(groups.get(key) ?? []), item]);
+    }
+    const keys = [...groups.keys()].sort((a, b) => (a === null ? -1 : b === null ? 1 : 0));
+    return keys.map((group) => ({
+        group,
+        bars: (groups.get(group) ?? [])
+            .slice()
+            .sort((a, b) => a.start.getTime() - b.start.getTime())
+            .map((item) => timelineBar(item, scale)),
+    }));
+}
+/** Where today falls on the scale (percent), or null when outside it. */
+export function todayOffset(scale, today = new Date()) {
+    const i = dayIndex(scale.start, today);
+    return i < 0 || i >= scale.days ? null : ((i + 0.5) / scale.days) * 100;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminoir",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Terminoir \u2014 Liquid Glass design tokens and Svelte 5 UI components.",
   "license": "Apache-2.0",
   "type": "module",