@proteos/ui 0.57.1 → 0.59.0

package/src/components/text-shimmer/text-shimmer.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { TextShimmer } from './text-shimmer'
+
+const meta: Meta<typeof TextShimmer> = {
+  title: 'Components/TextShimmer',
+  component: TextShimmer,
+  tags: ['autodocs'],
+  argTypes: {
+    tone: { control: 'radio', options: ['muted', 'accent'] },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof TextShimmer>
+
+export const Playground: Story = { args: { children: 'Searching records…', tone: 'muted' } }
+
+export const LoadingRow: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="text-[13px]">
+      <TextShimmer>Searching records…</TextShimmer>
+    </div>
+  ),
+}
+
+export const GlowingHeading: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <h2 className="text-2xl font-semibold">
+      <TextShimmer tone="accent">Composing your brief</TextShimmer>
+    </h2>
+  ),
+}

package/src/components/text-shimmer/text-shimmer.test.tsx

@@ -0,0 +1,16 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { TextShimmer } from './text-shimmer'
+
+describe('TextShimmer', () => {
+  it('keeps the text readable in the DOM', () => {
+    render(<TextShimmer>Searching records…</TextShimmer>)
+    expect(screen.getByText('Searching records…')).toBeInTheDocument()
+  })
+
+  it('passes through native span attributes', () => {
+    render(<TextShimmer data-testid="shimmer">Thinking…</TextShimmer>)
+    expect(screen.getByTestId('shimmer').tagName).toBe('SPAN')
+  })
+})

package/src/components/text-shimmer/text-shimmer.tsx

@@ -0,0 +1,43 @@
+import type { HTMLAttributes } from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   TextShimmer — a bright band sweeping across text. The text is clipped to
+   a wide gradient (muted → ink → muted) whose position animates, so only the
+   glyphs light up. For loading / streaming states ("Searching…", "Thinking…")
+   or a glowing heading. Pure cosmetics; the text itself stays in the DOM and
+   is read normally. Honors `prefers-reduced-motion` (static, muted text).
+   ========================================================================= */
+
+export const textShimmerStyles = tv({
+  base: [
+    'inline-block bg-clip-text text-transparent',
+    'bg-[length:200%_auto] animate-text-shimmer',
+    'motion-reduce:animate-none motion-reduce:bg-none motion-reduce:text-ink-4',
+  ],
+  variants: {
+    tone: {
+      // Muted band on a muted base — a quiet loading row.
+      muted:
+        'bg-[linear-gradient(90deg,var(--color-ink-4)_0%,var(--color-ink-4)_40%,var(--color-ink)_50%,var(--color-ink-4)_60%,var(--color-ink-4)_100%)]',
+      // Accent band on ink — a glowing heading.
+      accent:
+        'bg-[linear-gradient(90deg,var(--color-ink)_0%,var(--color-ink)_40%,var(--color-accent)_50%,var(--color-ink)_60%,var(--color-ink)_100%)] motion-reduce:text-ink',
+    },
+  },
+  defaultVariants: { tone: 'muted' },
+})
+
+export type TextShimmerVariants = VariantProps<typeof textShimmerStyles>
+
+export type TextShimmerProps = HTMLAttributes<HTMLSpanElement> & TextShimmerVariants
+
+export function TextShimmer({ tone, className, children, ...props }: TextShimmerProps) {
+  return (
+    <span {...props} className={cn(textShimmerStyles({ tone }), className)}>
+      {children}
+    </span>
+  )
+}

package/src/components/textarea/textarea.tsx

@@ -54,7 +54,7 @@ export function Textarea({
       {...props}
       className={(renderProps) =>
         cn(
-          'grid grid-cols-1 gap-1.5',
+          'grid grid-cols-1 gap-1.5 content-start',
           typeof className === 'function' ? className(renderProps) : className,
         )
       }

package/src/components/time-field/time-field.tsx

@@ -52,7 +52,7 @@ export function TimeField<T extends TimeValue = TimeValue>({
       {...props}
       className={(renderProps) =>
         cn(
-          'grid grid-cols-1 gap-1.5',
+          'grid grid-cols-1 gap-1.5 content-start',
           typeof className === 'function' ? className(renderProps) : className,
         )
       }

package/src/index.ts

@@ -38,9 +38,11 @@ export * from './components/nav'
 export * from './components/orb'
 export * from './components/popover'
 export * from './components/progress-bar'
+export * from './components/progress-ring'
 export * from './components/radio-group'
 export * from './components/recipient-select'
 export * from './components/record-filter'
+export * from './components/record-update'
 export * from './components/segmented-control'
 export * from './components/select'
 export * from './components/separator'
@@ -50,6 +52,7 @@ export * from './components/switch'
 export * from './components/table'
 export * from './components/tabs'
 export * from './components/tag-input'
+export * from './components/text-shimmer'
 export * from './components/textarea'
 export * from './components/time-field'
 export * from './components/toast'

package/src/lib/commands/index.ts

@@ -1,9 +1,13 @@
+export { useDiscoveryActive } from './discovery-store'
+export { isEditableTarget } from './match-event'
 export type { KeyCombo } from './parse-combo'
 export { parseCombo } from './parse-combo'
+export type { Platform } from './platform'
+export { getPlatform } from './platform'
 export { PROTECTED_COMBOS } from './protected-combos'
-export { isEditableTarget } from './match-event'
+export type { ActiveCommand, CommandLabel } from './registry'
+export { useActiveCommands } from './use-active-commands'
 export type { UseCommandOptions } from './use-command'
 export { useCommand } from './use-command'
 export type { UseEscapeKeyOptions } from './use-escape-key'
 export { useEscapeKey } from './use-escape-key'
-export { useDiscoveryActive } from './discovery-store'

package/src/lib/commands/registry.test.ts

@@ -2,7 +2,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { parseCombo } from './parse-combo'
 import { _setPlatformForTests } from './platform'
-import { _resetRegistry, register } from './registry'
+import {
+  _resetRegistry,
+  getActiveCommandsSnapshot,
+  listActiveCommands,
+  register,
+  subscribe,
+} from './registry'
 
 function dispatchKey(init: KeyboardEventInit & { cancelable?: boolean }): KeyboardEvent {
   const ev = new KeyboardEvent('keydown', { bubbles: true, cancelable: true, ...init })
@@ -95,3 +101,50 @@ describe('registry', () => {
     expect(fn).not.toHaveBeenCalled()
   })
 })
+
+describe('registry — active commands', () => {
+  beforeEach(() => {
+    _setPlatformForTests('mac')
+    _resetRegistry()
+  })
+  afterEach(() => {
+    _setPlatformForTests(undefined)
+  })
+
+  it('lists labeled top-of-stack bindings and invokes them', () => {
+    const save = vi.fn()
+    const older = vi.fn()
+    register(parseCombo('mod+s'), older, { label: 'Old save' })
+    register(parseCombo('mod+s'), save, { label: 'Save' })
+    register(parseCombo('mod+k'), () => {}) // unlabeled → not an action
+
+    const active = listActiveCommands()
+    expect(active.map((a) => [a.combo.raw, a.label])).toEqual([['mod+s', 'Save']])
+
+    active[0]?.invoke()
+    expect(save).toHaveBeenCalledTimes(1)
+    expect(older).not.toHaveBeenCalled()
+  })
+
+  it('resolves label getters when the list is built and drops empty ones', () => {
+    let name: string | undefined = 'Filter'
+    register(parseCombo('mod+f'), () => {}, { label: () => name })
+    register(parseCombo('mod+g'), () => {}, { label: () => '  ' })
+    expect(listActiveCommands().map((a) => a.label)).toEqual(['Filter'])
+    name = undefined
+    expect(listActiveCommands()).toEqual([])
+  })
+
+  it('notifies subscribers on register and unregister, with a stable snapshot in between', () => {
+    const listener = vi.fn()
+    subscribe(listener)
+    const unregister = register(parseCombo('mod+s'), () => {}, { label: 'Save' })
+    expect(listener).toHaveBeenCalledTimes(1)
+    const first = getActiveCommandsSnapshot()
+    expect(getActiveCommandsSnapshot()).toBe(first)
+    expect(first.map((a) => a.label)).toEqual(['Save'])
+    unregister()
+    expect(listener).toHaveBeenCalledTimes(2)
+    expect(getActiveCommandsSnapshot()).toEqual([])
+  })
+})

package/src/lib/commands/registry.ts

@@ -7,16 +7,40 @@
    Editable targets are NOT skipped here — `mod+<key>` combos use a real
    modifier, so they can't be confused with text input the way bare keys
    can. Cmd+S in a form field should still save. (The `useEscapeKey` path
-   keeps its editable-target skip because Escape is bare.) */
+   keeps its editable-target skip because Escape is bare.)
+
+   Entries may carry a label — the name of the thing the combo does ("Save",
+   "Cancel", "Filter"). Labeled, top-of-stack entries are what
+   `listActiveCommands()` exposes, so a palette can list "what can I do on
+   this page right now" and invoke it without the keyboard. Subscribers
+   (`subscribe`) are told whenever the stacks change. */
 
 import { matches } from './match-event'
 import type { KeyCombo } from './parse-combo'
 
 type Handler = (event: KeyboardEvent) => void
-type Entry = { combo: KeyCombo; handler: Handler }
+/** A fixed name, or a getter resolved when the list is built (so a wrapper
+ *  can read its control's accessible name from the DOM). */
+export type CommandLabel = string | (() => string | undefined)
+type Entry = { combo: KeyCombo; handler: Handler; label?: CommandLabel }
+
+export type RegisterOptions = { label?: CommandLabel }
+
+/** A labeled binding that will fire right now if its combo is pressed. */
+export type ActiveCommand = {
+  combo: KeyCombo
+  label: string
+  /** Run the binding as if its combo had been pressed. */
+  invoke: () => void
+}
 
 const stacks = new Map<string, Entry[]>()
+const listeners = new Set<() => void>()
 let listenerInstalled = false
+let version = 0
+let snapshotVersion = -1
+let snapshot: ActiveCommand[] = []
+const EMPTY: ActiveCommand[] = []
 
 function onWindowKeyDown(event: KeyboardEvent): void {
   for (const entries of stacks.values()) {
@@ -38,22 +62,83 @@ function ensureListener(): void {
   listenerInstalled = true
 }
 
-export function register(combo: KeyCombo, handler: Handler): () => void {
+function emit(): void {
+  version++
+  for (const listener of listeners) listener()
+}
+
+export function register(combo: KeyCombo, handler: Handler, options?: RegisterOptions): () => void {
   ensureListener()
   const list = stacks.get(combo.raw) ?? []
-  const entry: Entry = { combo, handler }
+  const entry: Entry = {
+    combo,
+    handler,
+    ...(options?.label !== undefined ? { label: options.label } : {}),
+  }
   list.push(entry)
   stacks.set(combo.raw, list)
+  emit()
   return () => {
     const current = stacks.get(combo.raw)
     if (!current) return
     const idx = current.lastIndexOf(entry)
     if (idx >= 0) current.splice(idx, 1)
     if (current.length === 0) stacks.delete(combo.raw)
+    emit()
+  }
+}
+
+/** Notified after every register / unregister. */
+export function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+function resolveLabel(label: CommandLabel | undefined): string | undefined {
+  const value = typeof label === 'function' ? label() : label
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : undefined
+}
+
+function invokeEntry(entry: Entry): void {
+  entry.handler(new KeyboardEvent('keydown', { key: entry.combo.key, cancelable: true }))
+}
+
+/** The labeled, top-of-stack bindings, in registration order of their combos.
+ *  Unlabeled bindings (a palette toggle, an undo hook) are not actions. */
+export function listActiveCommands(): ActiveCommand[] {
+  const out: ActiveCommand[] = []
+  for (const entries of stacks.values()) {
+    const top = entries[entries.length - 1]
+    if (!top) continue
+    const label = resolveLabel(top.label)
+    if (!label) continue
+    out.push({ combo: top.combo, label, invoke: () => invokeEntry(top) })
+  }
+  return out
+}
+
+/** `listActiveCommands()` memoised per registry change — referentially stable
+ *  between changes, as useSyncExternalStore requires. */
+export function getActiveCommandsSnapshot(): ActiveCommand[] {
+  if (snapshotVersion !== version) {
+    snapshot = listActiveCommands()
+    snapshotVersion = version
   }
+  return snapshot
+}
+
+export function getActiveCommandsServerSnapshot(): ActiveCommand[] {
+  return EMPTY
 }
 
 // Test-only: clear the registry between cases.
 export function _resetRegistry(): void {
   stacks.clear()
+  listeners.clear()
+  version = 0
+  snapshotVersion = -1
+  snapshot = []
 }

package/src/lib/commands/use-active-commands.test.tsx

@@ -0,0 +1,56 @@
+import { act, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { _setPlatformForTests } from './platform'
+import { _resetRegistry } from './registry'
+import { useActiveCommands } from './use-active-commands'
+import { useCommand } from './use-command'
+
+function Bind({ combo, label, handler }: { combo: string; label: string; handler: () => void }) {
+  useCommand(combo, handler, { label })
+  return null
+}
+
+function ActionList() {
+  const actions = useActiveCommands()
+  return (
+    <ul>
+      {actions.map((action) => (
+        <li key={action.combo.raw}>
+          <button type="button" onClick={action.invoke}>
+            {action.label}
+          </button>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+describe('useActiveCommands', () => {
+  beforeEach(() => {
+    _setPlatformForTests('mac')
+    _resetRegistry()
+  })
+  afterEach(() => {
+    _setPlatformForTests(undefined)
+  })
+
+  it('tracks labeled bindings as they mount and unmount', () => {
+    const save = vi.fn()
+    const { rerender } = render(
+      <>
+        <ActionList />
+        <Bind combo="mod+s" label="Save" handler={save} />
+      </>,
+    )
+    expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument()
+
+    act(() => {
+      screen.getByRole('button', { name: 'Save' }).click()
+    })
+    expect(save).toHaveBeenCalledTimes(1)
+
+    rerender(<ActionList />)
+    expect(screen.queryByRole('button', { name: 'Save' })).not.toBeInTheDocument()
+  })
+})

package/src/lib/commands/use-active-commands.ts

@@ -0,0 +1,16 @@
+/* The labeled bindings that would fire right now — what a command palette
+   lists as "Actions". Re-renders whenever a binding mounts, unmounts, or is
+   shadowed by a newer one for the same combo. */
+
+import { useSyncExternalStore } from 'react'
+
+import {
+  type ActiveCommand,
+  getActiveCommandsServerSnapshot,
+  getActiveCommandsSnapshot,
+  subscribe,
+} from './registry'
+
+export function useActiveCommands(): ActiveCommand[] {
+  return useSyncExternalStore(subscribe, getActiveCommandsSnapshot, getActiveCommandsServerSnapshot)
+}

package/src/lib/commands/use-command.ts

@@ -1,16 +1,20 @@
-/* Bind a `mod+<key>` command. The handler is wrapped in a ref so changing
-   handler identity each render does not re-register; only `combo` and
-   `enabled` are real dependencies. */
+/* Bind a `mod+<key>` command. The handler (and label) are wrapped in refs so
+   changing their identity each render does not re-register; only `combo`
+   and `enabled` are real dependencies. */
 
 import { useEffect, useRef } from 'react'
 
 import { parseCombo } from './parse-combo'
 import { assertNotProtected } from './protected-combos'
-import { register } from './registry'
+import { type CommandLabel, register } from './registry'
 
 export type UseCommandOptions = {
   /** Defaults to `true`. Set to `false` to temporarily disable without unmounting. */
   enabled?: boolean
+  /** What the binding does ("Save", "Filter"). Labeled bindings are listed by
+   *  `useActiveCommands()` — the command palette's "Actions" — and can be
+   *  invoked from there. Unlabeled bindings stay keyboard-only. */
+  label?: CommandLabel
 }
 
 export function useCommand(
@@ -20,13 +24,20 @@ export function useCommand(
 ): void {
   const enabled = options?.enabled ?? true
   const handlerRef = useRef(handler)
+  const labelRef = useRef(options?.label)
   useEffect(() => {
     handlerRef.current = handler
+    labelRef.current = options?.label
   })
   useEffect(() => {
     if (!enabled) return undefined
     const parsed = parseCombo(combo)
     assertNotProtected(parsed)
-    return register(parsed, (event) => handlerRef.current(event))
+    return register(parsed, (event) => handlerRef.current(event), {
+      label: () => {
+        const label = labelRef.current
+        return typeof label === 'function' ? label() : label
+      },
+    })
   }, [combo, enabled])
 }

package/src/styles.css

@@ -149,6 +149,20 @@
   --animate-exit-slide-up: exit-slide-up 100ms ease both;
   --animate-exit-zoom: exit-zoom 100ms ease both;
 
+  /* Text shimmer — a bright band sweeping across text that is clipped to a
+     gradient background (see the TextShimmer component). Loading / streaming
+     states; linear so the sweep reads as continuous. */
+  --animate-text-shimmer: text-shimmer 2s linear infinite;
+
+}
+
+@keyframes text-shimmer {
+  from {
+    background-position: 200% center;
+  }
+  to {
+    background-position: -200% center;
+  }
 }
 
 @keyframes indeterminate-progress {