@proteos/ui 0.31.0

package/src/components/date-time-picker/date-time-picker.test.tsx

@@ -0,0 +1,87 @@
+import { type CalendarDateTime, parseDateTime } from '@internationalized/date'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { DateTimePicker } from './date-time-picker'
+
+// Naive CalendarDateTime keeps the rendered month/day/time independent of the
+// test runner's timezone (unlike a UTC-anchored ZonedDateTime).
+const MAY_4 = '2026-05-04T14:30:00'
+
+describe('DateTimePicker', () => {
+  it('renders a labelled input', () => {
+    render(<DateTimePicker label="Starts at" />)
+    expect(screen.getByText('Starts at')).toBeInTheDocument()
+  })
+
+  it('renders inline time segments alongside the date segments', () => {
+    render(<DateTimePicker label="Starts at" defaultValue={parseDateTime(MAY_4)} />)
+    // Granularity 'minute' (the default) surfaces editable hour + minute
+    // segments in the inline DateInput — this is the in-cell time editor.
+    expect(screen.getByRole('spinbutton', { name: /hour/i })).toBeInTheDocument()
+    expect(screen.getByRole('spinbutton', { name: /minute/i })).toBeInTheDocument()
+  })
+
+  it('opens a popover with both a calendar grid and a Time field', async () => {
+    const user = userEvent.setup()
+    render(<DateTimePicker label="Starts at" defaultValue={parseDateTime(MAY_4)} />)
+
+    // The calendar-glyph trigger is the only <button> in the field (segments
+    // are spinbuttons). When closed it's the last <button> in the DOM.
+    const buttons = screen.getAllByRole('button')
+    const trigger = buttons[buttons.length - 1]
+    if (!trigger) throw new Error('calendar trigger missing')
+
+    await user.click(trigger)
+    expect(await screen.findByRole('application')).toBeInTheDocument()
+    expect(screen.getByRole('grid')).toBeInTheDocument()
+    // The dedicated time editor inside the popover.
+    expect(screen.getByLabelText('Time')).toBeInTheDocument()
+  })
+
+  it('selecting a calendar day fires onChange and preserves the time', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(
+      <DateTimePicker
+        label="Starts at"
+        defaultValue={parseDateTime(MAY_4)}
+        onChange={onChange}
+      />,
+    )
+
+    const buttons = screen.getAllByRole('button')
+    const trigger = buttons[buttons.length - 1]
+    if (!trigger) throw new Error('trigger missing')
+    await user.click(trigger)
+
+    // Pick the 15th in the current (May 2026) grid.
+    const fifteenth = await screen.findByRole('button', { name: /May 15, 2026/i })
+    await user.click(fifteenth)
+
+    expect(onChange).toHaveBeenCalled()
+    const called = onChange.mock.calls.at(-1)?.[0] as CalendarDateTime | null
+    expect(called?.day).toBe(15)
+    expect(called?.month).toBe(5)
+    expect(called?.hour).toBe(14)
+    expect(called?.minute).toBe(30)
+  })
+
+  it('renders the error message when invalid', () => {
+    render(<DateTimePicker label="Starts at" isInvalid errorMessage="Pick a future time." />)
+    expect(screen.getByText('Pick a future time.')).toBeInTheDocument()
+  })
+
+  it('disables the control when isDisabled is set', () => {
+    render(<DateTimePicker label="Starts at" isDisabled defaultValue={parseDateTime(MAY_4)} />)
+    for (const btn of screen.getAllByRole('button')) {
+      expect(btn).toBeDisabled()
+    }
+  })
+
+  it('shows the description slot', () => {
+    render(<DateTimePicker label="Starts at" description="When the shift begins." />)
+    expect(screen.getByText('When the shift begins.')).toBeInTheDocument()
+  })
+})

package/src/components/date-time-picker/date-time-picker.tsx

@@ -0,0 +1,203 @@
+import { type ReactNode, useContext } from 'react'
+import {
+  DatePicker as AriaDatePicker,
+  type DatePickerProps as AriaDatePickerProps,
+  Button as AriaDateTrigger,
+  TimeField as AriaTimeField,
+  DateInput,
+  DatePickerStateContext,
+  DateSegment,
+  type DateValue,
+  Dialog,
+  FieldError,
+  Group,
+  Label,
+  Popover,
+  Text,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  fieldControlStyles,
+  fieldErrorStyles,
+  type FieldSize,
+  fieldHintStyles,
+  fieldLabelStyles,
+} from '../field/field'
+import { CalendarGlyph, CalendarSurface } from '../date-picker/calendar-internals'
+
+export type DateTimePickerProps<T extends DateValue> = AriaDatePickerProps<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
+}
+
+/* Shared segment treatment for the inline DateInput + the popover TimeField,
+   so the two never drift. Matches DatePicker's date segments. */
+const segmentStyles = 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',
+)
+
+/* The popover's dedicated time editor. Reads the live DatePicker state so it
+   stays in sync with both the inline segments and the calendar selection:
+   `state.timeValue` / `state.setTimeValue` are RAC's split-out time portion of
+   the combined value. Renders nothing until the picker actually has a time
+   component (`hasTime` — i.e. granularity is finer than 'day'). */
+function PopoverTimeField({
+  granularity,
+  hourCycle,
+  hideTimeZone,
+}: {
+  granularity: 'hour' | 'minute' | 'second'
+  hourCycle?: 12 | 24
+  hideTimeZone?: boolean
+}) {
+  const state = useContext(DatePickerStateContext)
+  if (!state?.hasTime) return null
+  return (
+    <div className="mt-3 pt-3 border-t border-rule flex items-center justify-between gap-3">
+      <span className={fieldLabelStyles}>Time</span>
+      <AriaTimeField
+        aria-label="Time"
+        value={state.timeValue}
+        onChange={(next) => {
+          if (next) state.setTimeValue(next)
+        }}
+        granularity={granularity}
+        {...(hourCycle !== undefined ? { hourCycle } : {})}
+        {...(hideTimeZone !== undefined ? { hideTimeZone } : {})}
+      >
+        <DateInput
+          className={cn(
+            'inline-flex items-center rounded-md border border-rule bg-surface px-2.5 py-1.5',
+            'font-mono text-[13px] text-ink',
+            'focus-within:border-accent focus-within:shadow-[var(--shadow-focus)]',
+            'transition-[border-color,box-shadow] duration-150',
+          )}
+        >
+          {(segment) => <DateSegment segment={segment} className={segmentStyles} />}
+        </DateInput>
+      </AriaTimeField>
+    </div>
+  )
+}
+
+export function DateTimePicker<T extends DateValue>({
+  label,
+  description,
+  errorMessage,
+  size,
+  appearance,
+  className,
+  // Time-aware defaults: minute precision, locale hour cycle, no timezone
+  // segment, and keep the popover open after a calendar day-click so the user
+  // can still set a time.
+  granularity = 'minute',
+  hideTimeZone = true,
+  shouldCloseOnSelect = false,
+  ...props
+}: DateTimePickerProps<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)]'
+  // `granularity` is never 'day' here (defaulted to 'minute'); narrow for the
+  // TimeField, which only accepts hour/minute/second.
+  const timeGranularity = granularity === 'day' ? 'minute' : granularity
+  const { hourCycle } = props
+  return (
+    <AriaDatePicker
+      {...props}
+      granularity={granularity}
+      hideTimeZone={hideTimeZone}
+      shouldCloseOnSelect={shouldCloseOnSelect}
+      className={(renderProps) =>
+        cn(
+          'grid grid-cols-1 gap-1.5',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+
+      <Group
+        className={cn(
+          // Box chrome on the wrapper; the DateInput inside carries padding +
+          // font so the calendar trigger sits inside the same border + ring.
+          styles.box(),
+          'flex items-center gap-1 pr-1',
+          focusWithin,
+        )}
+      >
+        <DateInput
+          className={cn(
+            'flex-1 flex items-center min-w-0 text-ink',
+            styles.content(),
+            // Tabular alignment for date/time segments — overrides content's
+            // font-sans on purpose.
+            'font-mono',
+          )}
+        >
+          {(segment) => <DateSegment segment={segment} className={segmentStyles} />}
+        </DateInput>
+
+        <AriaDateTrigger
+          className={cn(
+            'shrink-0 inline-flex items-center justify-center',
+            'size-7 rounded-md',
+            'text-ink-3 hover:text-ink hover:bg-surface-2',
+            'outline-none cursor-pointer',
+            'focus-visible:shadow-[var(--shadow-focus)]',
+            'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+          )}
+        >
+          <CalendarGlyph />
+        </AriaDateTrigger>
+      </Group>
+
+      {description ? (
+        <Text slot="description" className={fieldHintStyles}>
+          {description}
+        </Text>
+      ) : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <FieldError className={fieldErrorStyles}>{errorMessage}</FieldError>
+      ) : null}
+
+      <Popover
+        offset={6}
+        className={cn(
+          // Match the anchoring field's width exactly. `--trigger-width` is
+          // set by RAC on the Popover when it's inside a DatePicker. Floor at
+          // 18rem so the calendar stays legible when the input is unusually
+          // narrow, and cap at 500px so it doesn't sprawl behind a very wide
+          // field.
+          'w-[var(--trigger-width)] min-w-[18rem] max-w-[500px]',
+          'rounded-md border border-rule bg-surface p-4',
+          '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',
+        )}
+      >
+        <Dialog className="outline-none">
+          <CalendarSurface />
+          <PopoverTimeField
+            granularity={timeGranularity}
+            hideTimeZone={hideTimeZone}
+            {...(hourCycle !== undefined ? { hourCycle } : {})}
+          />
+        </Dialog>
+      </Popover>
+    </AriaDatePicker>
+  )
+}

package/src/components/date-time-picker/index.ts

@@ -0,0 +1,2 @@
+export type { DateTimePickerProps } from './date-time-picker'
+export { DateTimePicker } from './date-time-picker'

package/src/components/empty-state/empty-state.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   EmptyState — zero-state callout. Centred art tile + title + description
+   + optional action. Used by the page-designer inspector's "Nothing
+   selected" panel and re-usable wherever a panel needs a friendly empty
+   state. Plan §7.2.
+   ========================================================================= */
+
+export const emptyStateStyles = tv({
+  slots: {
+    root: 'flex flex-col items-center text-center px-6',
+    art: 'inline-grid place-items-center rounded-[12px] bg-surface-2 text-ink-3 mb-3',
+    title: 'text-[14px] text-ink font-medium mb-1',
+    description: 'text-[12.5px] text-ink-3 leading-[1.5] max-w-[220px] mx-auto',
+    actions: 'mt-3',
+  },
+  variants: {
+    size: {
+      sm: {
+        root: 'py-6',
+        art: 'size-9',
+      },
+      md: {
+        root: 'py-9',
+        art: 'size-12',
+      },
+    },
+  },
+  defaultVariants: { size: 'md' },
+})
+
+export type EmptyStateVariants = VariantProps<typeof emptyStateStyles>
+
+export interface EmptyStateProps extends EmptyStateVariants {
+  icon?: ReactNode
+  title: ReactNode
+  description?: ReactNode
+  action?: ReactNode
+  className?: string
+}
+
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  size,
+  className,
+}: EmptyStateProps) {
+  const styles = emptyStateStyles({ size })
+  return (
+    <div className={cn(styles.root(), className)}>
+      {icon ? <div className={styles.art()}>{icon}</div> : null}
+      <div className={styles.title()}>{title}</div>
+      {description ? <div className={styles.description()}>{description}</div> : null}
+      {action ? <div className={styles.actions()}>{action}</div> : null}
+    </div>
+  )
+}

package/src/components/empty-state/index.ts

@@ -0,0 +1,2 @@
+export type { EmptyStateProps, EmptyStateVariants } from './empty-state'
+export { EmptyState, emptyStateStyles } from './empty-state'

package/src/components/error-animation/error-animation.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { Button } from '../button/button'
+
+import { ErrorAnimation } from './error-animation'
+
+const meta: Meta<typeof ErrorAnimation> = {
+  title: 'Components/ErrorAnimation',
+  component: ErrorAnimation,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof ErrorAnimation>
+
+export const Playground: Story = {
+  render: (args) => (
+    <div className="size-32">
+      <ErrorAnimation {...args} />
+    </div>
+  ),
+}
+
+export const Sizes: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="flex items-end gap-6">
+      <ErrorAnimation className="size-16" />
+      <ErrorAnimation className="size-24" />
+      <ErrorAnimation className="size-40" />
+    </div>
+  ),
+}
+
+// Replay demo — remount the component to restart the one-shot animation.
+export const Replay: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [key, setKey] = useState(0)
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <ErrorAnimation key={key} className="size-32" />
+        <Button size="sm" variant="ghost" onPress={() => setKey((k) => k + 1)}>
+          Replay
+        </Button>
+      </div>
+    )
+  },
+}

package/src/components/error-animation/error-animation.test.tsx

@@ -0,0 +1,22 @@
+import { render } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { ErrorAnimation } from './error-animation'
+
+describe('ErrorAnimation', () => {
+  it('renders a decorative wrapper with default sizing and the danger color', () => {
+    const { container } = render(<ErrorAnimation />)
+    const wrapper = container.firstElementChild as HTMLElement | null
+    expect(wrapper).not.toBeNull()
+    expect(wrapper).toHaveAttribute('aria-hidden')
+    expect(wrapper?.className).toContain('size-24')
+    expect(wrapper?.className).toContain('text-danger')
+    expect(wrapper?.querySelector('svg')).not.toBeNull()
+  })
+
+  it('forwards className to override the default size', () => {
+    const { container } = render(<ErrorAnimation className="size-40" />)
+    const wrapper = container.firstElementChild as HTMLElement | null
+    expect(wrapper?.className).toContain('size-40')
+  })
+})

package/src/components/error-animation/error-animation.tsx

@@ -0,0 +1,26 @@
+import { CircleX } from 'lucide-react'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   ErrorAnimation — failure indicator: a large red X in a circle (token
+   `--color-danger`), entering with the one-shot status-pop scale+fade
+   (suppressed under prefers-reduced-motion). Decorative: rendered with
+   `aria-hidden`, since the surrounding text region carries the
+   announcement. Size via className (default 96×96).
+   ========================================================================= */
+
+export type ErrorAnimationProps = {
+  className?: string
+}
+
+export function ErrorAnimation({ className }: ErrorAnimationProps) {
+  return (
+    <div
+      aria-hidden
+      className={cn('size-24 text-danger motion-safe:animate-status-pop', className)}
+    >
+      <CircleX className="size-full" strokeWidth={1.5} />
+    </div>
+  )
+}

package/src/components/error-animation/index.ts

@@ -0,0 +1,2 @@
+export type { ErrorAnimationProps } from './error-animation'
+export { ErrorAnimation } from './error-animation'

package/src/components/field/field.tsx

@@ -0,0 +1,142 @@
+import { tv, type VariantProps } from 'tailwind-variants'
+
+/* =========================================================================
+   Shared field chrome — one source of truth for the hairline box that wraps
+   Input, SelectTrigger, ComboboxInput, DatePicker, BadgeMultiSelect, etc.
+
+   Two slots:
+     - `box`     — border + radius + bg + shadow + hover/focus/invalid/disabled.
+                   The "field-ness" of the control. No padding, no font, no
+                   text-size, so it can sit on either a single-element control
+                   OR an outer wrapper of a compound control without dictating
+                   internal spacing.
+     - `content` — font + leading + placeholder color + padding + text-size.
+                   The "interior" of the field. Applied to the box itself for
+                   single-element controls (Input, Textarea, Select trigger),
+                   or to the inner editable element of compound controls
+                   (Combobox <input>, DatePicker <DateInput>) so the box can
+                   host a flex layout with siblings (chevron, calendar
+                   trigger) sharing the border + focus ring.
+
+   `size` is the only knob that defines what "compact" vs "comfortable" means
+   for any field-like control in the library. Change it here, every consumer
+   shifts in lockstep.
+   ========================================================================= */
+
+export const fieldControlStyles = tv({
+  slots: {
+    box: [
+      'w-full rounded-md border bg-surface text-ink',
+      'outline-none shadow-[var(--shadow-inset)]',
+      'transition-[border-color,box-shadow] duration-150',
+      'hover:border-ink-4',
+      'focus:border-accent focus:shadow-[var(--shadow-focus)]',
+      // RAC forwards data-focused/data-hovered/data-invalid on its components.
+      // Keep both CSS :focus and RAC data-* states covered.
+      'data-[hovered]:border-ink-4',
+      'data-[focused]:border-accent data-[focused]:shadow-[var(--shadow-focus)]',
+      'data-[invalid]:border-danger data-[invalid]:shadow-[var(--shadow-focus-danger)]',
+      'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+    ],
+    content: 'font-sans leading-snug placeholder:text-ink-4',
+  },
+  variants: {
+    size: {
+      sm: { content: 'px-2.5 py-1.5 text-[13px]' },
+      md: { content: 'px-3.5 py-2.5 text-[15px]' },
+    },
+    invalid: {
+      true: { box: 'border-danger shadow-[var(--shadow-focus-danger)]' },
+      false: { box: 'border-rule-strong' },
+    },
+    /* `cell` — flat, spreadsheet-style chrome for inline table editing
+       (LUM-35). Squares the corners to 2px and removes BOTH the resting
+       inset shadow and the focus/invalid halo, leaving just a border that
+       turns accent on focus / danger on invalid. Declared after `invalid`
+       so its `shadow-none` wins the tailwind-merge order over the invalid
+       variant's danger halo; the compoundVariant below is belt-and-braces. */
+    appearance: {
+      field: {},
+      cell: {
+        // Fixed 29px editor: sits under the 32px table row so the cell's
+        // items-center leaves a hairline gap top/bottom and the border reads
+        // fully instead of merging with the row gridline. Explicit height is
+        // more deterministic than relying on line-height + padding math.
+        // `py-1` keeps the content box (≈19px) above the ~18px text line so
+        // nothing clips. Both win over `size`'s values via tailwind-merge
+        // order (appearance is declared after size).
+        box: 'h-[29px] rounded-[4px] shadow-none focus:shadow-none data-[focused]:shadow-none data-[invalid]:shadow-none',
+        content: 'py-1',
+      },
+    },
+  },
+  compoundVariants: [
+    { appearance: 'cell', invalid: true, class: { box: 'shadow-none' } },
+  ],
+  defaultVariants: { size: 'md', invalid: false, appearance: 'field' },
+})
+
+export type FieldControlVariants = VariantProps<typeof fieldControlStyles>
+export type FieldSize = NonNullable<FieldControlVariants['size']>
+export type FieldAppearance = NonNullable<FieldControlVariants['appearance']>
+
+/* =========================================================================
+   Per-size lookups — for parts of compound controls that need *just* the
+   text-size or a coherent min-height (e.g. BadgeMultiSelect/MultiSelect's
+   chip wrapper, where the box has its own padding for the chip layout but
+   the placeholder line + overall height should still scale with `size`).
+   ========================================================================= */
+
+export const fieldTextStyles: Record<FieldSize, string> = {
+  sm: 'text-[13px]',
+  md: 'text-[15px]',
+}
+
+export const fieldMinHeight: Record<FieldSize, string> = {
+  sm: 'min-h-[32px]',
+  md: 'min-h-[42px]',
+}
+
+/* =========================================================================
+   Padding for chip-wrapper field controls (BadgeMultiSelect, MultiSelect,
+   TagInput) — these don't use `content`'s padding because the box hosts a
+   flex layout of chips. The padding still has to scale with `size` so the
+   total rendered height (wrapper-pad + chip-height) lines up with a
+   single-element field at the same size.
+   ========================================================================= */
+
+export const fieldChipPadding: Record<FieldSize, string> = {
+  sm: 'p-1',
+  md: 'p-1.5',
+}
+
+/* =========================================================================
+   Label / hint / error text styles — applied to RAC's Label / Text / FieldError
+   components inside each form control. Strings rather than components so the
+   existing monolithic APIs can keep their inline composition.
+   ========================================================================= */
+
+export const fieldLabelStyles = 'font-mono text-[11px] uppercase tracking-[0.08em] text-ink-4'
+
+export const fieldHintStyles = 'font-mono text-[11px] text-ink-4'
+
+export const fieldErrorStyles = 'font-mono text-[11px] text-danger'
+
+/* =========================================================================
+   FieldCaret — the small down-chevron used in Select and Combobox triggers.
+   Decorative; consumer elements carry their own aria semantics.
+   ========================================================================= */
+
+export function FieldCaret() {
+  return (
+    <svg aria-hidden viewBox="0 0 10 10" className="size-2.5 shrink-0 text-ink-3" fill="none">
+      <path
+        d="M2 4l3 3 3-3"
+        stroke="currentColor"
+        strokeWidth="1.2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}

package/src/components/field/index.ts

@@ -0,0 +1,8 @@
+export type { FieldAppearance, FieldControlVariants, FieldSize } from './field'
+export {
+  FieldCaret,
+  fieldControlStyles,
+  fieldErrorStyles,
+  fieldHintStyles,
+  fieldLabelStyles,
+} from './field'