@proteos/ui 0.61.0 → 0.76.0

package/src/components/glow-frame/glow-frame.test.tsx

@@ -0,0 +1,67 @@
+import { act, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { GlowFrame, type GlowFrameStatus } from './glow-frame'
+
+function frame(status: GlowFrameStatus) {
+  return (
+    <GlowFrame status={status}>
+      <p>Output</p>
+    </GlowFrame>
+  )
+}
+
+const beams = () => document.querySelector('[data-glow="beams"]')
+const flash = () => document.querySelector('[data-glow="flash"]')
+
+describe('GlowFrame', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('renders its children', () => {
+    render(frame('idle'))
+    expect(screen.getByText('Output')).toBeInTheDocument()
+  })
+
+  it('shows the beams while working and stops them after the fade', () => {
+    const { rerender } = render(frame('working'))
+    expect(beams()).not.toBeNull()
+
+    rerender(frame('idle'))
+    expect(beams()).not.toBeNull()
+    act(() => vi.advanceTimersByTime(800))
+    expect(beams()).toBeNull()
+  })
+
+  it('flashes once when the output lands', () => {
+    const { rerender } = render(frame('working'))
+    expect(flash()).toBeNull()
+
+    rerender(frame('ready'))
+    expect(flash()).not.toBeNull()
+    act(() => vi.advanceTimersByTime(900))
+    expect(flash()).toBeNull()
+  })
+
+  it('does not flash when mounted with the output already there', () => {
+    render(frame('ready'))
+    expect(flash()).toBeNull()
+    expect(beams()).toBeNull()
+  })
+
+  it('does not flash when the work ends without output', () => {
+    const { rerender } = render(frame('working'))
+    rerender(frame('idle'))
+    expect(flash()).toBeNull()
+  })
+
+  it('flashes again for a second run', () => {
+    const { rerender } = render(frame('working'))
+    rerender(frame('ready'))
+    act(() => vi.advanceTimersByTime(900))
+    rerender(frame('working'))
+    expect(beams()).not.toBeNull()
+    rerender(frame('ready'))
+    expect(flash()).not.toBeNull()
+  })
+})

package/src/components/glow-frame/glow-frame.tsx

@@ -0,0 +1,182 @@
+import { type ReactNode, type RefObject, useEffect, useRef, useState } from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   GlowFrame — the light round a model's output. Wrap the box the output
+   appears in and drive `status`:
+
+   - `working`  beams travel the box's edge while the model works.
+   - leaving `working`, the beams fade out (FADE_MS) and stop painting.
+   - `working` → `ready` plays one flash: a short burst of colour inside the
+     edge, the "here it is". Mounting straight into `ready` (a remount, a tab
+     switch) plays nothing, nor does `working` → `idle` (error, cancel).
+
+   Give it the box's radius (`rounded-*`) via `className`; both layers
+   inherit it. The frame spills 4px of fading light round the box (the
+   `.glow-room` in styles.css) — leave that much room before any overflow
+   clip, or accept that the outer spill is cut. Styles: styles.css, GlowFrame.
+   ========================================================================= */
+
+/** `room` spans the 4px of fading light round the box; `frame` is the box's
+ *  own outline, the one the beams ride and the flash fills. The light itself
+ *  is the `.glow-*` CSS in styles.css. */
+export const glowFrameStyles = tv({
+  slots: {
+    room: 'glow-room flex min-h-0 flex-col',
+    frame: 'glow-frame flex min-h-0 flex-1 flex-col',
+  },
+})
+
+export type GlowFrameVariants = VariantProps<typeof glowFrameStyles>
+
+export type GlowFrameStatus = 'idle' | 'working' | 'ready'
+
+export type GlowFrameProps = {
+  status: GlowFrameStatus
+  className?: string
+  children?: ReactNode
+}
+
+/** How long the beams take to fade in / out, in ms. */
+const FADE_MS = 700
+/** One flash, in ms (matches `glow-flash` in styles.css). */
+const FLASH_MS = 900
+/** How often the flash's colours get new places round the edge, in ms. */
+const REROLL_MS = 250
+const HUES = [1, 2, 3, 4, 5, 6] as const
+
+export function GlowFrame({ status, className, children }: GlowFrameProps) {
+  const isWorking = status === 'working'
+  const { run, isResting } = useBeams(isWorking)
+  const flash = useFlash(status)
+  const strokesRef = useReroll(flash)
+  const styles = glowFrameStyles()
+
+  return (
+    <div className={cn(styles.room(), className)}>
+      <div
+        className={styles.frame()}
+        data-status={status}
+        data-working={isWorking ? 'true' : 'false'}
+        data-flashing={flash !== 0 ? 'true' : 'false'}
+      >
+        {children}
+        {isResting ? null : (
+          <div key={`beams-${run}`} className="glow-fx" aria-hidden="true" data-glow="beams">
+            <div className="glow-orb">
+              <div className="glow-dot glow-a" />
+            </div>
+            <div className="glow-orb">
+              <div className="glow-dot glow-b" />
+            </div>
+            <div className="glow-beams">
+              <div className="glow-blob glow-tail glow-a" />
+              <div className="glow-blob glow-lead glow-a" />
+              <div className="glow-blob glow-tail glow-b" />
+              <div className="glow-blob glow-lead glow-b" />
+            </div>
+          </div>
+        )}
+        {flash !== 0 ? (
+          <div
+            key={`flash-${flash}`}
+            ref={strokesRef}
+            className="glow-flash"
+            aria-hidden="true"
+            data-glow="flash"
+          >
+            <div className="glow-ring glow-ring-1" />
+            <div className="glow-stroke glow-stroke-2">
+              <div className="glow-ring glow-ring-2" />
+            </div>
+            <div className="glow-stroke glow-stroke-3">
+              <div className="glow-ring glow-ring-3" />
+            </div>
+            <div className="glow-stroke glow-stroke-4">
+              <div className="glow-ring glow-ring-4" />
+            </div>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+/** The beams' lifecycle: mounted while working; once off they fade for
+ *  FADE_MS, then `isResting` stops them painting. Each new start bumps `run`,
+ *  which keys the layer so the entrance plays again. */
+function useBeams(isWorking: boolean): { run: number; isResting: boolean } {
+  const [run, setRun] = useState(0)
+  const [isResting, setIsResting] = useState(!isWorking)
+  const wasWorking = useRef(isWorking)
+
+  useEffect(() => {
+    if (isWorking) {
+      if (!wasWorking.current) setRun((n) => n + 1)
+      wasWorking.current = true
+      setIsResting(false)
+      return
+    }
+    wasWorking.current = false
+    const timer = window.setTimeout(() => setIsResting(true), FADE_MS + 50)
+    return () => window.clearTimeout(timer)
+  }, [isWorking])
+
+  return { run, isResting }
+}
+
+/** The flash being played (a counter, so a second working → ready replays
+ *  it), 0 while dark. Only a working → ready seen by this instance lights it. */
+function useFlash(status: GlowFrameStatus): number {
+  const [flash, setFlash] = useState(0)
+  const previous = useRef(status)
+
+  useEffect(() => {
+    const was = previous.current
+    previous.current = status
+    if (!(was === 'working' && status === 'ready')) return
+    setFlash((n) => n + 1)
+  }, [status])
+
+  useEffect(() => {
+    if (flash === 0) return
+    const timer = window.setTimeout(() => setFlash(0), FLASH_MS)
+    return () => window.clearTimeout(timer)
+  }, [flash])
+
+  return flash
+}
+
+/** While a flash plays (and motion is allowed), gives the six hues new
+ *  random places round the edge every REROLL_MS by writing the targets onto
+ *  the rings; their CSS transitions carry each ring there at its own pace. */
+function useReroll(flash: number): RefObject<HTMLDivElement | null> {
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (flash === 0) return
+    if (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return
+    const reroll = () => {
+      const rings = ref.current?.querySelectorAll<HTMLElement>('.glow-ring')
+      if (!rings) return
+      // Random places ARE the animation: each hue somewhere round the edge,
+      // sorted by place they become the gradient's six stops.
+      const stops = HUES.map((hue) => ({ hue, at: Math.random() * 100 })).sort(
+        (a, b) => a.at - b.at,
+      )
+      for (const ring of rings) {
+        stops.forEach((stop, i) => {
+          ring.style.setProperty(`--glow-p${i + 1}`, `${stop.at.toFixed(2)}%`)
+          ring.style.setProperty(`--glow-k${i + 1}`, `var(--color-glow-${stop.hue})`)
+        })
+      }
+    }
+    reroll()
+    const timer = window.setInterval(reroll, REROLL_MS)
+    return () => window.clearInterval(timer)
+  }, [flash])
+
+  return ref
+}

package/src/components/glow-frame/index.ts

@@ -0,0 +1,2 @@
+export type { GlowFrameProps, GlowFrameStatus, GlowFrameVariants } from './glow-frame'
+export { GlowFrame, glowFrameStyles } from './glow-frame'

package/src/components/stepper/index.ts

@@ -0,0 +1,8 @@
+export type {
+  StepperOrientation,
+  StepperProps,
+  StepperStepProps,
+  StepperVariants,
+  StepState,
+} from './stepper'
+export { Stepper, StepperStep, stepperStyles } from './stepper'

package/src/components/stepper/stepper.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Route } from 'lucide-react'
+import { useState } from 'react'
+
+import { Stepper, StepperStep, type StepState } from './stepper'
+
+const meta: Meta<typeof Stepper> = {
+  title: 'Components/Stepper',
+  component: Stepper,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Stepper>
+
+const STEPS = ['Definition', 'Sourcing', 'Audience review', 'Journey building', 'Schedule', 'Run']
+
+function stateAt(index: number, current: number): StepState {
+  if (index < current) return 'completed'
+  if (index === current) return 'current'
+  return 'upcoming'
+}
+
+/* Current step in the middle: completed ones carry a check, the current one
+   is filled, the rest are outlined. */
+export const Default: Story = {
+  render: () => (
+    <Stepper aria-label="Campaign setup">
+      {STEPS.map((label, i) => (
+        <StepperStep key={label} index={i} state={stateAt(i, 3)} isLast={i === STEPS.length - 1}>
+          {label}
+        </StepperStep>
+      ))}
+    </Stepper>
+  ),
+}
+
+/* Clicking a step selects it for viewing without moving the current one —
+   the page renderer's preview behaviour. */
+export const Preview: Story = {
+  render: function PreviewStory() {
+    const current = 2
+    const [selected, setSelected] = useState(current)
+    return (
+      <div className="flex flex-col gap-4">
+        <Stepper aria-label="Campaign setup">
+          {STEPS.map((label, i) => (
+            <StepperStep
+              key={label}
+              index={i}
+              state={stateAt(i, current)}
+              isSelected={i === selected}
+              isLast={i === STEPS.length - 1}
+              onPress={() => setSelected(i)}
+            >
+              {label}
+            </StepperStep>
+          ))}
+        </Stepper>
+        <div className="text-[13px] text-ink-3">
+          Viewing <span className="text-ink">{STEPS[selected]}</span>; current step is{' '}
+          <span className="text-ink">{STEPS[current]}</span>.
+        </div>
+      </div>
+    )
+  },
+}
+
+/* An icon replaces the number on upcoming / current markers. */
+export const WithIcons: Story = {
+  render: () => (
+    <Stepper aria-label="Campaign setup">
+      <StepperStep index={0} state="completed">
+        Definition
+      </StepperStep>
+      <StepperStep index={1} state="current" icon={<Route />}>
+        Journey building
+      </StepperStep>
+      <StepperStep index={2} state="upcoming" icon={<Route />} isLast>
+        Run
+      </StepperStep>
+    </Stepper>
+  ),
+}

package/src/components/stepper/stepper.test.tsx

@@ -0,0 +1,79 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Stepper, StepperStep } from './stepper'
+
+function renderRail(onPress?: (index: number) => void) {
+  return render(
+    <Stepper aria-label="Setup">
+      <StepperStep index={0} state="completed" onPress={() => onPress?.(0)}>
+        Define
+      </StepperStep>
+      <StepperStep index={1} state="current" onPress={() => onPress?.(1)}>
+        Source
+      </StepperStep>
+      <StepperStep index={2} state="upcoming" isLast onPress={() => onPress?.(2)}>
+        Run
+      </StepperStep>
+    </Stepper>,
+  )
+}
+
+describe('Stepper', () => {
+  it('is an ordered list of buttons', () => {
+    renderRail()
+    expect(screen.getByRole('list', { name: 'Setup' })).toBeInTheDocument()
+    expect(screen.getAllByRole('listitem')).toHaveLength(3)
+    expect(screen.getAllByRole('button').map((b) => b.textContent)).toEqual([
+      'Define',
+      '2Source',
+      '3Run',
+    ])
+  })
+
+  it('marks only the current step with aria-current="step"', () => {
+    renderRail()
+    const items = screen.getAllByRole('listitem')
+    expect(items[0]).not.toHaveAttribute('aria-current')
+    expect(items[1]).toHaveAttribute('aria-current', 'step')
+    expect(items[2]).not.toHaveAttribute('aria-current')
+  })
+
+  it('reports presses per step', async () => {
+    const onPress = vi.fn()
+    renderRail(onPress)
+    await userEvent.click(screen.getByRole('button', { name: 'Run' }))
+    expect(onPress).toHaveBeenCalledWith(2)
+  })
+
+  it('shows an icon instead of the number on a step that is not completed', () => {
+    render(
+      <Stepper>
+        <StepperStep index={0} state="upcoming" icon={<svg data-testid="step-icon" />} isLast>
+          Run
+        </StepperStep>
+      </Stepper>,
+    )
+    expect(screen.getByTestId('step-icon')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Run' }).textContent).toBe('Run')
+  })
+
+  it('stacks vertically on request, with connectors between the steps', () => {
+    const { container } = render(
+      <Stepper aria-label="Wrap-up" orientation="vertical">
+        <StepperStep index={0} state="completed" orientation="vertical" isDisabled>
+          Transcript
+        </StepperStep>
+        <StepperStep index={1} state="current" orientation="vertical" isLast isDisabled>
+          Summary
+        </StepperStep>
+      </Stepper>,
+    )
+    expect(screen.getByRole('list', { name: 'Wrap-up' })).toBeInTheDocument()
+    expect(screen.getAllByRole('listitem')).toHaveLength(2)
+    // One connector between two steps (the last step draws none).
+    expect(container.querySelectorAll('li > span[aria-hidden]').length).toBe(1)
+    expect(screen.getByRole('button', { name: 'Transcript' })).toBeDisabled()
+  })
+})

package/src/components/stepper/stepper.tsx

@@ -0,0 +1,127 @@
+import { Check } from 'lucide-react'
+import type { HTMLAttributes, ReactNode } from 'react'
+import { Button as AriaButton, type ButtonProps as AriaButtonProps } from 'react-aria-components'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Stepper — an ordered rail of steps: a numbered marker per step, a check
+   on the completed ones, the current one marked (`aria-current="step"`),
+   connectors in between. Chrome only — which step is current, and what a
+   click does, is the consumer's business (the page renderer's `stepper`
+   element previews a step on click; a wizard would navigate).
+
+   `<Stepper>` is the `<ol>`; each `<StepperStep>` is an `<li>` wrapping a
+   RAC Button so steps are keyboard-reachable and announce their state.
+   `orientation="vertical"` stacks the steps with a short vertical connector
+   under each marker (a progress checklist, a wizard's side rail).
+   ========================================================================= */
+
+export const stepperStyles = tv({
+  slots: {
+    root: 'flex min-w-0 flex-wrap items-center gap-y-2 m-0 list-none p-0',
+    item: 'flex items-center',
+    trigger: [
+      'inline-flex items-center gap-[7px] rounded-sm border-0 bg-transparent p-0',
+      'cursor-pointer select-none outline-none',
+      'transition-colors duration-150',
+      'data-[focus-visible]:shadow-[var(--shadow-focus)]',
+      'data-[disabled]:cursor-default',
+    ],
+    marker: [
+      'grid size-[18px] shrink-0 place-items-center rounded-pill border-[1.5px]',
+      'font-mono text-[10px] font-medium leading-none',
+      'transition-[background-color,border-color,color] duration-150',
+      '[&_svg]:size-[11px]',
+    ],
+    label: 'whitespace-nowrap text-[13px]',
+    connector: 'mx-2.5 h-px w-6 shrink-0 bg-rule',
+  },
+  variants: {
+    orientation: {
+      horizontal: {},
+      vertical: {
+        root: 'flex-col flex-nowrap items-stretch gap-y-0',
+        item: 'flex-col items-start',
+        // Centered under the 18px marker (9px in, minus half the line).
+        connector: 'mx-0 my-1 ml-[8.5px] h-4 w-px',
+      },
+    },
+    state: {
+      completed: {
+        marker: 'border-accent bg-accent text-surface',
+        label: 'text-ink-2 group-data-[hovered]:text-ink',
+      },
+      current: {
+        marker: 'border-accent bg-accent text-surface',
+        label: 'font-medium text-accent',
+      },
+      upcoming: {
+        marker: 'border-rule-strong bg-transparent text-ink-3',
+        label: 'text-ink-3 group-data-[hovered]:text-ink',
+      },
+    },
+    isSelected: {
+      true: { label: 'underline decoration-accent/40 underline-offset-4' },
+      false: {},
+    },
+  },
+  defaultVariants: { orientation: 'horizontal', state: 'upcoming', isSelected: false },
+})
+
+export type StepperVariants = VariantProps<typeof stepperStyles>
+export type StepState = NonNullable<StepperVariants['state']>
+export type StepperOrientation = NonNullable<StepperVariants['orientation']>
+
+export type StepperProps = HTMLAttributes<HTMLOListElement> & {
+  /** Default horizontal. Pass the same value to each step. */
+  orientation?: StepperOrientation
+}
+
+export function Stepper({ orientation, className, ...props }: StepperProps) {
+  const { root } = stepperStyles({ orientation })
+  return <ol {...props} className={cn(root(), className)} />
+}
+
+export type StepperStepProps = Omit<AriaButtonProps, 'children' | 'className'> & {
+  /** Where the step sits relative to the current one. */
+  state: StepState
+  /** Mirrors the parent `<Stepper>`'s orientation (the connector's direction). */
+  orientation?: StepperOrientation
+  /** Zero-based position; drawn as `index + 1` unless `icon` is given. */
+  index: number
+  /** Replaces the number in the marker (the check still wins when completed). */
+  icon?: ReactNode
+  /** The step the consumer is showing — may differ from the current one. */
+  isSelected?: boolean
+  /** Hides the trailing connector. */
+  isLast?: boolean
+  children: ReactNode
+  className?: string
+}
+
+export function StepperStep({
+  state,
+  orientation,
+  index,
+  icon,
+  isSelected = false,
+  isLast = false,
+  children,
+  className,
+  ...props
+}: StepperStepProps) {
+  const styles = stepperStyles({ orientation, state, isSelected })
+  return (
+    <li aria-current={state === 'current' ? 'step' : undefined} className={styles.item()}>
+      <AriaButton {...props} className={cn('group', styles.trigger(), className)}>
+        <span aria-hidden="true" className={styles.marker()}>
+          {state === 'completed' ? <Check strokeWidth={2.5} /> : (icon ?? index + 1)}
+        </span>
+        <span className={styles.label()}>{children}</span>
+      </AriaButton>
+      {!isLast && <span aria-hidden="true" className={styles.connector()} />}
+    </li>
+  )
+}

package/src/components/time-slot-list/index.ts

@@ -0,0 +1,2 @@
+export type { TimeSlotListItem, TimeSlotListProps, TimeSlotListVariants } from './time-slot-list'
+export { TimeSlotList, timeSlotListStyles } from './time-slot-list'

package/src/components/time-slot-list/time-slot-list.stories.tsx

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { TimeSlotList } from './time-slot-list'
+
+const meta: Meta<typeof TimeSlotList> = {
+  title: 'Components/TimeSlotList',
+  component: TimeSlotList,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div className="w-[240px] p-5 bg-surface border border-rule rounded-md">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof TimeSlotList>
+
+const TIMES = ['09:00', '09:30', '10:00', '10:30', '11:00', '13:00', '13:30', '14:00'].map(
+  (label) => ({
+    id: label,
+    label,
+  }),
+)
+
+export const Default: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<string | null>('10:30')
+    return (
+      <TimeSlotList aria-label="Times" items={TIMES} selectedId={selected} onSelect={setSelected} />
+    )
+  },
+}
+
+export const WithInlineConfirm: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<string | null>('10:30')
+    return (
+      <TimeSlotList
+        aria-label="Times"
+        items={TIMES}
+        selectedId={selected}
+        onSelect={setSelected}
+        confirmLabel="Confirm"
+        onConfirm={(id) => alert(`Booked ${id}`)}
+      />
+    )
+  },
+}
+
+export const TakenSlot: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<string | null>(null)
+    return (
+      <TimeSlotList
+        aria-label="Times"
+        items={TIMES.map((item) => (item.id === '10:30' ? { ...item, isDisabled: true } : item))}
+        selectedId={selected}
+        onSelect={setSelected}
+      />
+    )
+  },
+}
+
+export const TwoColumns: Story = {
+  decorators: [
+    (Story) => (
+      <div className="w-[360px]">
+        <Story />
+      </div>
+    ),
+  ],
+  render: () => {
+    const [selected, setSelected] = useState<string | null>(null)
+    return (
+      <TimeSlotList
+        aria-label="Times"
+        items={TIMES}
+        selectedId={selected}
+        onSelect={setSelected}
+        columns={2}
+      />
+    )
+  },
+}
+
+export const Empty: Story = {
+  render: () => (
+    <TimeSlotList
+      aria-label="Times"
+      items={[]}
+      selectedId={null}
+      onSelect={() => {}}
+      emptyMessage="All booked today — pick another day."
+    />
+  ),
+}