@corbet-labs/ccht 0.2.0 → 0.2.3

package/src/components/Dock.svelte

@@ -0,0 +1,172 @@
+<!-- Product-neutral edge rail. The application owns all effects (dock state,
+  persistence, focus targets beyond this panel); this component only renders
+  the tab and panel chrome and forwards user intent through app-supplied
+  open/close callbacks. It never fetches, spawns, or stores anything. -->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  let {
+    side = 'left',
+    title,
+    open,
+    onClose,
+    onOpen,
+    tabLabel,
+    tabSummary = '',
+    closeLabel,
+    panelId,
+    children
+  }: {
+    side: 'left' | 'right';
+    title: string;
+    open: boolean;
+    onClose: () => void;
+    onOpen: () => void;
+    tabLabel: string;
+    tabSummary?: string;
+    closeLabel?: string;
+    panelId: string;
+    children: Snippet;
+  } = $props();
+
+  let panelEl: HTMLElement | undefined = $state(undefined);
+  let tabEl: HTMLButtonElement | undefined = $state(undefined);
+  let wasOpen = $state(false);
+  let prevFocus: HTMLElement | null = $state(null);
+  const dismissLabel = $derived(closeLabel ?? `Close ${title}`);
+
+  function handleTabClick(event: MouseEvent) {
+    prevFocus = event.currentTarget as HTMLElement;
+    onOpen();
+  }
+
+  $effect(() => {
+    if (open && !wasOpen) {
+      wasOpen = true;
+      prevFocus ??= document.activeElement as HTMLElement | null;
+      requestAnimationFrame(() => {
+        // First visible, enabled control wins; hidden or disabled nodes
+        // never take focus. Fixed panels have no offsetParent, so filter
+        // on client rects instead.
+        const target = [...(panelEl?.querySelectorAll<HTMLElement>(
+          'button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), a[href], [tabindex]:not([tabindex="-1"])'
+        ) ?? [])].find((node) => node.getClientRects().length > 0) ?? panelEl;
+        target?.focus();
+      });
+    } else if (!open && wasOpen) {
+      wasOpen = false;
+      const restore = prevFocus?.isConnected ? prevFocus : null;
+      prevFocus = null;
+      requestAnimationFrame(() => {
+        (restore ?? tabEl)?.focus?.();
+      });
+    }
+  });
+
+  $effect(() => {
+    if (panelEl) (panelEl as HTMLElement & { inert: boolean }).inert = !open;
+  });
+
+  function onKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape' && open) onClose();
+  }
+</script>
+
+<svelte:window onkeydown={onKeydown} />
+
+{#if !open}
+  <button
+    bind:this={tabEl}
+    type="button"
+    class="ccht-dock-tab"
+    data-side={side}
+    aria-expanded="false"
+    aria-controls={panelId}
+    aria-label={tabSummary ? `Open ${title}: ${tabSummary}` : `Open ${title}`}
+    onclick={handleTabClick}
+  ><span class="ccht-dock-tab-text">{tabLabel} · {tabSummary || title}</span></button>
+{/if}
+
+<div
+  bind:this={panelEl}
+  id={panelId}
+  class="ccht-dock-panel"
+  data-side={side}
+  data-open={open ? 'true' : 'false'}
+  role="dialog"
+  aria-label={title}
+  aria-hidden={!open}
+  tabindex="-1"
+>
+  <div class="ccht-dock-head">
+    <div class="ccht-dock-title"><h2>{title}</h2>{#if tabSummary}<p>{tabSummary}</p>{/if}</div>
+    <button type="button" class="ccht-dock-close" aria-label={dismissLabel} onclick={onClose}>Close</button>
+  </div>
+  <div class="ccht-dock-body">{@render children()}</div>
+</div>
+
+<style>
+  .ccht-dock-tab {
+    position: fixed; top: 50%; z-index: 80; transform: translateY(-50%);
+    max-height: min(60vh, 30rem); max-width: 2.4rem; padding: 0.7rem 0.4rem;
+    display: flex; align-items: center; justify-content: center;
+    border: 1px solid var(--ccht-border, #30405c);
+    color: var(--ccht-fg, #c2cede);
+    background: var(--ccht-tab-bg, #111c2df2);
+    font: 800 0.68rem ui-monospace, monospace; cursor: pointer;
+    writing-mode: vertical-rl; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  }
+  .ccht-dock-tab[data-side='left'] { left: 0; border-left: 0; border-radius: 0 0.5rem 0.5rem 0; }
+  .ccht-dock-tab[data-side='right'] { right: 0; border-right: 0; border-radius: 0.5rem 0 0 0.5rem; }
+  .ccht-dock-tab:hover {
+    border-color: var(--ccht-accent, #53708f);
+    color: var(--ccht-fg-bright, #e2eaf5);
+    background: var(--ccht-tab-bg-hover, #17243af2);
+  }
+  .ccht-dock-tab-text { overflow: hidden; text-overflow: ellipsis; }
+  .ccht-dock-panel {
+    position: fixed; top: 0; bottom: 0; z-index: 70;
+    width: min(30rem, 100vw); display: flex; flex-direction: column;
+    background: var(--ccht-panel-bg, #0d1625);
+    color: var(--ccht-fg, #d8e2f0); visibility: hidden;
+    transition: transform 0.2s ease, visibility 0s linear 0.2s;
+  }
+  .ccht-dock-panel[data-side='left'] {
+    left: 0; border-right: 1px solid var(--ccht-border, #223049); transform: translateX(-102%);
+  }
+  .ccht-dock-panel[data-side='right'] {
+    right: 0; border-left: 1px solid var(--ccht-border, #223049); transform: translateX(102%);
+  }
+  .ccht-dock-panel[data-open='true'] { transform: none; visibility: visible; transition: transform 0.2s ease; }
+  .ccht-dock-panel[data-open='false'] { visibility: hidden; }
+  .ccht-dock-head {
+    display: flex; align-items: center; justify-content: space-between; gap: 0.8rem;
+    padding: 1rem 1.1rem; border-bottom: 1px solid var(--ccht-border, #223049);
+  }
+  .ccht-dock-title { min-width: 0; }
+  .ccht-dock-title h2 { margin: 0; font-size: 1.02rem; overflow-wrap: anywhere; }
+  .ccht-dock-title p {
+    margin: 0.3rem 0 0; overflow-wrap: anywhere;
+    color: var(--ccht-muted, #8fa0b7); font: 750 0.68rem ui-monospace, monospace;
+  }
+  .ccht-dock-close {
+    flex: 0 0 auto; min-height: 2.5rem; padding: 0.55rem 0.85rem;
+    border: 1px solid var(--ccht-border, #30405c); border-radius: 0.5rem;
+    color: var(--ccht-fg, #c2cede);
+    background: var(--ccht-tab-bg, #111c2d);
+    font-size: 0.72rem; font-weight: 850; cursor: pointer;
+  }
+  .ccht-dock-close:hover {
+    border-color: var(--ccht-accent, #53708f);
+    background: var(--ccht-tab-bg-hover, #17243a);
+  }
+  .ccht-dock-body {
+    flex: 1; min-height: 0; overflow: auto; padding: 1rem 1.1rem;
+    display: grid; gap: 0.85rem; align-content: start;
+  }
+  @media (max-width: 560px) {
+    .ccht-dock-panel { width: 100vw; }
+    .ccht-dock-head, .ccht-dock-body { padding-left: 0.85rem; padding-right: 0.85rem; }
+  }
+  @media (prefers-reduced-motion: reduce) { .ccht-dock-panel { transition: none; } }
+</style>

package/src/dock.ts

@@ -0,0 +1,244 @@
+/** Framework-free dock state for web consumers, mirroring the dock vocabulary.
+ *
+ * Docks are named regions of application chrome (for example a chat rail or
+ * a configuration panel). `DockKind` classifies a dock, `Placement` places
+ * it, and the manager tracks which docks exist, which are open, and where
+ * each one sits. The conversation model stays in Rust/Wasm; these types only
+ * describe *where* a surface lives and whether it is visible.
+ *
+ * This module is plain TypeScript: no DOM access, no network I/O, no spawned
+ * processes, and no storage. Persistence travels through `serialize` /
+ * `restore` as explicit JSON handled by the application; focus is handed off
+ * through an opaque token the application moves to its own focus target.
+ * Product copy belongs to the embedding application.
+ */
+
+/** What a dock is for. `chat` hosts a conversation surface, `config` hosts
+ * settings, and `custom` covers every application-defined use. */
+export type DockKind = 'chat' | 'config' | 'custom';
+
+/** Where a dock sits. Edge values pin the dock to a window edge; `inline`
+ * renders it in the normal application flow instead. */
+export type Placement = 'left' | 'right' | 'bottom' | 'inline';
+
+const DOCK_ID_PATTERN = /^[a-z0-9-_]+$/;
+const DOCK_ID_MAX_LENGTH = 64;
+
+/** Validate a dock id. Returns an error message, or null when the id is valid.
+ *
+ * Rules: a non-empty string of at most 64 ASCII `[a-z0-9-_]` characters.
+ * Never throws; validate before registering or restoring a dock.
+ */
+export function validateDockId(id: unknown): string | null {
+  if (typeof id !== 'string' || id.length === 0) {
+    return 'invalid dock id: must be a non-empty string';
+  }
+  if (id.length > DOCK_ID_MAX_LENGTH) {
+    return 'invalid dock id: must be at most 64 characters';
+  }
+  if (!DOCK_ID_PATTERN.test(id)) {
+    return 'invalid dock id: must match [a-z0-9-_]';
+  }
+  return null;
+}
+
+/** One persisted dock entry. `open` is the only mutable runtime state; the
+ * focus token is deliberately absent and never survives serialization. */
+export interface DockEntry {
+  id: string;
+  kind: DockKind;
+  placement: Placement;
+  open: boolean;
+}
+
+/** Named dock registry with open state, placement, and focus handoff.
+ *
+ * Methods that name a dock throw `Error('UnknownDock: <id>')` for ids that
+ * were never registered. `register` throws `Error('DuplicateDock: <id>')`
+ * for an id that already exists, and rethrows the `validateDockId` message
+ * for a malformed id. Invalid kinds, placements, focus tokens, and snapshots
+ * throw `Error` with a fixed `invalid ...` message.
+ */
+export interface DockManager {
+  /** Register a closed dock. Throws on a malformed id, an invalid kind or
+   * placement, or a duplicate id. */
+  register(id: string, kind: DockKind, placement: Placement): void;
+  /** Mark a dock open. Throws `UnknownDock` for an unregistered id. */
+  open(id: string): void;
+  /** Mark a dock open and stage a focus token for the application to consume
+   * with `takeFocusToken`. The token must be a non-empty string. */
+  openWithFocus(id: string, token: string): void;
+  /** Mark a dock closed. Throws `UnknownDock` for an unregistered id. */
+  close(id: string): void;
+  /** Flip a dock's open state and return the new state. */
+  toggle(id: string): boolean;
+  /** Whether a dock is currently open. */
+  isOpen(id: string): boolean;
+  /** A dock's current placement. */
+  placement(id: string): Placement;
+  /** Move a dock to another placement. */
+  setPlacement(id: string, placement: Placement): void;
+  /** Ids of open docks, in registration order. */
+  openDocks(): string[];
+  /** Take the staged focus token once, clearing it; null when none is staged. */
+  takeFocusToken(): string | null;
+  /** Mark every dock closed. Staged focus tokens are left untouched. */
+  closeAll(): void;
+  /** Persist `[{id, kind, placement, open}]` as JSON, in registration order.
+   * The focus token is never persisted. */
+  serialize(): string;
+  /** Replace all state from `serialize` output. Validates every entry first,
+   * so a malformed snapshot leaves the current state untouched, and clears
+   * any staged focus token. */
+  restore(json: string): void;
+}
+
+/** Create an empty dock manager. Managers are independent; applications that
+ * need shared state pass one manager around instead of creating several. */
+export function createDockManager(): DockManager {
+  const docks = new Map<string, { kind: DockKind; placement: Placement; open: boolean }>();
+  let focusToken: string | null = null;
+
+  function entry(id: string): { kind: DockKind; placement: Placement; open: boolean } {
+    const found = docks.get(id);
+    if (found === undefined) {
+      throw new Error(`UnknownDock: ${id}`);
+    }
+    return found;
+  }
+
+  function checkKind(kind: unknown): asserts kind is DockKind {
+    if (kind !== 'chat' && kind !== 'config' && kind !== 'custom') {
+      throw new Error('invalid dock kind');
+    }
+  }
+
+  function checkPlacement(value: unknown): asserts value is Placement {
+    if (value !== 'left' && value !== 'right' && value !== 'bottom' && value !== 'inline') {
+      throw new Error('invalid dock placement');
+    }
+  }
+
+  function checkToken(token: unknown): asserts token is string {
+    if (typeof token !== 'string' || token.length === 0) {
+      throw new Error('invalid focus token');
+    }
+  }
+
+  return {
+    register(id, kind, placement) {
+      const invalid = validateDockId(id);
+      if (invalid !== null) {
+        throw new Error(invalid);
+      }
+      checkKind(kind);
+      checkPlacement(placement);
+      if (docks.has(id)) {
+        throw new Error(`DuplicateDock: ${id}`);
+      }
+      docks.set(id, { kind, placement, open: false });
+    },
+    open(id) {
+      entry(id).open = true;
+    },
+    openWithFocus(id, token) {
+      checkToken(token);
+      entry(id).open = true;
+      focusToken = token;
+    },
+    close(id) {
+      entry(id).open = false;
+    },
+    toggle(id) {
+      const target = entry(id);
+      target.open = !target.open;
+      return target.open;
+    },
+    isOpen(id) {
+      return entry(id).open;
+    },
+    placement(id) {
+      return entry(id).placement;
+    },
+    setPlacement(id, placement) {
+      checkPlacement(placement);
+      entry(id).placement = placement;
+    },
+    openDocks() {
+      const ids: string[] = [];
+      for (const [id, state] of docks) {
+        if (state.open) {
+          ids.push(id);
+        }
+      }
+      return ids;
+    },
+    takeFocusToken() {
+      const token = focusToken;
+      focusToken = null;
+      return token;
+    },
+    closeAll() {
+      for (const state of docks.values()) {
+        state.open = false;
+      }
+    },
+    serialize() {
+      const snapshot: DockEntry[] = [];
+      for (const [id, state] of docks) {
+        snapshot.push({ id, kind: state.kind, placement: state.placement, open: state.open });
+      }
+      return JSON.stringify(snapshot);
+    },
+    restore(json) {
+      let decoded: unknown;
+      try {
+        decoded = JSON.parse(json);
+      } catch {
+        throw new Error('invalid dock snapshot: not JSON');
+      }
+      if (!Array.isArray(decoded)) {
+        throw new Error('invalid dock snapshot: must be an array');
+      }
+      const next = new Map<string, { kind: DockKind; placement: Placement; open: boolean }>();
+      for (const value of decoded) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          throw new Error('invalid dock snapshot: entry must be an object');
+        }
+        const record = value as Record<string, unknown>;
+        const invalid = validateDockId(record.id);
+        if (invalid !== null) {
+          throw new Error(`invalid dock snapshot: ${invalid}`);
+        }
+        const id = record.id as string;
+        if (record.kind !== 'chat' && record.kind !== 'config' && record.kind !== 'custom') {
+          throw new Error('invalid dock snapshot: invalid dock kind');
+        }
+        if (
+          record.placement !== 'left' &&
+          record.placement !== 'right' &&
+          record.placement !== 'bottom' &&
+          record.placement !== 'inline'
+        ) {
+          throw new Error('invalid dock snapshot: invalid dock placement');
+        }
+        if (typeof record.open !== 'boolean') {
+          throw new Error('invalid dock snapshot: open must be a boolean');
+        }
+        if (next.has(id)) {
+          throw new Error('invalid dock snapshot: duplicate dock id');
+        }
+        next.set(id, {
+          kind: record.kind,
+          placement: record.placement,
+          open: record.open,
+        });
+      }
+      docks.clear();
+      for (const [id, state] of next) {
+        docks.set(id, state);
+      }
+      focusToken = null;
+    },
+  };
+}