@proteos/ui 0.31.0

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

@@ -0,0 +1,98 @@
+import type { ReactNode } from 'react'
+import {
+  TimeField as AriaTimeField,
+  type TimeFieldProps as AriaTimeFieldProps,
+  DateInput,
+  DateSegment,
+  FieldError,
+  Label,
+  Text,
+  type TimeValue,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  fieldControlStyles,
+  fieldErrorStyles,
+  type FieldSize,
+  fieldHintStyles,
+  fieldLabelStyles,
+} from '../field/field'
+
+export type TimeFieldProps<T extends TimeValue> = AriaTimeFieldProps<T> & {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  /** Field size. Defaults to `md`. */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the box. */
+  appearance?: FieldAppearance
+}
+
+/* Standalone time editor — backs the `time-picker` control (naive `HH:mm:ss`).
+   Just the segmented input: no calendar, no popover. Box chrome + content
+   padding both ride on the DateInput since there's no sibling trigger to share
+   the border with. */
+export function TimeField<T extends TimeValue = TimeValue>({
+  label,
+  description,
+  errorMessage,
+  size,
+  appearance,
+  className,
+  ...props
+}: TimeFieldProps<T>) {
+  const styles = fieldControlStyles({ size, appearance })
+  const focusWithin =
+    appearance === 'cell'
+      ? 'focus-within:border-accent focus-within:shadow-none'
+      : 'focus-within:border-accent focus-within:shadow-[var(--shadow-focus)]'
+  return (
+    <AriaTimeField
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'grid grid-cols-1 gap-1.5',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+
+      <DateInput
+        className={cn(
+          styles.box(),
+          styles.content(),
+          'flex items-center min-w-0 text-ink',
+          // Tabular alignment for time segments — overrides content's
+          // font-sans on purpose.
+          'font-mono',
+          focusWithin,
+        )}
+      >
+        {(segment) => (
+          <DateSegment
+            segment={segment}
+            className={cn(
+              'px-px tabular-nums outline-none select-none',
+              'data-[placeholder]:text-ink-4',
+              'data-[type=literal]:text-ink-4',
+              // segment focus treatment: indigo fill, paper text
+              'data-[focused]:bg-accent data-[focused]:text-[#f0efe8] data-[focused]:rounded-[3px]',
+              'data-[disabled]:cursor-not-allowed',
+            )}
+          />
+        )}
+      </DateInput>
+
+      {description ? (
+        <Text slot="description" className={fieldHintStyles}>
+          {description}
+        </Text>
+      ) : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <FieldError className={fieldErrorStyles}>{errorMessage}</FieldError>
+      ) : null}
+    </AriaTimeField>
+  )
+}

package/src/components/tooltip/index.ts

@@ -0,0 +1,2 @@
+export type { TooltipProps } from './tooltip'
+export { Tooltip, TooltipTrigger } from './tooltip'

package/src/components/tooltip/tooltip.stories.tsx

@@ -0,0 +1,176 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Button } from '@/components/button/button'
+
+import { Tooltip, TooltipTrigger } from './tooltip'
+
+const meta: Meta<typeof TooltipTrigger> = {
+  title: 'Components/Tooltip',
+  component: TooltipTrigger,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    delay: {
+      control: { type: 'number', min: 0, step: 50 },
+      description: 'Hover delay before the tooltip opens (ms). Focus ignores this.',
+    },
+    closeDelay: {
+      control: { type: 'number', min: 0, step: 50 },
+      description: 'Delay after pointer leaves before the tooltip closes (ms).',
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof TooltipTrigger>
+
+const Info = (
+  <svg viewBox="0 0 16 16" fill="none" aria-hidden>
+    <circle cx="8" cy="8" r="6.5" stroke="currentColor" strokeWidth="1.2" />
+    <path d="M8 7.5v4M8 5v0.25" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" />
+  </svg>
+)
+
+export const Basic: Story = {
+  render: () => (
+    <TooltipTrigger>
+      <Button variant="ghost">Read manifesto</Button>
+      <Tooltip>Opens the one-pager on Proteos's design philosophy.</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+export const OnIconButton: Story = {
+  render: () => (
+    <TooltipTrigger>
+      <Button size="icon-md" variant="ghost" aria-label="About">
+        {Info}
+      </Button>
+      <Tooltip>About Proteos</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+export const WithShortcut: Story = {
+  render: () => (
+    <TooltipTrigger>
+      <Button variant="secondary">Compose</Button>
+      <Tooltip>
+        Compose system
+        <span className="ml-2 rounded-[3px] border border-rule bg-surface-2 px-1 py-px text-[10px] text-ink-3">
+          ⌘ ↵
+        </span>
+      </Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+/* =========================================================================
+   Delay presets — hover times to compare against the default (500ms).
+   ========================================================================= */
+
+/** Opens the moment the pointer lands — good for icon buttons where the user
+ *  is already hunting for the label. */
+export const InstantDelay: Story = {
+  args: { delay: 0 },
+  render: (args) => (
+    <TooltipTrigger {...args}>
+      <Button size="icon-md" variant="ghost" aria-label="About">
+        {Info}
+      </Button>
+      <Tooltip>Opens with no delay — try hovering.</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+/** Snappy but not twitchy — the package default. Documented here so you can
+ *  eyeball it against the instant/slow extremes. */
+export const SnappyDelay: Story = {
+  args: { delay: 500 },
+  render: (args) => (
+    <TooltipTrigger {...args}>
+      <Button variant="ghost">Hover me (500 ms)</Button>
+      <Tooltip>Default hover delay — balanced for dense UIs.</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+/** Deliberately slow — mirrors RAC's out-of-the-box 1500ms. Useful when you
+ *  want the tooltip to only show for users who *linger* on the target. */
+export const SlowDelay: Story = {
+  args: { delay: 1500 },
+  render: (args) => (
+    <TooltipTrigger {...args}>
+      <Button variant="ghost">Hover me (1500 ms)</Button>
+      <Tooltip>Slow delay — only shows if you really pause on the target.</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+/* =========================================================================
+   closeDelay in context — a row of adjacent targets. With `closeDelay` above
+   zero, moving between neighbours skips the re-open wait so the tooltips feel
+   like a chained sequence rather than four separate prompts.
+   ========================================================================= */
+
+export const ChainedWithCloseDelay: Story = {
+  args: { delay: 300, closeDelay: 300 },
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: (args) => (
+    <div className="flex items-center gap-1">
+      <TooltipTrigger {...args}>
+        <Button size="icon-md" variant="ghost" aria-label="Filter">
+          {Info}
+        </Button>
+        <Tooltip>Filter</Tooltip>
+      </TooltipTrigger>
+      <TooltipTrigger {...args}>
+        <Button size="icon-md" variant="ghost" aria-label="Group">
+          {Info}
+        </Button>
+        <Tooltip>Group</Tooltip>
+      </TooltipTrigger>
+      <TooltipTrigger {...args}>
+        <Button size="icon-md" variant="ghost" aria-label="Sort">
+          {Info}
+        </Button>
+        <Tooltip>Sort</Tooltip>
+      </TooltipTrigger>
+      <TooltipTrigger {...args}>
+        <Button size="icon-md" variant="ghost" aria-label="Export">
+          {Info}
+        </Button>
+        <Tooltip>Export</Tooltip>
+      </TooltipTrigger>
+    </div>
+  ),
+}
+
+/** Opposite of the chain — each icon forces a fresh delay. Good for sparse
+ *  toolbars where the tooltips aren't meant to read together. */
+export const IsolatedNoCloseDelay: Story = {
+  args: { delay: 300, closeDelay: 0 },
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: (args) => (
+    <div className="flex items-center gap-1">
+      <TooltipTrigger {...args}>
+        <Button size="icon-md" variant="ghost" aria-label="Filter">
+          {Info}
+        </Button>
+        <Tooltip>Filter</Tooltip>
+      </TooltipTrigger>
+      <TooltipTrigger {...args}>
+        <Button size="icon-md" variant="ghost" aria-label="Group">
+          {Info}
+        </Button>
+        <Tooltip>Group</Tooltip>
+      </TooltipTrigger>
+      <TooltipTrigger {...args}>
+        <Button size="icon-md" variant="ghost" aria-label="Sort">
+          {Info}
+        </Button>
+        <Tooltip>Sort</Tooltip>
+      </TooltipTrigger>
+    </div>
+  ),
+}

package/src/components/tooltip/tooltip.test.tsx

@@ -0,0 +1,52 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it } from 'vitest'
+
+import { Button } from '@/components/button/button'
+
+import { Tooltip, TooltipTrigger } from './tooltip'
+
+describe('Tooltip', () => {
+  it('is not visible by default', () => {
+    render(
+      <TooltipTrigger>
+        <Button>Info</Button>
+        <Tooltip>Helpful hint</Tooltip>
+      </TooltipTrigger>,
+    )
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument()
+  })
+
+  it('appears when the trigger receives keyboard focus', async () => {
+    const user = userEvent.setup()
+    render(
+      <TooltipTrigger>
+        <Button>Info</Button>
+        <Tooltip>Helpful hint</Tooltip>
+      </TooltipTrigger>,
+    )
+
+    await user.tab()
+    expect(await screen.findByRole('tooltip')).toHaveTextContent('Helpful hint')
+  })
+
+  it('hides when focus leaves the trigger', async () => {
+    const user = userEvent.setup()
+    render(
+      <>
+        <TooltipTrigger>
+          <Button>Info</Button>
+          <Tooltip>Helpful hint</Tooltip>
+        </TooltipTrigger>
+        <Button>Other</Button>
+      </>,
+    )
+
+    await user.tab()
+    expect(await screen.findByRole('tooltip')).toBeInTheDocument()
+
+    await user.tab()
+    // Tooltip tears down once the trigger loses focus-visible.
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument()
+  })
+})

package/src/components/tooltip/tooltip.tsx

@@ -0,0 +1,56 @@
+import {
+  Tooltip as AriaTooltip,
+  type TooltipProps as AriaTooltipProps,
+  TooltipTrigger as AriaTooltipTrigger,
+  type TooltipTriggerComponentProps,
+} from 'react-aria-components'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Tooltip — small mono label on hover/focus. Composition follows RAC:
+     <TooltipTrigger>
+       <Button>…</Button>     // the hover/focus target
+       <Tooltip>Copy</Tooltip> // the floating label
+     </TooltipTrigger>
+   Use for icon-button labels, truncated text hints, keyboard shortcuts.
+   ========================================================================= */
+
+/** Stateful root. RAC handles hover delay + focus visibility.
+ *
+ *  - `delay` — ms of hover before the tooltip opens. Keyboard focus opens
+ *    instantly regardless. Default **500** (RAC's own default is 1500 which
+ *    feels sluggish for a dense app). Set `0` for instant tooltips.
+ *  - `closeDelay` — ms after the pointer leaves before the tooltip hides.
+ *    Default **0** (close immediately). Raise it if adjacent targets share
+ *    tooltips and you want them to chain without re-waiting.
+ */
+export function TooltipTrigger({
+  delay = 500,
+  closeDelay = 0,
+  ...props
+}: TooltipTriggerComponentProps) {
+  return <AriaTooltipTrigger delay={delay} closeDelay={closeDelay} {...props} />
+}
+
+export type TooltipProps = AriaTooltipProps
+
+export function Tooltip({ className, offset = 6, ...props }: TooltipProps) {
+  return (
+    <AriaTooltip
+      {...props}
+      offset={offset}
+      className={(renderProps) =>
+        cn(
+          'z-50 max-w-xs',
+          'rounded-md border border-rule bg-surface shadow-[var(--shadow-raised)]',
+          'px-2.5 py-1.5',
+          'font-mono text-[11.5px] text-ink-2',
+          'entering:animate-in entering:fade-in-0 entering:slide-in-from-top-1 entering:duration-150',
+          'exiting:animate-out exiting:fade-out-0 exiting:duration-100',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    />
+  )
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+export * from './components/attachment-chip'
+export * from './components/attribute-type-icon'
+export * from './components/avatar'
+export * from './components/avatar-group'
+export * from './components/badge'
+export * from './components/badge-multi-select'
+export * from './components/breadcrumbs'
+export * from './components/button'
+export * from './components/card'
+export * from './components/checkbox'
+export * from './components/combobox'
+export * from './components/command'
+export * from './components/currency-input'
+export * from './components/data-table'
+export * from './components/date-picker'
+export * from './components/date-time-picker'
+export * from './components/empty-state'
+export * from './components/error-animation'
+export * from './components/field'
+export * from './components/file-field'
+export * from './components/file-viewer'
+export * from './components/image-attachment'
+export * from './components/image-lightbox'
+export * from './components/input'
+export * from './components/kbd'
+export * from './components/menu'
+export * from './components/modal'
+export * from './components/multi-select'
+export * from './components/nav'
+export * from './components/popover'
+export * from './components/progress-bar'
+export * from './components/radio-group'
+export * from './components/record-filter'
+export * from './components/segmented-control'
+export * from './components/select'
+export * from './components/separator'
+export * from './components/skeleton'
+export * from './components/success-animation'
+export * from './components/switch'
+export * from './components/table'
+export * from './components/tabs'
+export * from './components/tag-input'
+export * from './components/textarea'
+export * from './components/time-field'
+export * from './components/tooltip'
+
+export { cn } from './lib/cn'

package/src/lib/cn.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}

package/src/lib/commands/discovery-store.test.tsx

@@ -0,0 +1,76 @@
+import { act, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  _getDiscoverySubscriberCount,
+  _resetDiscovery,
+  useDiscoveryActive,
+} from './discovery-store'
+import { _setPlatformForTests } from './platform'
+
+function Probe() {
+  const active = useDiscoveryActive()
+  return <span data-testid="probe">{active ? 'on' : 'off'}</span>
+}
+
+function holdCmdShift() {
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Shift', shiftKey: true }))
+    window.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Meta', shiftKey: true, metaKey: true }),
+    )
+  })
+}
+
+function releaseMeta() {
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent('keyup', { key: 'Meta', shiftKey: true }))
+  })
+}
+
+describe('useDiscoveryActive', () => {
+  beforeEach(() => {
+    _setPlatformForTests('mac')
+    _resetDiscovery()
+  })
+  afterEach(() => {
+    _setPlatformForTests(undefined)
+    _resetDiscovery()
+  })
+
+  it('is false initially', () => {
+    render(<Probe />)
+    expect(screen.getByTestId('probe').textContent).toBe('off')
+  })
+
+  it('flips on when Cmd+Shift are both held', () => {
+    render(<Probe />)
+    holdCmdShift()
+    expect(screen.getByTestId('probe').textContent).toBe('on')
+  })
+
+  it('flips off when one modifier is released', () => {
+    render(<Probe />)
+    holdCmdShift()
+    releaseMeta()
+    expect(screen.getByTestId('probe').textContent).toBe('off')
+  })
+
+  it('keeps a single subscriber per mounted Probe (one listener total at the module level)', () => {
+    const { unmount: u1 } = render(<Probe />)
+    const { unmount: u2 } = render(<Probe />)
+    expect(_getDiscoverySubscriberCount()).toBe(2)
+    u1()
+    u2()
+    expect(_getDiscoverySubscriberCount()).toBe(0)
+  })
+
+  it('resets on blur (alt-tab scenario)', () => {
+    render(<Probe />)
+    holdCmdShift()
+    act(() => {
+      window.dispatchEvent(new Event('blur'))
+    })
+    expect(screen.getByTestId('probe').textContent).toBe('off')
+  })
+})

package/src/lib/commands/discovery-store.ts

@@ -0,0 +1,110 @@
+/* Module-singleton store tracking the Cmd+Shift "discovery hold". One pair
+   of window listeners regardless of how many <Command> wrappers subscribe.
+   Subscribers re-render via useSyncExternalStore when the both-held flag
+   flips. Resyncs from event modifier flags on every key event so it stays
+   accurate even if the browser drops a modifier key event (focus changes,
+   alt-tab, etc.). */
+
+import { useSyncExternalStore } from 'react'
+
+import { getPlatform } from './platform'
+
+type Listener = () => void
+
+let cmdHeld = false
+let shiftHeld = false
+let initialized = false
+const listeners = new Set<Listener>()
+
+function getSnapshot(): boolean {
+  return cmdHeld && shiftHeld
+}
+
+function getServerSnapshot(): boolean {
+  return false
+}
+
+function emit(): void {
+  for (const l of listeners) l()
+}
+
+function sync(cmdNow: boolean, shiftNow: boolean): void {
+  if (cmdNow !== cmdHeld || shiftNow !== shiftHeld) {
+    cmdHeld = cmdNow
+    shiftHeld = shiftNow
+    emit()
+  }
+}
+
+function onKeyDown(e: KeyboardEvent): void {
+  const platform = getPlatform()
+  const cmdFlag = platform === 'mac' ? e.metaKey : e.ctrlKey
+  // For the modifier key itself, trust the event type (the flag lags on press).
+  if (e.key === 'Meta' || e.key === 'Control') {
+    sync(true, e.shiftKey)
+    return
+  }
+  if (e.key === 'Shift') {
+    sync(cmdFlag, true)
+    return
+  }
+  sync(cmdFlag, e.shiftKey)
+}
+
+function onKeyUp(e: KeyboardEvent): void {
+  const platform = getPlatform()
+  const cmdFlag = platform === 'mac' ? e.metaKey : e.ctrlKey
+  if (e.key === 'Meta' || e.key === 'Control') {
+    sync(false, e.shiftKey)
+    return
+  }
+  if (e.key === 'Shift') {
+    sync(cmdFlag, false)
+    return
+  }
+  sync(cmdFlag, e.shiftKey)
+}
+
+function onBlur(): void {
+  // The window lost focus — assume the user released everything. Without
+  // this, holding Cmd+Shift then alt-tabbing would leave us stuck in
+  // discovery mode until the next keydown.
+  sync(false, false)
+}
+
+function ensureInitialized(): void {
+  if (initialized) return
+  if (typeof window === 'undefined') return
+  window.addEventListener('keydown', onKeyDown, { capture: true })
+  window.addEventListener('keyup', onKeyUp, { capture: true })
+  window.addEventListener('blur', onBlur)
+  initialized = true
+}
+
+function subscribe(listener: Listener): () => void {
+  ensureInitialized()
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+export function useDiscoveryActive(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}
+
+// Test-only: number of installed listeners is the number of subscribers.
+// The window-level listeners are installed at most once (initialized flag).
+export function _getDiscoverySubscriberCount(): number {
+  return listeners.size
+}
+
+export function _resetDiscovery(): void {
+  cmdHeld = false
+  shiftHeld = false
+  listeners.clear()
+}
+
+export function _isDiscoveryInitialized(): boolean {
+  return initialized
+}

package/src/lib/commands/index.ts

@@ -0,0 +1,9 @@
+export type { KeyCombo } from './parse-combo'
+export { parseCombo } from './parse-combo'
+export { PROTECTED_COMBOS } from './protected-combos'
+export { isEditableTarget } from './match-event'
+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'