@proteos/ui 0.31.0

package/src/lib/commands/use-escape-key.test.tsx

@@ -0,0 +1,97 @@
+import { render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { _resetEscapeStack, useEscapeKey } from './use-escape-key'
+
+function Bind({
+  handler,
+  enabled,
+}: {
+  handler: (e: KeyboardEvent) => void
+  enabled?: boolean
+}) {
+  useEscapeKey(handler, enabled !== undefined ? { enabled } : undefined)
+  return null
+}
+
+function dispatchEscape(target?: EventTarget) {
+  const ev = new KeyboardEvent('keydown', {
+    bubbles: true,
+    cancelable: true,
+    key: 'Escape',
+  })
+  ;(target ?? window).dispatchEvent(ev)
+}
+
+describe('useEscapeKey', () => {
+  beforeEach(() => {
+    _resetEscapeStack()
+  })
+  afterEach(() => {
+    _resetEscapeStack()
+  })
+
+  it('fires the handler on Escape', () => {
+    const fn = vi.fn()
+    render(<Bind handler={fn} />)
+    dispatchEscape()
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips editable targets', () => {
+    const fn = vi.fn()
+    render(<Bind handler={fn} />)
+    const input = document.createElement('input')
+    document.body.appendChild(input)
+    dispatchEscape(input)
+    document.body.removeChild(input)
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it('respects enabled=false', () => {
+    const fn = vi.fn()
+    render(<Bind handler={fn} enabled={false} />)
+    dispatchEscape()
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it('newest mount wins; only one handler fires per event', () => {
+    const outer = vi.fn()
+    const inner = vi.fn()
+    render(
+      <>
+        <Bind handler={outer} />
+        <Bind handler={inner} />
+      </>,
+    )
+    dispatchEscape()
+    expect(inner).toHaveBeenCalledTimes(1)
+    expect(outer).not.toHaveBeenCalled()
+  })
+
+  it('cleans up on unmount; the previous handler becomes top', () => {
+    const outer = vi.fn()
+    const inner = vi.fn()
+    function Outer() {
+      useEscapeKey(outer)
+      return null
+    }
+    function Inner() {
+      useEscapeKey(inner)
+      return null
+    }
+    function Wrap({ showInner }: { showInner: boolean }) {
+      return (
+        <>
+          <Outer />
+          {showInner ? <Inner /> : null}
+        </>
+      )
+    }
+    const { rerender } = render(<Wrap showInner={true} />)
+    rerender(<Wrap showInner={false} />)
+    dispatchEscape()
+    expect(outer).toHaveBeenCalledTimes(1)
+    expect(inner).not.toHaveBeenCalled()
+  })
+})

package/src/lib/commands/use-escape-key.ts

@@ -0,0 +1,62 @@
+/* Bare-Escape handler. Doesn't go through the `mod+<key>` registry because
+   Escape has no modifier. Same editable-target guard. Multiple subscribers
+   stack — only the newest fires per event, matching the "newest wins"
+   semantics of the command registry so nested overlays (peek over a
+   record stack, say) close one layer at a time. */
+
+import { useEffect, useRef } from 'react'
+
+import { isEditableTarget } from './match-event'
+
+export type UseEscapeKeyOptions = {
+  /** Defaults to `true`. Set to `false` to temporarily disable without unmounting. */
+  enabled?: boolean
+}
+
+type Entry = { handler: (event: KeyboardEvent) => void }
+
+const stack: Entry[] = []
+let listenerInstalled = false
+
+function onWindowKeyDown(event: KeyboardEvent): void {
+  if (event.key !== 'Escape') return
+  if (isEditableTarget(event.target)) return
+  const top = stack[stack.length - 1]
+  if (!top) return
+  top.handler(event)
+}
+
+function ensureListener(): void {
+  if (listenerInstalled) return
+  if (typeof window === 'undefined') return
+  window.addEventListener('keydown', onWindowKeyDown, { capture: true })
+  listenerInstalled = true
+}
+
+export function useEscapeKey(
+  handler: (event: KeyboardEvent) => void,
+  options?: UseEscapeKeyOptions,
+): void {
+  const enabled = options?.enabled ?? true
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  })
+  useEffect(() => {
+    if (!enabled) return undefined
+    ensureListener()
+    const entry: Entry = {
+      handler: (event) => handlerRef.current(event),
+    }
+    stack.push(entry)
+    return () => {
+      const idx = stack.lastIndexOf(entry)
+      if (idx >= 0) stack.splice(idx, 1)
+    }
+  }, [enabled])
+}
+
+// Test-only.
+export function _resetEscapeStack(): void {
+  stack.length = 0
+}

package/src/styles.css

@@ -0,0 +1,321 @@
+/* Google Fonts @import MUST come before `@import "tailwindcss"` — Tailwind's
+   directive expands inline into many rules, and any @import that follows them
+   violates CSS's "all @imports come first" rule. */
+@import url("https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600&family=Inter:wght@300;400;450;500;600&display=swap");
+
+@import "tailwindcss";
+
+/* Make Tailwind's content scanner pick up classes used inside the lib's own
+   components when this stylesheet is consumed from another package (e.g.
+   `clients/web` imports it via `@import "@proteos/ui/styles.css"`). Without
+   this, utilities that only appear in lib source — `border-transparent`, the
+   indigo color-mix variants, `rounded-pill`, etc. — are tree-shaken from the
+   consumer's build and components render unstyled. Path is resolved relative
+   to *this* file. */
+@source "./components/**/*.{ts,tsx}";
+
+/* ==========================================================
+   PROTEOS · INDIGO — design tokens
+   Mirrors Proteos Design System v0.1 (spec: revision 2026.04.24).
+   Exposed to Tailwind v4 utilities via @theme, and preserved as
+   raw CSS custom properties so components can reference them.
+   ========================================================== */
+
+@theme {
+  /* Base — the page/chrome background the app shell paints. The majority
+     surface: pages, panels, headers, toolbars, tables, ghost buttons.
+     Split from --color-surface so themes can lift raised blocks off it;
+     in paper the two are identical. */
+  --color-bg: #f2f0ea;
+
+  /* Surfaces — raised blocks that sit ON the base: cards, popovers, modals,
+     inputs. surface-2/-3 are the recessed tint steps (hovers, read-only
+     boxes, chips, table-header fill), stepped darker in paper. */
+  --color-surface: #f2f0ea;
+  --color-surface-2: #e7e4db;
+  --color-surface-3: #dcd8cc;
+
+  /* Ink — indigo-tinted slate */
+  --color-ink: #1a1d2b;
+  --color-ink-2: #353a4b;
+  --color-ink-3: #686c7a;
+  --color-ink-4: #9a9ca6;
+
+  /* Hairlines. rule-strong marks interactive-control borders (inputs,
+     ghost buttons, segmented tracks) — equal to rule in paper, darker in
+     the light/dark themes so touchable chrome pops. */
+  --color-rule: #cfcbbd;
+  --color-rule-2: #dbd7c9;
+  --color-rule-strong: #cfcbbd;
+
+  /* Accent — deep indigo */
+  --color-accent: #2f3a66;
+  --color-accent-2: #4a5580;
+  --color-accent-ink: #1a2042;
+
+  /* Semantic — muted, paper-compatible */
+  --color-success: #3d5c3a;
+  --color-warning: #8a6a1f;
+  --color-danger: #7a2a2a;
+  --color-info: #2f3a66;
+
+  /* Indigo ramp — for edge cases & future components */
+  --color-indigo-50: #e8e9f0;
+  --color-indigo-100: #c9ccdc;
+  --color-indigo-200: #9aa0bf;
+  --color-indigo-300: #6b73a0;
+  --color-indigo-400: #4a5580;
+  --color-indigo-500: #2f3a66;
+  --color-indigo-600: #1a2042;
+  --color-indigo-700: #121630;
+  --color-indigo-800: #0a0c1e;
+
+  /* App tile palette — coloured tiles in AppSwitcher and the canvas
+     element-type badge. `tile-fg` is the ink-on-tile colour, slightly
+     warmer than --color-surface so it reads as "printed on coloured paper". */
+  --color-tile-indigo: #2f3a66;
+  --color-tile-moss: #5b7052;
+  --color-tile-terra: #8a5a3f;
+  --color-tile-slate: #1a1d2b;
+  --color-tile-fg: #f0efe8;
+
+  /* Type */
+  --font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+  --font-sans: "Inter", ui-sans-serif, system-ui, -apple-system, sans-serif;
+
+  /* Radii */
+  --radius-sm: 6px;
+  --radius-md: 10px;
+  --radius-lg: 14px;
+  --radius-xl: 18px;
+  --radius-pill: 999px;
+
+  /* Shadows — warm, low-key */
+  --shadow-inset: 0 1px 0 rgba(255, 255, 255, 0.6) inset,
+    0 1px 2px rgba(26, 29, 43, 0.05);
+  --shadow-rest: 0 1px 0 rgba(255, 255, 255, 0.6) inset,
+    0 4px 10px -4px rgba(26, 29, 43, 0.1), 0 1px 2px rgba(26, 29, 43, 0.05);
+  --shadow-raised: 0 1px 0 rgba(255, 255, 255, 0.6) inset,
+    0 14px 30px -14px rgba(26, 29, 43, 0.18),
+    0 2px 4px rgba(26, 29, 43, 0.05);
+  --shadow-float: 0 1px 0 rgba(255, 255, 255, 0.6) inset,
+    0 30px 60px -30px rgba(26, 29, 43, 0.28),
+    0 2px 6px rgba(26, 29, 43, 0.06);
+  --shadow-focus: 0 0 0 4px color-mix(in oklab, var(--color-accent) 22%, transparent);
+  --shadow-focus-danger: 0 0 0 4px
+    color-mix(in oklab, var(--color-danger) 18%, transparent);
+
+  /* Motion — durations & easing. 150ms colour/border, 200ms transform,
+     280ms layout. Default ease for layout transitions is the "out-soft"
+     curve; everything else uses CSS's `ease`. Nothing bounces. */
+  --ease-out-soft: cubic-bezier(0.2, 0.8, 0.2, 1);
+  --duration-fast: 150ms;
+  --duration-base: 200ms;
+  --duration-slow: 280ms;
+
+  /* Indeterminate progress — a 35%-wide segment that slides off the right
+     edge and re-enters from the left on a continuous loop. Paired with the
+     ProgressBar component's `w-[35%]` fill. */
+  --animate-indeterminate-progress: indeterminate-progress 1.5s ease-in-out infinite;
+
+  /* Status pop — one-shot scale+fade entrance for the large success/error
+     status icons. Soft ease, no overshoot (nothing bounces). */
+  --animate-status-pop: status-pop var(--duration-slow) var(--ease-out-soft) both;
+}
+
+@keyframes indeterminate-progress {
+  0% {
+    left: -35%;
+  }
+  60% {
+    left: 100%;
+  }
+  100% {
+    left: 100%;
+  }
+}
+
+@keyframes status-pop {
+  from {
+    opacity: 0;
+    transform: scale(0.85);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+/* Raw variables (non-color) for direct component consumption.
+   Tailwind v4 mirrors @theme into :root for colors/radii/shadows, but we
+   also expose spacing tokens here for components that need raw var() access. */
+:root {
+  --s-1: 4px;
+  --s-2: 8px;
+  --s-3: 12px;
+  --s-4: 16px;
+  --s-5: 20px;
+  --s-6: 24px;
+  --s-7: 32px;
+  --s-8: 40px;
+  --s-9: 56px;
+  --s-10: 72px;
+  --s-11: 96px;
+  --s-12: 128px;
+
+  /* Table zebra-stripe + row-hover strength — the % of ink mixed into the
+     page bg per row (see Table). Per-theme so each mode tunes independently:
+     near-white bases show a given delta more, so light dials down. Paper 3%
+     matches the pre-theme stripe tone. */
+  --row-stripe: 3%;
+  --row-hover: 6%;
+
+  color-scheme: light;
+}
+
+/* ==========================================================
+   Theme modes — paper (default, tokens above) · light · dark.
+   Switched via data-theme on <html> (see clients/web lib/theme.ts).
+   Plain unlayered blocks: they beat Tailwind's @layer theme :root
+   declarations, and [data-theme] beats :root on specificity. Tailwind
+   utilities resolve var(--color-*) / var(--shadow-*) at use-time, so
+   redefining the custom properties re-skins every component.
+   ========================================================== */
+
+/* Light — white surfaces lifted off a cool-gray base. */
+:root[data-theme='light'] {
+  --color-bg: #fbfbfc;
+  --color-surface: #ffffff;
+  --color-surface-2: #f0f0f2;
+  --color-surface-3: #e5e5e9;
+
+  --color-ink: #1a1d2b;
+  --color-ink-2: #383d4e;
+  --color-ink-3: #63677a;
+  --color-ink-4: #7e818f;
+
+  --color-rule: #d7d7dc;
+  --color-rule-2: #e6e6ea;
+  --color-rule-strong: #b0b1ba;
+
+  /* Softer stripes — the near-white base makes any delta read stronger. */
+  --row-stripe: 2%;
+  --row-hover: 4%;
+
+  /* Accent, semantics, indigo ramp, tiles — unchanged from paper. */
+
+  /* Cooler, crisper shadows; the white top-inset highlight from paper is
+     dropped — invisible on white surfaces. */
+  --shadow-inset: 0 1px 2px rgba(23, 25, 45, 0.05);
+  --shadow-rest: 0 1px 2px rgba(23, 25, 45, 0.05),
+    0 3px 10px -3px rgba(23, 25, 45, 0.07);
+  --shadow-raised: 0 2px 4px rgba(23, 25, 45, 0.05),
+    0 12px 28px -10px rgba(23, 25, 45, 0.14);
+  --shadow-float: 0 4px 10px rgba(23, 25, 45, 0.06),
+    0 28px 60px -20px rgba(23, 25, 45, 0.22);
+}
+
+/* Dark — parallel ramp, not an inversion. Accent lifts to a lighter
+   indigo so fills and focus halos hold contrast against dark surfaces. */
+:root[data-theme='dark'] {
+  color-scheme: dark;
+
+  --color-bg: #111318;
+  --color-surface: #191c24;
+  --color-surface-2: #222633;
+  --color-surface-3: #2c3140;
+
+  --color-ink: #e9eaf0;
+  --color-ink-2: #c5c8d4;
+  --color-ink-3: #9297a8;
+  --color-ink-4: #6d7183;
+
+  --color-rule: #32384a;
+  --color-rule-2: #272c38;
+  --color-rule-strong: #4a5166;
+
+  /* Dark rows lighten as they stripe; a touch more to stay legible. */
+  --row-stripe: 4%;
+  --row-hover: 7%;
+
+  /* accent-2 is the hover fill on accent chrome under fixed light text —
+     in dark it must darken (rest accent is already light-ish), not lighten.
+     accent-ink flips to a light indigo: it's the text color on tinted
+     surfaces and the hover fill under text-surface (dark) — both want light. */
+  --color-accent: #6b78b4;
+  --color-accent-2: #5d6aa6;
+  --color-accent-ink: #ccd3f0;
+
+  --color-success: #7fae7c;
+  --color-warning: #d0a75a;
+  --color-danger: #d08a83;
+  --color-info: #6b78b4;
+
+  /* Indigo ramp inverted so a low index stays "subtle against bg". */
+  --color-indigo-50: #232945;
+  --color-indigo-100: #2c3354;
+  --color-indigo-200: #3a4370;
+  --color-indigo-300: #4d5890;
+  --color-indigo-400: #6b78b4;
+  --color-indigo-500: #8290c8;
+  --color-indigo-600: #a5b0d9;
+  --color-indigo-700: #c7cee9;
+  --color-indigo-800: #e4e7f5;
+
+  /* Tile fills stay saturated mid-tones; tile-fg unchanged. */
+
+  --shadow-inset: 0 1px 2px rgba(0, 0, 0, 0.35);
+  --shadow-rest: 0 1px 2px rgba(0, 0, 0, 0.35),
+    0 4px 12px -4px rgba(0, 0, 0, 0.45);
+  --shadow-raised: 0 2px 4px rgba(0, 0, 0, 0.35),
+    0 14px 30px -12px rgba(0, 0, 0, 0.55);
+  --shadow-float: 0 4px 10px rgba(0, 0, 0, 0.4),
+    0 30px 60px -24px rgba(0, 0, 0, 0.65);
+  --shadow-focus: 0 0 0 4px color-mix(in oklab, var(--color-accent) 35%, transparent);
+  --shadow-focus-danger: 0 0 0 4px
+    color-mix(in oklab, var(--color-danger) 28%, transparent);
+}
+
+/* Paper grain — faint dotted multiply overlay, identical to the design system spec.
+   Applied as a fixed decorative layer above content but below interactive chrome. */
+.proteos-grain::before {
+  content: "";
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 100;
+  opacity: 0.32;
+  mix-blend-mode: multiply;
+  background-image:
+    radial-gradient(rgba(40, 38, 55, 0.035) 1px, transparent 1px),
+    radial-gradient(rgba(40, 38, 55, 0.025) 1px, transparent 1px);
+  background-size: 3px 3px, 7px 7px;
+  background-position: 0 0, 1px 2px;
+}
+
+/* Grain is a paper-mode signature only. On white it reads as dirt; the
+   multiply dots vanish or muddy on dark. Absent attribute = paper.
+   `.proteos-grain-dots` gates inline-styled dot overlays (page-designer
+   canvas) the same way. */
+:root[data-theme='light'] .proteos-grain::before,
+:root[data-theme='dark'] .proteos-grain::before {
+  content: none;
+}
+
+:root[data-theme='light'] .proteos-grain-dots,
+:root[data-theme='dark'] .proteos-grain-dots {
+  display: none;
+}
+
+/* DEPRECATED aliases for module components built before the surface rename
+   (2026-07). Already-deployed module bundles bake `var(--color-bg-2)` /
+   `var(--color-bg-3)` strings that no longer exist after the rename; these
+   keep them resolving (and they chain through the theme overrides above,
+   since custom properties resolve at use-time). Remove once every module is
+   redeployed against the surface-* names. Note: old `var(--color-bg)` now
+   resolves to the new base (was the surface color) — near-identical in every
+   theme, so no alias is provided for it. */
+:root {
+  --color-bg-2: var(--color-surface-2);
+  --color-bg-3: var(--color-surface-3);
+}

package/src/test/setup.ts

@@ -0,0 +1,9 @@
+import * as matchers from '@testing-library/jest-dom/matchers'
+import { cleanup } from '@testing-library/react'
+import { afterEach, expect } from 'vitest'
+
+expect.extend(matchers)
+
+afterEach(() => {
+  cleanup()
+})