terminoir 0.4.0 → 0.5.1

package/README.md

@@ -1,24 +1,26 @@
 # Terminoir
 
-Shared **Liquid Glass** design tokens and **Svelte 5** UI components for Mauricio's apps (oyster-web, Bibliothek, mauted.com-style surfaces). CSS remains framework-agnostic; interactive primitives ship as tree-shakeable Svelte components with typed props.
+Shared **Liquid Glass** design tokens and **Svelte 5** UI components for Mauricio's apps (Oyster and future apps). CSS remains framework-agnostic; interactive primitives ship as tree-shakeable Svelte components with typed props.
+
+**Terminoir is the source of truth for UI and design.** Apps compose its components and keep only their own domain UI, with no generic controls or CSS of their own. If another app could use a component with different data, it belongs here. Oyster enforces this with a ratchet check; see [`docs/ui-boundary.md` in mauted/oyster](https://github.com/mauted/oyster/blob/main/docs/ui-boundary.md).
 
 ## Install
 
 ```bash
-# Sibling checkout (oyster-web sync:terminoir → vendor/terminoir)
-pnpm add ../terminoir
-# or
-npm install file:../terminoir
-
-# Git dependency
-pnpm add github:mauted/terminoir
+pnpm add terminoir
 ```
 
+To try unreleased changes in an app, `pnpm link /path/to/terminoir` from the app, then `pnpm unlink terminoir && pnpm install` when done.
+
+### 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.
+
 Peer dependency: **Svelte 5** (for components). Optional **React 18–19** for `terminoir/react`. CSS-only consumers can import styles without JS.
 
 **LiquidGlassJS:** Glass primitives use [`@surdeddd/liquidglass`](https://github.com/Surdeddd/liquidglassjs) (MIT — see `THIRD-PARTY-NOTICES.md`). Terminoir presets follow **macOS Tahoe / iOS 26–style Liquid Glass**: soft rounded corners (`--radius-glass`), flat frosted surfaces with thin hairline borders, minimal shadow, no gloss bevels; physics off on large panels, with automatic **css-fallback** blur when refraction is unavailable and respect for `prefers-reduced-motion` / `prefers-reduced-transparency`.
 
-**CSS entry:** `@import "terminoir"` (bare) resolves to the full CSS bundle via the package `style` field and export conditions—no `dist/` build required when vendoring raw source (oyster-web Docker flow).
+**CSS entry:** `@import "terminoir"` (bare) resolves to the full CSS bundle via the package `style` field and export conditions.
 
 ### Glass components (Svelte)
 
@@ -75,17 +77,6 @@ Demo: `pnpm demo:dev` → `/glass` (light/dark toggle in header).
 </div>
 ```
 
-```ts
-// vite.config.ts — during local sibling dev (optional)
-import path from 'node:path';
-
-export default defineConfig({
-  resolve: {
-    alias: { terminoir: path.resolve('../vendor/terminoir/src/lib/index.ts') },
-  },
-  ssr: { noExternal: ['terminoir'] },
-});
-```
 
 ### React (Bibliothek)
 
@@ -129,23 +120,42 @@ Import from **`terminoir`**:
 
 | Component | Notes |
 |-----------|--------|
-| `Button`, `IconButton` | Variants: primary, secondary, ghost, destructive, outline · sizes sm/md/lg |
-| `Input`, `Textarea`, `Select`, `Checkbox`, `Switch` | Labels, focus rings |
-| `Chip`, `Badge` | Status tones on chips |
+| `Button`, `IconButton` | Variants: primary, secondary, ghost, destructive, outline · sizes sm/md/lg · `Button href` renders a link |
+| `Input`, `Textarea`, `Select`, `Checkbox`, `Switch` | `hideLabel` (screen-reader only), `hint`, `error`, `quiet` (borderless until hover/focus, for inline property editing); `Input` `width` for toolbar fields |
+| `Chip`, `Badge` | Status tones; `Chip` `color` dot, `onclick`, removable `onremove` |
 | `Card`, `CardGrid` | Accent tint, badge, chips, progress, meta, hover lift |
 | `Panel` | Glass panel surface |
 | `Dialog` | Modal with focus trap-ish behavior + Escape |
-| `Popover`, `Tooltip`, `DropdownMenu` | Lightweight overlays |
-| `CommandPalette` | ⌘/Ctrl+K, filter, arrow keys |
+| `Popover`, `Tooltip` | Lightweight overlays |
+| `DropdownMenu`, `ContextMenu` | Items with `icon` and `tone: 'danger'`; icon-only trigger; close on outside click / Escape; `ContextMenu` opens at x/y |
+| `Drawer` | Side sheet with title, close button and optional footer |
+| `CommandPalette` | ⌘/Ctrl+K (`hotkey`), grouped rows with icons and hints; `bind:query` + `filter={false}` + `loading` for async search; `footer` snippet |
 | `Toaster` + `toast()` | Action / undo via `action: { label, onClick }` |
-| `Tabs` | Keyboard-focusable tablist |
-| `AppShell` | `header` + `sidebar` snippets; in-flow menu button; mobile drawer with ✕ close; `AppShellNavLink` active style; resize without hairline divider |
+| `Tabs`, `SegmentedControl` | Tab panels (unique ids per instance); compact radio-group toggle |
+| `AppShell` | `header` + `sidebar` snippets; mobile drawer; `fitViewport` (main scrolls, for canvases), `flush`, `headerMode="mobile"`; `toggleSidebar()` / `closeMobileDrawer()` via `bind:this` |
 | `AppShellNavLink` | `href?`, `active`, nav row with active highlight |
 | `SettingsPage`, `SettingsSection` | Settings layout — intro + stacked glass section cards |
 | `EmptyState`, `Skeleton`, `Avatar`, `Kbd` | Presentation |
 | `FontPicker` | UI + code font lists, lazy `@fontsource`, persisted per `appId` |
 | `NavIcon` | `name`, optional `color` — Font Awesome 6 (`fa-*` or plain ids like `inbox`); host app loads FA CSS |
-| `IconField` | `bind:value` icon id picker (`ICON_PICKER_OPTIONS`) |
+| `IconField` | `bind:value` icon id picker (`ICON_PICKER_OPTIONS`); `compact` opens the grid in a popover |
+
+### App kit (0.5)
+
+Building blocks so apps compose screens without CSS of their own. See the demo's **App kit** page.
+
+| Component | Notes |
+|-----------|--------|
+| `Page`, `PageHeader`, `Section` | Readable page column (`narrow`/`default`/`wide`/`full`, `fill` for canvases); title + meta + actions; titled section with actions |
+| `Stack`, `Inline`, `Spacer`, `Centered` | Vertical / horizontal layout with `--space-*` gaps (`Inline fill` splits evenly); fill space; full-viewport centred column |
+| `Text`, `Prose`, `Disclosure` | Tone/size/weight text; long-form typography; collapsible details |
+| `NavSection` | Sidebar section with title and action |
+| `DataTable` | Columns, `cell` snippet, clickable rows, `hideOnMobile`, empty state |
+| `List`, `ListItem`, `DescriptionList`, `FormRow` | Rows with leading/trailing slots; key–value pairs; label-left form rows |
+| `SearchPicker` | Debounced async combobox (`search(q)`), keyboard navigation |
+| `TitleInput`, `FileButton`, `RadioCards` | Borderless heading input; button that opens a file picker; card-style radio group |
+| `CalendarGrid` | Week (scrolling hours) and month grids; `CalendarEvent` with `muted`/`color`; helpers `calendarRange`, `shiftCalendar`, `eventsOn` |
+| `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` |
 
 ### Utilities (typed, tree-shakeable)

package/css/components.css

@@ -8,6 +8,7 @@
 }
 
 .terminoir-btn {
+  white-space: nowrap;
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -282,3 +283,64 @@
 .terminoir-accent-swatches__swatch:focus-visible {
   box-shadow: var(--focus-ring);
 }
+
+/* Visually hidden but announced by screen readers (labels of compact controls). */
+.terminoir-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.terminoir-field__hint {
+  margin: 0;
+  font-size: 0.75rem;
+  color: var(--muted-foreground);
+}
+
+.terminoir-field__hint--error {
+  color: var(--destructive);
+}
+
+.terminoir-input[aria-invalid='true'],
+.terminoir-textarea[aria-invalid='true'],
+.terminoir-select[aria-invalid='true'] {
+  border-color: var(--destructive);
+}
+
+a.terminoir-btn {
+  text-decoration: none;
+}
+
+/* Quiet fields: read like plain values until hovered or focused (inline property editors). */
+.terminoir-field--quiet .terminoir-input,
+.terminoir-field--quiet .terminoir-textarea,
+.terminoir-field--quiet .terminoir-select {
+  border-color: transparent;
+  background-color: transparent;
+  box-shadow: none;
+  padding-left: 0.5rem;
+}
+
+.terminoir-field--quiet .terminoir-select {
+  background-image: none;
+}
+
+.terminoir-field--quiet .terminoir-input:hover,
+.terminoir-field--quiet .terminoir-textarea:hover,
+.terminoir-field--quiet .terminoir-select:hover {
+  border-color: color-mix(in srgb, var(--foreground) 12%, transparent);
+  background-color: color-mix(in srgb, var(--foreground) 3%, transparent);
+}
+
+.terminoir-field--quiet .terminoir-input:focus-visible,
+.terminoir-field--quiet .terminoir-textarea:focus-visible,
+.terminoir-field--quiet .terminoir-select:focus-visible {
+  border-color: var(--ring);
+  background-color: color-mix(in srgb, var(--card) 38%, var(--background));
+}

package/css/shell.css

@@ -151,6 +151,37 @@
   display: none;
 }
 
+.terminoir-shell--fit {
+  height: 100dvh;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.terminoir-shell--fit .terminoir-shell__stage {
+  min-height: 0;
+  height: 100dvh;
+}
+
+.terminoir-shell--fit .terminoir-shell__main {
+  overflow-y: auto;
+  min-height: 0;
+}
+
+.terminoir-shell--fit .terminoir-shell__sidebar-inner {
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.terminoir-shell--flush .terminoir-shell__main {
+  padding: 0;
+}
+
+@media (min-width: 769px) {
+  .terminoir-shell--header-mobile .terminoir-shell__main-header {
+    display: none;
+  }
+}
+
 @media (max-width: 768px) {
   .terminoir-shell {
     grid-template-columns: minmax(0, 1fr);
@@ -210,7 +241,7 @@
     padding-right: var(--space-3);
   }
 
-  .terminoir-shell__main {
+  .terminoir-shell:not(.terminoir-shell--flush) .terminoir-shell__main {
     padding-left: var(--space-3);
     padding-right: var(--space-3);
   }

package/dist/components/AccentSwatches.svelte

@@ -14,7 +14,7 @@
     class?: string;
   } = $props();
 
-  const groupId = `terminoir-accent-swatches-${Math.random().toString(36).slice(2, 8)}`;
+  const groupId = $props.id();
 </script>
 
 <fieldset class={cn('terminoir-accent-swatches glass-palette', className)} aria-labelledby={`${groupId}-label`}>

package/dist/components/AppShell.svelte

@@ -9,6 +9,9 @@
     defaultWidth = 260,
     minWidth = 180,
     maxWidth = 420,
+    fitViewport = false,
+    flush = false,
+    headerMode = 'always',
     class: className = '',
     header,
     sidebar,
@@ -18,6 +21,12 @@
     defaultWidth?: number;
     minWidth?: number;
     maxWidth?: number;
+    /** Exactly one viewport tall; the main area scrolls (needed for full-height canvases). */
+    fitViewport?: boolean;
+    /** No padding around the main area (pages bring their own, e.g. `Page`). */
+    flush?: boolean;
+    /** `mobile` hides the header bar (and its menu button) on wide screens. */
+    headerMode?: 'always' | 'mobile';
     class?: string;
     header?: Snippet;
     sidebar?: Snippet;
@@ -32,6 +41,20 @@
   let mobileOpen = $state(false);
   let shellEl: HTMLElement | undefined = $state();
   let dragging = $state(false);
+  let isMobile = $state(false);
+  const expanded = $derived(isMobile ? mobileOpen : desktopOpen);
+  const MOBILE_QUERY = '(max-width: 768px)';
+
+  $effect(() => {
+    const mq = window.matchMedia(MOBILE_QUERY);
+    const sync = () => {
+      isMobile = mq.matches;
+      if (!mq.matches) mobileOpen = false;
+    };
+    sync();
+    mq.addEventListener('change', sync);
+    return () => mq.removeEventListener('change', sync);
+  });
 
   $effect.pre(() => {
     if (typeof window === 'undefined') return;
@@ -48,8 +71,9 @@
     shellEl?.style.setProperty('--terminoir-sidebar-width', `${width}px`);
   }
 
-  function toggleSidebar() {
-    if (typeof window !== 'undefined' && window.matchMedia('(max-width: 768px)').matches) {
+  /** Open/close the sidebar (drawer on phones). Call through `bind:this` for keyboard shortcuts. */
+  export function toggleSidebar() {
+    if (isMobile) {
       mobileOpen = !mobileOpen;
       return;
     }
@@ -57,7 +81,8 @@
     writeStorage(appId, openKey, String(desktopOpen));
   }
 
-  function closeMobileDrawer() {
+  /** Close the phone drawer, e.g. after a navigation link is chosen. */
+  export function closeMobileDrawer() {
     mobileOpen = false;
   }
 
@@ -87,6 +112,9 @@
   class={cn(
     'terminoir-shell',
     !desktopOpen && 'terminoir-shell--collapsed',
+    fitViewport && 'terminoir-shell--fit',
+    flush && 'terminoir-shell--flush',
+    headerMode === 'mobile' && 'terminoir-shell--header-mobile',
     mobileOpen && 'terminoir-shell--mobile-open',
     className,
   )}
@@ -128,8 +156,8 @@
       <button
         type="button"
         class="terminoir-shell__icon-btn terminoir-shell__menu-btn terminoir-focusable glass-chrome"
-        aria-label={desktopOpen || mobileOpen ? 'Hide sidebar' : 'Show sidebar'}
-        aria-expanded={desktopOpen || mobileOpen}
+        aria-label={isMobile ? (expanded ? 'Close menu' : 'Open menu') : expanded ? 'Hide sidebar' : 'Show sidebar'}
+        aria-expanded={expanded}
         onclick={toggleSidebar}
       >
         <NavIcon name="bars" />

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

@@ -4,11 +4,20 @@ type $$ComponentProps = {
     defaultWidth?: number;
     minWidth?: number;
     maxWidth?: number;
+    /** Exactly one viewport tall; the main area scrolls (needed for full-height canvases). */
+    fitViewport?: boolean;
+    /** No padding around the main area (pages bring their own, e.g. `Page`). */
+    flush?: boolean;
+    /** `mobile` hides the header bar (and its menu button) on wide screens. */
+    headerMode?: 'always' | 'mobile';
     class?: string;
     header?: Snippet;
     sidebar?: Snippet;
     children?: Snippet;
 };
-declare const AppShell: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const AppShell: import("svelte").Component<$$ComponentProps, {
+    toggleSidebar: () => void;
+    closeMobileDrawer: () => void;
+}, "">;
 type AppShell = ReturnType<typeof AppShell>;
 export default AppShell;

package/dist/components/AppShellNavLink.svelte

@@ -17,10 +17,8 @@
     children?: Snippet;
   } & Record<string, unknown> = $props();
 
-  const classes = cn(
-    'terminoir-shell__nav-link terminoir-focusable',
-    active && 'terminoir-shell__nav-link--active',
-    className,
+  const classes = $derived(
+    cn('terminoir-shell__nav-link terminoir-focusable', active && 'terminoir-shell__nav-link--active', className),
   );
 </script>
 

package/dist/components/Button.svelte

@@ -6,6 +6,7 @@
   type Size = 'sm' | 'md' | 'lg';
 
   let {
+    href,
     variant = 'primary',
     size = 'md',
     type = 'button',
@@ -15,6 +16,8 @@
     children,
     ...rest
   }: {
+    /** Render as a link styled like a button (navigation, OAuth flows). */
+    href?: string;
     variant?: Variant;
     size?: Size;
     type?: 'button' | 'submit' | 'reset';
@@ -25,17 +28,32 @@
   } & Record<string, unknown> = $props();
 </script>
 
-<button
-  {type}
-  {disabled}
-  class={cn(
-    'terminoir-btn terminoir-focusable glass-interactive',
-    `terminoir-btn--${variant}`,
-    `terminoir-btn--${size}`,
-    className,
-  )}
-  {onclick}
-  {...rest}
->
-  {@render children?.()}
-</button>
+{#if href}
+  <a
+    {href}
+    class={cn(
+      'terminoir-btn terminoir-focusable glass-interactive',
+      `terminoir-btn--${variant}`,
+      `terminoir-btn--${size}`,
+      className,
+    )}
+    {...rest}
+  >
+    {@render children?.()}
+  </a>
+{:else}
+  <button
+    {type}
+    {disabled}
+    class={cn(
+      'terminoir-btn terminoir-focusable glass-interactive',
+      `terminoir-btn--${variant}`,
+      `terminoir-btn--${size}`,
+      className,
+    )}
+    {onclick}
+    {...rest}
+  >
+    {@render children?.()}
+  </button>
+{/if}

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

@@ -2,6 +2,8 @@ import type { Snippet } from 'svelte';
 type Variant = 'primary' | 'secondary' | 'ghost' | 'destructive' | 'outline';
 type Size = 'sm' | 'md' | 'lg';
 type $$ComponentProps = {
+    /** Render as a link styled like a button (navigation, OAuth flows). */
+    href?: string;
     variant?: Variant;
     size?: Size;
     type?: 'button' | 'submit' | 'reset';