@proteos/ui 0.57.1 → 0.59.0

package/src/components/record-update/index.ts

@@ -0,0 +1,17 @@
+export type {
+  RecordUpdateErrorsProps,
+  RecordUpdateProps,
+  RecordUpdateRowProps,
+  RecordUpdateRowState,
+  RecordUpdateRowVariants,
+} from './record-update'
+export {
+  RecordUpdate,
+  RecordUpdateErrors,
+  RecordUpdateFooter,
+  RecordUpdateRow,
+  RecordUpdateRows,
+  RecordUpdateSummary,
+  recordUpdateRowStyles,
+  recordUpdateStyles,
+} from './record-update'

package/src/components/record-update/record-update.stories.tsx

@@ -0,0 +1,141 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { type ReactNode, useState } from 'react'
+
+import { Badge } from '../badge/badge'
+import { Button } from '../button/button'
+import { Input } from '../input/input'
+import { Select } from '../select/select'
+import {
+  RecordUpdate,
+  RecordUpdateErrors,
+  RecordUpdateFooter,
+  RecordUpdateRow,
+  type RecordUpdateRowState,
+  RecordUpdateRows,
+  RecordUpdateSummary,
+} from './record-update'
+
+const meta: Meta<typeof RecordUpdateRow> = {
+  title: 'Components/RecordUpdate',
+  component: RecordUpdateRow,
+  tags: ['autodocs'],
+  argTypes: {
+    state: { control: 'radio', options: ['changed', 'unresolved', 'rejected', 'removed'] },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof RecordUpdateRow>
+
+const STATUS_OPTIONS = [
+  { id: 'open', label: 'Open' },
+  { id: 'won', label: 'Won' },
+  { id: 'churned', label: 'Churned' },
+] as const
+
+function ReadOnly({ children }: { children: ReactNode }) {
+  return (
+    <div className="flex items-center min-h-9 bg-surface-2 rounded-md px-3 py-2 text-[13.5px] text-ink">
+      {children}
+    </div>
+  )
+}
+
+export const Row: Story = {
+  args: {
+    label: 'Status',
+    from: <ReadOnly>Open</ReadOnly>,
+    to: <ReadOnly>Churned</ReadOnly>,
+    state: 'changed',
+    onRemove: () => {},
+    onRestore: () => {},
+  },
+}
+
+export const Review: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [status, setStatus] = useState('churned')
+    const [amount, setAmount] = useState('13200')
+    const [removed, setRemoved] = useState<Record<string, boolean>>({})
+    const stateFor = (key: string, fallback: RecordUpdateRowState = 'changed') =>
+      removed[key] ? 'removed' : fallback
+    const toggle = (key: string, value: boolean) =>
+      setRemoved((prev) => ({ ...prev, [key]: value }))
+    return (
+      <div className="w-[600px] border border-rule rounded-lg bg-surface">
+        <RecordUpdate>
+          <RecordUpdateSummary>
+            Marks the company as churned and raises the amount by 10%.
+          </RecordUpdateSummary>
+          <RecordUpdateRows>
+            <RecordUpdateRow
+              label="Status"
+              state={stateFor('status')}
+              from={
+                <ReadOnly>
+                  <Badge>Open</Badge>
+                </ReadOnly>
+              }
+              to={
+                <Select
+                  aria-label="Status"
+                  options={STATUS_OPTIONS}
+                  selectedKey={status}
+                  onSelectionChange={(key) => setStatus(String(key))}
+                />
+              }
+              onRemove={() => toggle('status', true)}
+              onRestore={() => toggle('status', false)}
+            />
+            <RecordUpdateRow
+              label="Amount"
+              state={stateFor('amount')}
+              from={<ReadOnly>12,000</ReadOnly>}
+              to={<Input aria-label="Amount" value={amount} onChange={setAmount} />}
+              onRemove={() => toggle('amount', true)}
+              onRestore={() => toggle('amount', false)}
+            />
+            <RecordUpdateRow
+              label="Owner"
+              state={stateFor('owner', 'unresolved')}
+              from={<ReadOnly>Tonio Knuth</ReadOnly>}
+              to={<Input aria-label="Owner" placeholder="Pick a user…" />}
+              hint="“Julia” is a name, not an id — pick the user."
+              onRemove={() => toggle('owner', true)}
+              onRestore={() => toggle('owner', false)}
+            />
+            <RecordUpdateRow
+              label="Tier"
+              state="rejected"
+              from={
+                <ReadOnly>
+                  <Badge>Silver</Badge>
+                </ReadOnly>
+              }
+              to={
+                <span className="text-[13px] text-danger">
+                  “platinum” is not one of the options (silver, gold).
+                </span>
+              }
+            />
+            <RecordUpdateRow
+              label="Website"
+              from={<ReadOnly>—</ReadOnly>}
+              to={<Input aria-label="Website" value="acme" onChange={() => {}} isInvalid />}
+              errorMessage="Must be a valid URL"
+              onRemove={() => {}}
+            />
+          </RecordUpdateRows>
+          <RecordUpdateErrors
+            errors={['“Created at” is managed by the platform and cannot be changed.']}
+          />
+          <RecordUpdateFooter>
+            <Button variant="ghost">Cancel</Button>
+            <Button variant="cta">Apply 2 changes</Button>
+          </RecordUpdateFooter>
+        </RecordUpdate>
+      </div>
+    )
+  },
+}

package/src/components/record-update/record-update.test.tsx

@@ -0,0 +1,114 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  RecordUpdate,
+  RecordUpdateErrors,
+  RecordUpdateRow,
+  RecordUpdateRows,
+  RecordUpdateSummary,
+} from './record-update'
+
+describe('RecordUpdateRow', () => {
+  it('names the group after the label and shows both cells', () => {
+    render(<RecordUpdateRow label="Status" from={<span>Open</span>} to={<span>Won</span>} />)
+    expect(screen.getByRole('group')).toHaveAttribute('data-state', 'changed')
+    expect(screen.getByText('Status')).toBeInTheDocument()
+    expect(screen.getByText('Open')).toBeInTheDocument()
+    expect(screen.getByText('Won')).toBeInTheDocument()
+  })
+
+  it('offers remove while changed and restore once removed', async () => {
+    const user = userEvent.setup()
+    const onRemove = vi.fn()
+    const onRestore = vi.fn()
+    const { rerender } = render(
+      <RecordUpdateRow
+        label="Status"
+        from="Open"
+        to="Won"
+        onRemove={onRemove}
+        onRestore={onRestore}
+      />,
+    )
+    await user.click(screen.getByRole('button', { name: 'Remove change' }))
+    expect(onRemove).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('button', { name: 'Restore change' })).not.toBeInTheDocument()
+
+    rerender(
+      <RecordUpdateRow
+        label="Status"
+        from="Open"
+        to="Won"
+        state="removed"
+        onRemove={onRemove}
+        onRestore={onRestore}
+      />,
+    )
+    expect(screen.queryByText('Won')).not.toBeInTheDocument()
+    expect(screen.getByText('Kept as it is')).toBeInTheDocument()
+    await user.click(screen.getByRole('button', { name: 'Restore change' }))
+    expect(onRestore).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders the proposed value alone when there is no current value', () => {
+    const { container } = render(<RecordUpdateRow label="Name" to={<span>Julia</span>} />)
+    expect(screen.getByText('Julia')).toBeInTheDocument()
+    expect(container.querySelector('svg')).toBeNull()
+  })
+
+  it('tags a rejected row and keeps its cells (the explanation rides in `to`)', () => {
+    render(
+      <RecordUpdateRow
+        label="Created at"
+        from="2026-09-01"
+        to={<span>Read-only field</span>}
+        state="rejected"
+      />,
+    )
+    expect(screen.getByRole('group')).toHaveAttribute('data-state', 'rejected')
+    expect(screen.getByText('not possible')).toBeInTheDocument()
+    expect(screen.getByText('Read-only field')).toBeInTheDocument()
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+
+  it('tags an unresolved row and shows the hint; an error is an alert', () => {
+    render(
+      <RecordUpdateRow
+        label="Owner"
+        from="Tonio"
+        to={<input aria-label="Owner" />}
+        state="unresolved"
+        hint="Pick the user."
+        errorMessage="Required"
+      />,
+    )
+    expect(screen.getByRole('group')).toHaveAttribute('data-state', 'unresolved')
+    expect(screen.getByText('needs a value')).toBeInTheDocument()
+    expect(screen.getByText('Pick the user.')).toBeInTheDocument()
+    expect(screen.getByRole('alert')).toHaveTextContent('Required')
+  })
+})
+
+describe('RecordUpdate', () => {
+  it('composes summary, rows and the general errors alert', () => {
+    render(
+      <RecordUpdate>
+        <RecordUpdateSummary>Two changes.</RecordUpdateSummary>
+        <RecordUpdateRows>
+          <RecordUpdateRow label="Status" from="Open" to="Won" />
+        </RecordUpdateRows>
+        <RecordUpdateErrors errors={['Created at cannot be changed.']} />
+      </RecordUpdate>,
+    )
+    expect(screen.getByText('Two changes.')).toBeInTheDocument()
+    expect(screen.getByRole('group', { name: '' })).toBeInTheDocument()
+    expect(screen.getByRole('alert')).toHaveTextContent('Created at cannot be changed.')
+  })
+
+  it('renders no errors block when the list is empty', () => {
+    render(<RecordUpdateErrors errors={[]} />)
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+})

package/src/components/record-update/record-update.tsx

@@ -0,0 +1,259 @@
+import { AlertCircle, ArrowRight, Undo2, X } from 'lucide-react'
+import type { HTMLAttributes, ReactNode } from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+import { Button } from '../button/button'
+
+/* =========================================================================
+   RecordUpdate — a proposed set of field changes to ONE record, laid out
+   as a mini page: a summary line, one row per field (`from → to`), the
+   problems the proposer ran into, and a footer with the decision buttons.
+   Chrome only — the consumer renders the two cells of every row (a
+   read-only display on the left, an editor on the right), so the same
+   surface reviews an AI-prepared record update in the command palette, in
+   a chat client tool, or in a prepared-action popover.
+
+   Slot composition (Card pattern): the root carries no padding; each slot
+   owns its own spacing so they compose freely.
+
+     <RecordUpdate>
+       <RecordUpdateSummary>…</RecordUpdateSummary>
+       <RecordUpdateRows>
+         <RecordUpdateRow label from to state … />
+       </RecordUpdateRows>
+       <RecordUpdateErrors errors={[…]} />
+       <RecordUpdateFooter>…buttons…</RecordUpdateFooter>
+     </RecordUpdate>
+
+   Row states:
+     changed    — a value the reviewer can still edit or drop.
+     unresolved — the proposer knew WHICH field but not the value; the
+                  right cell is expected to be an empty editor and `hint`
+                  says why. Consumers block "apply" while any row is here.
+     rejected   — the proposer could NOT do what was asked for this field
+                  (read-only, no such option …); the right cell carries the
+                  explanation and nothing is applied for the row.
+     removed    — dropped from the change set; collapses to one line with a
+                  restore button so the decision stays reversible.
+   ========================================================================= */
+
+export const recordUpdateStyles = tv({
+  slots: {
+    root: 'flex flex-col min-w-0 text-ink',
+    summary: 'px-4 pt-3 pb-1 text-[13px] text-ink-3',
+    rows: 'flex flex-col px-4 divide-y divide-rule',
+    errors: [
+      'mx-4 my-3 flex gap-2 rounded-md px-3 py-2 text-[13px] text-danger',
+      'bg-[color-mix(in_oklab,var(--color-danger)_8%,var(--color-surface))]',
+    ],
+    footer: 'flex items-center justify-end gap-2 px-4 py-3',
+  },
+})
+
+export const recordUpdateRowStyles = tv({
+  slots: {
+    // fieldset resets (UA border / padding / min-content width) included.
+    root: 'flex flex-col gap-1.5 m-0 border-0 px-0 py-2.5 min-w-0',
+    labelRow: [
+      'flex items-center gap-2 min-h-7',
+      'font-mono text-[10.5px] uppercase tracking-[0.08em] text-ink-4',
+    ],
+    tag: 'normal-case tracking-normal text-[10px] rounded-full px-1.5 py-px',
+    cells:
+      'grid grid-cols-1 sm:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-2 sm:gap-3',
+    from: 'min-w-0 opacity-70',
+    arrow: 'size-3.5 shrink-0 text-ink-4 rotate-90 sm:rotate-0 justify-self-center',
+    to: 'min-w-0',
+    hint: 'text-[12px] text-ink-4',
+    error: 'text-[12px] text-danger',
+    removed: 'text-[13px] italic text-ink-4',
+  },
+  variants: {
+    state: {
+      changed: {},
+      unresolved: {
+        tag: 'text-warning bg-[color-mix(in_oklab,var(--color-warning)_12%,var(--color-surface))]',
+      },
+      rejected: {
+        tag: 'text-danger bg-[color-mix(in_oklab,var(--color-danger)_10%,var(--color-surface))]',
+      },
+      removed: { labelRow: 'line-through decoration-ink-4/60' },
+    },
+  },
+  defaultVariants: { state: 'changed' },
+})
+
+export type RecordUpdateRowVariants = VariantProps<typeof recordUpdateRowStyles>
+export type RecordUpdateRowState = NonNullable<RecordUpdateRowVariants['state']>
+
+/* ---------- root + slots ---------- */
+
+export type RecordUpdateProps = HTMLAttributes<HTMLDivElement>
+
+export function RecordUpdate({ className, children, ...props }: RecordUpdateProps) {
+  return (
+    <div {...props} className={cn(recordUpdateStyles().root(), className)}>
+      {children}
+    </div>
+  )
+}
+
+export function RecordUpdateSummary({
+  className,
+  children,
+  ...props
+}: HTMLAttributes<HTMLElement>) {
+  return (
+    <p {...props} className={cn(recordUpdateStyles().summary(), className)}>
+      {children}
+    </p>
+  )
+}
+
+export function RecordUpdateRows({
+  className,
+  children,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div {...props} className={cn(recordUpdateStyles().rows(), className)}>
+      {children}
+    </div>
+  )
+}
+
+export interface RecordUpdateErrorsProps extends HTMLAttributes<HTMLDivElement> {
+  /** Problems that are not tied to one field. Renders nothing when empty. */
+  errors: ReadonlyArray<string>
+}
+
+export function RecordUpdateErrors({ errors, className, ...props }: RecordUpdateErrorsProps) {
+  if (errors.length === 0) return null
+  return (
+    <div {...props} role="alert" className={cn(recordUpdateStyles().errors(), className)}>
+      <AlertCircle className="size-4 shrink-0 mt-px" aria-hidden />
+      <ul className="flex flex-col gap-1 min-w-0">
+        {errors.map((error) => (
+          <li key={error}>{error}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+export function RecordUpdateFooter({
+  className,
+  children,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div {...props} className={cn(recordUpdateStyles().footer(), className)}>
+      {children}
+    </div>
+  )
+}
+
+/* ---------- row ---------- */
+
+export interface RecordUpdateRowProps
+  extends Omit<HTMLAttributes<HTMLFieldSetElement>, 'children' | 'className'> {
+  /** The field's label — rendered in the page-layout field-label style. */
+  label: ReactNode
+  /** Current value cell (typically a read-only display). Omit for a value
+   *  that has no "before" — a record being created — and the row shows
+   *  `to` alone, without the arrow. */
+  from?: ReactNode
+  /** Proposed value cell (an editor bound to the change, or the rejection text). */
+  to: ReactNode
+  state?: RecordUpdateRowState
+  /** Why the value is unresolved, or any other one-line note under the cells. */
+  hint?: ReactNode
+  /** Validation error for the proposed value. */
+  errorMessage?: string
+  /** Drop this change. Renders the remove button when given (not in `removed`). */
+  onRemove?: () => void
+  /** Bring a removed change back. Renders the restore button in `removed`. */
+  onRestore?: () => void
+  /** Accessible names for the two buttons. */
+  removeLabel?: string
+  restoreLabel?: string
+  /** Text of the `unresolved` / `rejected` tags next to the label. */
+  unresolvedLabel?: string
+  rejectedLabel?: string
+  /** Text shown in place of the cells while `removed`. */
+  removedText?: string
+  className?: string
+}
+
+export function RecordUpdateRow({
+  label,
+  from,
+  to,
+  state = 'changed',
+  hint,
+  errorMessage,
+  onRemove,
+  onRestore,
+  removeLabel = 'Remove change',
+  restoreLabel = 'Restore change',
+  unresolvedLabel = 'needs a value',
+  rejectedLabel = 'not possible',
+  removedText = 'Kept as it is',
+  className,
+  ...props
+}: RecordUpdateRowProps) {
+  const styles = recordUpdateRowStyles({ state })
+  const isRemoved = state === 'removed'
+  // A fieldset: the row IS a group of one field's cells (implicit `group`
+  // role), reset from the UA's border / padding / min-content width.
+  return (
+    <fieldset
+      {...props}
+      data-state={state}
+      {...(errorMessage ? { 'aria-invalid': true } : {})}
+      className={cn(styles.root(), className)}
+    >
+      <div className={styles.labelRow()}>
+        <span className="truncate">{label}</span>
+        {state === 'unresolved' ? <span className={styles.tag()}>{unresolvedLabel}</span> : null}
+        {state === 'rejected' ? <span className={styles.tag()}>{rejectedLabel}</span> : null}
+        <span className="ml-auto flex items-center">
+          {isRemoved
+            ? onRestore && (
+                <Button
+                  variant="ghost"
+                  size="icon-sm"
+                  aria-label={restoreLabel}
+                  onPress={onRestore}
+                >
+                  <Undo2 />
+                </Button>
+              )
+            : onRemove && (
+                <Button variant="ghost" size="icon-sm" aria-label={removeLabel} onPress={onRemove}>
+                  <X />
+                </Button>
+              )}
+        </span>
+      </div>
+      {isRemoved ? (
+        <div className={styles.removed()}>{removedText}</div>
+      ) : from === undefined ? (
+        <div className={styles.to()}>{to}</div>
+      ) : (
+        <div className={styles.cells()}>
+          <div className={styles.from()}>{from}</div>
+          <ArrowRight className={styles.arrow()} aria-hidden />
+          <div className={styles.to()}>{to}</div>
+        </div>
+      )}
+      {!isRemoved && hint ? <div className={styles.hint()}>{hint}</div> : null}
+      {!isRemoved && errorMessage ? (
+        <div className={styles.error()} role="alert">
+          {errorMessage}
+        </div>
+      ) : null}
+    </fieldset>
+  )
+}

package/src/components/select/select.tsx

@@ -74,7 +74,7 @@ export function Select<T extends Key>({
       {...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/switch/switch.stories.tsx

@@ -12,6 +12,7 @@ const meta: Meta<typeof Switch> = {
   argTypes: {
     isDisabled: { control: { type: 'boolean' } },
     isSelected: { control: { type: 'boolean' } },
+    description: { control: { type: 'text' } },
     labelPlacement: {
       control: { type: 'inline-radio' },
       options: ['start', 'end'],
@@ -45,6 +46,27 @@ export const Row: Story = {
   ),
 }
 
+export const WithDescription: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="grid gap-5 w-[420px]">
+      <Switch description="Asks the decision model first and skips the reasoning call when nothing applies.">
+        Screen with decision model first
+      </Switch>
+      <Switch
+        labelPlacement="start"
+        defaultSelected
+        description="Label first: the copy sits under the label, the track stays on the right."
+      >
+        Live architect
+      </Switch>
+      <Switch isDisabled description="Disabled: label, track and copy all fade together.">
+        Version history
+      </Switch>
+    </div>
+  ),
+}
+
 export const AllStates: Story = {
   parameters: { controls: { hideNoControlsWarning: true } },
   render: () => (

package/src/components/switch/switch.test.tsx

@@ -47,4 +47,10 @@ describe('Switch', () => {
     render(<Switch isSelected>Version history</Switch>)
     expect(screen.getByRole('switch', { name: 'Version history' })).toBeChecked()
   })
+
+  it('exposes a description through aria-describedby without changing the name', () => {
+    render(<Switch description="Off by default.">Live architect</Switch>)
+    const control = screen.getByRole('switch', { name: 'Live architect' })
+    expect(control).toHaveAccessibleDescription('Off by default.')
+  })
 })

package/src/components/switch/switch.tsx

@@ -1,18 +1,37 @@
-import type { ReactNode } from 'react'
+import { type ReactNode, useId } from 'react'
 import { Switch as AriaSwitch, type SwitchProps as AriaSwitchProps } from 'react-aria-components'
 
 import { cn } from '../../lib/cn'
+import { fieldHintStyles } from '../field/field'
 
 export type SwitchProps = Omit<AriaSwitchProps, 'children'> & {
   children?: ReactNode
   /** Render the label before the track instead of after it. */
   labelPlacement?: 'start' | 'end'
+  /**
+   * Helper copy under the label, aligned with it and exposed through
+   * `aria-describedby`. Lives OUTSIDE the label so it never joins the
+   * switch's accessible name. With a description the root becomes a `<div>`
+   * wrapping the label; without one the label stays the root, as before.
+   */
+  description?: ReactNode
 }
 
-export function Switch({ children, labelPlacement = 'end', className, ...props }: SwitchProps) {
-  return (
+export function Switch({
+  children,
+  labelPlacement = 'end',
+  description,
+  className,
+  ...props
+}: SwitchProps) {
+  const descriptionId = useId()
+  const describedBy = [props['aria-describedby'], description ? descriptionId : undefined]
+    .filter(Boolean)
+    .join(' ')
+  const control = (
     <AriaSwitch
       {...props}
+      {...(describedBy ? { 'aria-describedby': describedBy } : {})}
       className={(renderProps) =>
         cn(
           // `relative`: RAC's visually-hidden <input> is absolutely positioned;
@@ -50,4 +69,22 @@ export function Switch({ children, labelPlacement = 'end', className, ...props }
       {children}
     </AriaSwitch>
   )
+  if (!description) return control
+  return (
+    <div className="grid gap-1 content-start">
+      {control}
+      <span
+        id={descriptionId}
+        className={cn(
+          fieldHintStyles,
+          'leading-[1.45]',
+          // Track (38px) + gap-3 (12px): the copy starts under the label text.
+          labelPlacement === 'end' && 'pl-[50px]',
+          props.isDisabled && 'opacity-45',
+        )}
+      >
+        {description}
+      </span>
+    </div>
+  )
 }

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

@@ -142,7 +142,7 @@ export function TagInput({
   }
 
   return (
-    <div className={cn('grid grid-cols-1 gap-1.5', className)}>
+    <div className={cn('grid grid-cols-1 gap-1.5 content-start', className)}>
       {label ? (
         <label htmlFor={inputId} className={fieldLabelStyles}>
           {label}

package/src/components/text-shimmer/index.ts

@@ -0,0 +1,2 @@
+export type { TextShimmerProps, TextShimmerVariants } from './text-shimmer'
+export { TextShimmer, textShimmerStyles } from './text-shimmer'