@proteos/ui 0.31.0

package/src/components/command/command-hint.tsx

@@ -0,0 +1,46 @@
+import { cn } from '../../lib/cn'
+import { parseCombo } from '../../lib/commands/parse-combo'
+import { getPlatform } from '../../lib/commands/platform'
+import { Kbd } from '../kbd'
+
+/* =========================================================================
+   CommandHint — visual representation of a `mod+<key>` combo. Renders a
+   single `<Kbd>` so it slots in where the cosmetic `<Kbd>⌘K</Kbd>` lived
+   before. On macOS the modifier is shown as `⌘` glued directly to the key
+   (`⌘K`); on other platforms it reads `Ctrl+K`. Pure presentation — no
+   binding, no listeners.
+
+   `tone="prominent"` flips the cap to a high-contrast surface for use on
+   the discovery overlay where it needs to stand out against the backdrop.
+   ========================================================================= */
+
+export type CommandHintTone = 'subtle' | 'prominent'
+
+export type CommandHintProps = {
+  combo: string
+  tone?: CommandHintTone
+  className?: string
+}
+
+export function CommandHint({ combo, tone = 'subtle', className }: CommandHintProps) {
+  const parsed = parseCombo(combo)
+  const platform = getPlatform()
+  const modSymbol = platform === 'mac' ? '⌘' : 'Ctrl'
+  const keyLabel = parsed.isLetter ? parsed.key.toUpperCase() : prettifyKey(parsed.key)
+  const label = platform === 'mac' ? `${modSymbol}${keyLabel}` : `${modSymbol}+${keyLabel}`
+  return (
+    <Kbd
+      className={cn(
+        tone === 'prominent' && 'bg-ink text-surface border-transparent',
+        className,
+      )}
+    >
+      {label}
+    </Kbd>
+  )
+}
+
+function prettifyKey(key: string): string {
+  if (key.length === 0) return key
+  return key[0]!.toUpperCase() + key.slice(1)
+}

package/src/components/command/command.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { Button } from '../button'
+
+import { Command } from './command'
+import { CommandHint } from './command-hint'
+
+const meta: Meta<typeof Command> = {
+  title: 'Components/Command',
+  component: Command,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: [
+          'Discovery-aware wrapper that binds a `mod+<key>` combo to a child',
+          'button and reveals the shortcut on Cmd+Shift hold. Note: browser',
+          'default combos like `mod+S` are technically overridable, but you',
+          'should make that a deliberate choice — most productivity apps only',
+          'override them inside document-editor contexts.',
+        ].join(' '),
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Command>
+
+export const Basic: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    function Demo() {
+      const [count, setCount] = useState(0)
+      return (
+        <div className="flex flex-col items-start gap-3">
+          <p className="text-[13px] text-ink-3">
+            Press <strong>Cmd+J</strong> (or hold <strong>Cmd+Shift</strong> to peek the
+            shortcut, then press <strong>J</strong>).
+          </p>
+          <Command combo="mod+j">
+            <Button onPress={() => setCount((c) => c + 1)}>Increment ({count})</Button>
+          </Command>
+        </div>
+      )
+    }
+    return <Demo />
+  },
+}
+
+export const DiscoveryFlow: Story = {
+  parameters: {
+    controls: { hideNoControlsWarning: true },
+    docs: {
+      description: {
+        story:
+          'Hold Cmd+Shift to reveal the bound shortcut as an overlay chip over each `<Command>` on the page. Press the bound key to fire the action.',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-start gap-3 p-6 bg-surface-2 rounded-md">
+      <Command combo="mod+s">
+        <Button>Save</Button>
+      </Command>
+      <Command combo="mod+d">
+        <Button variant="subtle">Duplicate</Button>
+      </Command>
+      <Command combo="mod+e">
+        <Button variant="ghost">Export</Button>
+      </Command>
+    </div>
+  ),
+}
+
+export const Hint: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="flex flex-col gap-2 text-[13px] text-ink-3">
+      <div className="flex items-center gap-2">
+        Open the palette: <CommandHint combo="mod+k" />
+      </div>
+      <div className="flex items-center gap-2">
+        Prominent variant: <CommandHint combo="mod+k" tone="prominent" />
+      </div>
+    </div>
+  ),
+}

package/src/components/command/command.test.tsx

@@ -0,0 +1,102 @@
+import { act, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { Button } from '../button'
+import { _resetDiscovery } from '../../lib/commands/discovery-store'
+import { _setPlatformForTests } from '../../lib/commands/platform'
+import { _resetRegistry } from '../../lib/commands/registry'
+
+import { Command } from './command'
+
+function dispatchModS() {
+  window.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      metaKey: true,
+      code: 'KeyS',
+      key: 's',
+    }),
+  )
+}
+
+function holdCmdShift() {
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Shift', shiftKey: true }))
+    window.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Meta', shiftKey: true, metaKey: true }),
+    )
+  })
+}
+
+describe('Command', () => {
+  beforeEach(() => {
+    _setPlatformForTests('mac')
+    _resetRegistry()
+    _resetDiscovery()
+  })
+  afterEach(() => {
+    _setPlatformForTests(undefined)
+  })
+
+  it('fires the wrapped Button.onPress when the combo is pressed', () => {
+    const onPress = vi.fn()
+    render(
+      <Command combo="mod+s">
+        <Button onPress={onPress}>Save</Button>
+      </Command>,
+    )
+    dispatchModS()
+    expect(onPress).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows the discovery hint only while Cmd+Shift is held', () => {
+    render(
+      <Command combo="mod+s">
+        <Button>Save</Button>
+      </Command>,
+    )
+    expect(screen.queryByText('⌘S')).toBeNull()
+    holdCmdShift()
+    expect(screen.getByText('⌘S')).toBeInTheDocument()
+  })
+
+  it('cleans up on unmount', () => {
+    const onPress = vi.fn()
+    const { unmount } = render(
+      <Command combo="mod+s">
+        <Button onPress={onPress}>Save</Button>
+      </Command>,
+    )
+    unmount()
+    dispatchModS()
+    expect(onPress).not.toHaveBeenCalled()
+  })
+
+  it('targets a descendant when `target` is provided (used by RecordView for the filter)', () => {
+    const onPress = vi.fn()
+    render(
+      <Command combo="mod+s" target="[data-test-trigger]">
+        <span>
+          <Button>Decoy</Button>
+          <Button data-test-trigger onPress={onPress}>
+            Save
+          </Button>
+        </span>
+      </Command>,
+    )
+    dispatchModS()
+    expect(onPress).toHaveBeenCalledTimes(1)
+  })
+
+  it('does nothing when `target` matches no descendant', () => {
+    const onPress = vi.fn()
+    render(
+      <Command combo="mod+s" target="[data-missing]">
+        <Button onPress={onPress}>Save</Button>
+      </Command>,
+    )
+    dispatchModS()
+    expect(onPress).not.toHaveBeenCalled()
+  })
+})

package/src/components/command/command.tsx

@@ -0,0 +1,76 @@
+'use client'
+
+import { type ReactNode, useRef } from 'react'
+
+import { cn } from '../../lib/cn'
+import { useCommand } from '../../lib/commands/use-command'
+import { useDiscoveryActive } from '../../lib/commands/discovery-store'
+
+import { CommandHint } from './command-hint'
+
+/* =========================================================================
+   Command — discovery-aware wrapper around an interactive element. Binds
+   `combo` to a synthetic click on the wrapped child (RAC `Button`'s
+   `onPress` listens for native click events, so this fires the user's
+   handler), and reveals a hint chip while Cmd+Shift is held so users can
+   learn the bound shortcut.
+
+       <Command combo="mod+s">
+         <Button onPress={onSave}>Save</Button>
+       </Command>
+
+   When the trigger isn't the immediate child (e.g. wrapped in a `<span>`
+   for popover anchoring, or buried inside a list), pass `target` — a CSS
+   selector resolved against the wrapper. The first matching descendant
+   receives the synthetic click.
+
+       <Command combo="mod+f" target="[data-filter-trigger]">
+         <RecordFilterButton … />
+         <RecordFilterChips … />
+       </Command>
+
+   `className` overrides the wrapper layout (default `inline-block`) for
+   call sites where the wrapper needs to participate in a flex/grid layout.
+   The wrapper stays `relative` either way so the discovery overlay can
+   absolute-position against it.
+   ========================================================================= */
+
+export type CommandProps = {
+  combo: string
+  /** CSS selector for the click target. Defaults to the wrapper's first
+   *  element child — fine when that child IS the interactive control. */
+  target?: string
+  /** Layout overrides for the wrapper. `relative` is always applied. */
+  className?: string
+  children: ReactNode
+}
+
+export function Command({ combo, target, className, children }: CommandProps) {
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const discoveryActive = useDiscoveryActive()
+
+  useCommand(combo, () => {
+    const root = wrapperRef.current
+    if (!root) return
+    const el = target
+      ? root.querySelector<HTMLElement>(target)
+      : (root.firstElementChild as HTMLElement | null)
+    el?.click()
+  })
+
+  return (
+    <div ref={wrapperRef} className={cn('relative inline-block', className)}>
+      {children}
+      {discoveryActive ? (
+        <div
+          aria-hidden
+          className="absolute -inset-2 rounded-md bg-[color-mix(in_oklab,var(--color-ink)_28%,transparent)] pointer-events-none transition-opacity z-40"
+        >
+          <span className="absolute -top-2.5 -left-2 pointer-events-none z-50">
+            <CommandHint combo={combo} tone="prominent" />
+          </span>
+        </div>
+      ) : null}
+    </div>
+  )
+}

package/src/components/command/index.ts

@@ -0,0 +1,16 @@
+export type { CommandProps } from './command'
+export { Command } from './command'
+export type { CommandHintProps, CommandHintTone } from './command-hint'
+export { CommandHint } from './command-hint'
+
+// Re-export the command-system primitives so consumers can `import { useCommand,
+// useEscapeKey, parseCombo, useDiscoveryActive } from '@proteos/ui'`.
+export type { KeyCombo, UseCommandOptions, UseEscapeKeyOptions } from '../../lib/commands'
+export {
+  isEditableTarget,
+  parseCombo,
+  PROTECTED_COMBOS,
+  useCommand,
+  useDiscoveryActive,
+  useEscapeKey,
+} from '../../lib/commands'

package/src/components/currency-input/currency-input.tsx

@@ -0,0 +1,192 @@
+import { formatAmount, parseAmount } from '@proteos/sdk'
+import { ChevronDown } from 'lucide-react'
+import { type ReactNode, useEffect, useState } from 'react'
+import {
+  Button as AriaSelectTrigger,
+  ListBox,
+  ListBoxItem,
+  Popover,
+  Select as AriaSelect,
+} from 'react-aria-components'
+
+import { cn } from '../../lib/cn'
+import { type FieldAppearance, fieldControlStyles, fieldErrorStyles, type FieldSize } from '../field/field'
+
+/* =========================================================================
+   CurrencyInput — a single money field: an amount input plus a trailing
+   currency-symbol button that opens a symbol+code dropdown (the same shape as
+   the date-picker's trailing calendar trigger).
+
+   The amount is held and emitted as a canonical decimal STRING (never
+   parseFloat'd) so precision and trailing zeros survive; it is *displayed* in
+   the viewer's locale (grouping + decimal separator) and parsed back from that
+   notation on input. The selectable currencies are passed in via
+   `currencyOptions` so the lib stays free of any ISO/Intl dataset; the locale
+   number helpers come from the SDK so there's one well-defined implementation.
+   ========================================================================= */
+
+export interface CurrencyInputValue {
+  amount: string
+  currency_code: string
+}
+
+export interface CurrencyInputOption {
+  code: string
+  /** The currency's symbol (e.g. "$", "€"); falls back to the code. */
+  symbol?: string
+}
+
+export interface CurrencyInputProps {
+  value: CurrencyInputValue | null
+  onChange: (next: CurrencyInputValue | null) => void
+  currencyOptions: ReadonlyArray<CurrencyInputOption>
+  /** Locale for the amount's grouping + decimal separators. Defaults to runtime. */
+  locale?: string
+  isReadOnly?: boolean
+  isInvalid?: boolean
+  errorMessage?: ReactNode
+  size?: FieldSize
+  appearance?: FieldAppearance
+  placeholder?: string
+  autoFocus?: boolean
+  'aria-label'?: string
+  onBlur?: () => void
+  className?: string
+}
+
+export function CurrencyInput({
+  value,
+  onChange,
+  currencyOptions,
+  locale,
+  isReadOnly,
+  isInvalid,
+  errorMessage,
+  size,
+  appearance,
+  placeholder,
+  autoFocus,
+  'aria-label': ariaLabel,
+  onBlur,
+  className,
+}: CurrencyInputProps) {
+  const amount = value?.amount ?? ''
+  const code = value?.currency_code ?? ''
+
+  // `draft` is the text shown in the input. It's grouped (e.g. "1.234,56") when
+  // the field is idle and ungrouped ("1234,56") while editing, so grouping
+  // doesn't fight the caret mid-type. The canonical value still flows out via
+  // onChange on every keystroke.
+  const [draft, setDraft] = useState(() => formatAmount(amount, locale, { grouped: true }))
+  const [isEditing, setIsEditing] = useState(false)
+
+  useEffect(() => {
+    if (!isEditing) setDraft(formatAmount(amount, locale, { grouped: true }))
+  }, [amount, locale, isEditing])
+
+  const emit = (nextAmount: string, nextCode: string) => {
+    if (nextAmount === '' && nextCode === '') {
+      onChange(null)
+      return
+    }
+    onChange({ amount: nextAmount, currency_code: nextCode })
+  }
+
+  const selectedSymbol = currencyOptions.find((option) => option.code === code)?.symbol ?? code
+
+  const styles = fieldControlStyles({ size, appearance, ...(isInvalid ? { invalid: true } : {}) })
+  const focusWithin =
+    appearance === 'cell'
+      ? 'focus-within:border-accent focus-within:shadow-none'
+      : 'focus-within:border-accent focus-within:shadow-[var(--shadow-focus)]'
+
+  return (
+    <div className={cn('grid grid-cols-1 gap-1.5', className)}>
+      <div className={cn(styles.box(), 'flex items-center gap-1 pr-1', focusWithin)}>
+        <input
+          className={cn(
+            'min-w-0 flex-1 bg-transparent text-ink outline-none tabular-nums',
+            styles.content(),
+            // Sit a touch lower than a standard field by trimming the vertical
+            // padding (cell mode keeps the fixed 29px row-editor height).
+            appearance === 'cell' ? '' : size === 'sm' ? 'py-1' : 'py-1.5',
+          )}
+          inputMode="decimal"
+          value={draft}
+          onChange={(event) => {
+            setDraft(event.target.value)
+            emit(parseAmount(event.target.value, locale), code)
+          }}
+          onFocus={() => {
+            setIsEditing(true)
+            setDraft(formatAmount(amount, locale, { grouped: false }))
+          }}
+          onBlur={() => {
+            setIsEditing(false)
+            const canonical = parseAmount(draft, locale)
+            setDraft(formatAmount(canonical, locale, { grouped: true }))
+            emit(canonical, code)
+            onBlur?.()
+          }}
+          readOnly={isReadOnly ?? false}
+          autoFocus={autoFocus ?? false}
+          placeholder={placeholder ?? ''}
+          aria-label={ariaLabel ? `${ariaLabel} amount` : 'Amount'}
+        />
+
+        <AriaSelect
+          aria-label={ariaLabel ? `${ariaLabel} currency` : 'Currency'}
+          selectedKey={code === '' ? null : code}
+          onSelectionChange={(key) => emit(amount, key == null ? '' : String(key))}
+          isDisabled={isReadOnly ?? false}
+        >
+          <AriaSelectTrigger
+            className={cn(
+              'inline-flex h-6 shrink-0 items-center gap-0.5 rounded-md px-1.5',
+              'text-ink-2 outline-none hover:bg-surface-2 hover:text-ink',
+              'cursor-pointer focus-visible:shadow-[var(--shadow-focus)]',
+              'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-45',
+            )}
+          >
+            <span className="min-w-[1ch] text-center tabular-nums">{selectedSymbol || '¤'}</span>
+            <ChevronDown className="size-3 opacity-60" aria-hidden />
+          </AriaSelectTrigger>
+
+          <Popover
+            offset={6}
+            className={cn(
+              'min-w-[9rem] rounded-md border border-rule bg-surface p-1',
+              'shadow-[var(--shadow-raised)]',
+              'entering:animate-in entering:fade-in-0 entering:slide-in-from-top-1',
+              'exiting:animate-out exiting:fade-out-0 exiting:slide-out-to-top-1',
+            )}
+          >
+            <ListBox className="max-h-72 overflow-auto outline-none">
+              {currencyOptions.map((option) => (
+                <ListBoxItem
+                  key={option.code}
+                  id={option.code}
+                  textValue={`${option.symbol ?? ''} ${option.code}`}
+                  className={cn(
+                    'flex items-center gap-2 rounded-[6px] px-2.5 py-1.5 text-[14px] text-ink-2',
+                    'cursor-pointer select-none outline-none',
+                    'data-[hovered]:bg-surface-2 data-[hovered]:text-ink',
+                    'data-[focused]:bg-surface-2 data-[focused]:text-ink',
+                    'data-[selected]:bg-surface-3 data-[selected]:text-ink',
+                  )}
+                >
+                  <span className="w-5 shrink-0 text-ink-3 tabular-nums">{option.symbol ?? ''}</span>
+                  <span className="font-medium">{option.code}</span>
+                </ListBoxItem>
+              ))}
+            </ListBox>
+          </Popover>
+        </AriaSelect>
+      </div>
+
+      {errorMessage && appearance !== 'cell' ? (
+        <div className={fieldErrorStyles}>{errorMessage}</div>
+      ) : null}
+    </div>
+  )
+}

package/src/components/currency-input/index.ts

@@ -0,0 +1,6 @@
+export type {
+  CurrencyInputOption,
+  CurrencyInputProps,
+  CurrencyInputValue,
+} from './currency-input'
+export { CurrencyInput } from './currency-input'

package/src/components/data-table/cells.stories.tsx

@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHeader,
+  TableHeaderCell,
+  TableHeaderSpacer,
+  TableRow,
+} from '../table'
+import { BooleanCell, DateCell, DateTimeCell, LinkCell, TruncateCell } from './cells'
+
+/* =========================================================================
+   Stories for the attribute-driven cell helpers. These are intentionally
+   small — they ship in the lib only because RecordTable dispatches on
+   AttributeType at runtime. Anything domain-specific (status pills, route
+   pairs, deltas, avatars+name) is consumer JSX inside `column.cell`.
+   ========================================================================= */
+
+const meta: Meta = {
+  title: 'Components/DataTable/Cells',
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+}
+export default meta
+
+type Story = StoryObj
+
+const COL_WIDTHS = { label: 180, value: 240 } as const
+
+function Showcase({ rows }: { rows: ReadonlyArray<{ label: string; value: React.ReactNode }> }) {
+  return (
+    <div className="w-[480px]">
+      <Table aria-label="Cell helpers">
+        <TableHeader>
+          <TableHeaderCell width={COL_WIDTHS.label}>Cell</TableHeaderCell>
+          <TableHeaderCell width={COL_WIDTHS.value}>Renders</TableHeaderCell>
+          <TableHeaderSpacer />
+        </TableHeader>
+        <TableBody>
+          {rows.map((row, i) => (
+            <TableRow key={row.label} alt={i % 2 === 1} style={{ height: 36 }}>
+              <TableCell width={COL_WIDTHS.label} mono>
+                {row.label}
+              </TableCell>
+              <TableCell width={COL_WIDTHS.value}>{row.value}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  )
+}
+
+export const DateCells: Story = {
+  render: () => (
+    <Showcase
+      rows={[
+        { label: 'DateCell · ISO', value: <DateCell value="2026-04-28" /> },
+        { label: 'DateCell · null', value: <DateCell value={null} /> },
+        { label: 'DateTimeCell', value: <DateTimeCell value="2026-04-28T13:42:00Z" /> },
+        { label: 'DateTimeCell · invalid', value: <DateTimeCell value="not-a-date" /> },
+      ]}
+    />
+  ),
+}
+
+export const Booleans: Story = {
+  render: () => (
+    <Showcase
+      rows={[
+        { label: 'BooleanCell · true', value: <BooleanCell value={true} /> },
+        { label: 'BooleanCell · false', value: <BooleanCell value={false} /> },
+        { label: 'BooleanCell · null', value: <BooleanCell value={null} /> },
+      ]}
+    />
+  ),
+}
+
+export const Truncation: Story = {
+  render: () => (
+    <Showcase
+      rows={[
+        {
+          label: 'TruncateCell · short',
+          value: <TruncateCell value="Atlanta, GA" />,
+        },
+        {
+          label: 'TruncateCell · long',
+          value: (
+            <TruncateCell value="Industrial chemicals, hazmat class 3, 18,420 lb, refrigeration not required" />
+          ),
+        },
+        { label: 'TruncateCell · empty', value: <TruncateCell value={null} /> },
+      ]}
+    />
+  ),
+}
+
+export const Links: Story = {
+  render: () => (
+    <Showcase
+      rows={[
+        {
+          label: 'LinkCell',
+          value: <LinkCell href="#shipment-10482">SH-10482</LinkCell>,
+        },
+        {
+          label: 'LinkCell · external',
+          value: (
+            <LinkCell href="https://example.com/SH-10482" target="_blank" rel="noreferrer">
+              View on partner ↗
+            </LinkCell>
+          ),
+        },
+      ]}
+    />
+  ),
+}