@duro-app/ui 5.6.0 → 5.8.0

package/src/components/Time/Time.stories.tsx

@@ -0,0 +1,173 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, waitFor} from 'storybook/test'
+import {html} from 'react-strict-dom'
+import {renderToString} from 'react-dom/server'
+import {hydrateRoot} from 'react-dom/client'
+import {Time} from './Time'
+import {relative} from './relative'
+import {Stack} from '../Stack/Stack'
+import {Text} from '../Text/Text'
+import {onThemeSurface} from '../../docs/themedSurface'
+
+// A fixed instant, as a loader would pass it: never the clock during render.
+const NOW = Date.UTC(2026, 9, 8, 12, 0, 0)
+const COMMIT = '2026-10-05T09:30:00.000Z'
+const DAY_MS = 24 * 60 * 60 * 1000
+
+type Locale = 'en' | 'fr' | 'de'
+
+interface TimeArgs {
+  /** The instant shown, in days from `now` (negative: in the past). */
+  offsetDays: number
+  /** The locale `relative` and the title use. */
+  locale: Locale
+  /** `auto` says "yesterday" where the locale has a word; `always` keeps the number. */
+  numeric: 'auto' | 'always'
+  /** The text before the date. */
+  label: string
+}
+
+const meta = {
+  title: 'Components/Time',
+  args: {offsetDays: -3, locale: 'en', numeric: 'auto', label: 'Updated'},
+  argTypes: {
+    offsetDays: {control: {type: 'range', min: -400, max: 400, step: 1}},
+    locale: {
+      control: {type: 'select', labels: {en: 'English', fr: 'Français', de: 'Deutsch'}},
+      options: ['en', 'fr', 'de'],
+    },
+    numeric: {control: 'radio', options: ['auto', 'always']},
+    label: {control: 'text'},
+  },
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: ({offsetDays, locale, numeric, label}) => {
+    const iso = new Date(NOW + offsetDays * DAY_MS).toISOString()
+    return (
+      <Text variant="bodySm" color="muted">
+        {label}{' '}
+        <Time dateTime={iso} title={full(iso, locale)}>
+          {relative(iso, {now: NOW, locale, numeric})}
+        </Time>
+      </Text>
+    )
+  },
+} satisfies Meta<TimeArgs>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const TEST_ONLY = ['!dev', '!autodocs']
+
+function full(iso: string, locale: string) {
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: 'long',
+    timeStyle: 'short',
+    timeZone: 'UTC',
+  }).format(new Date(iso))
+}
+
+function Updated({locale, label}: {locale: string; label: string}) {
+  return (
+    <Text variant="bodySm" color="muted">
+      {label}{' '}
+      <Time dateTime={COMMIT} title={full(COMMIT, locale)}>
+        {relative(COMMIT, {now: NOW, locale})}
+      </Time>
+    </Text>
+  )
+}
+
+/**
+ * A date relative to a fixed `now` (2026-10-08 12:00 UTC). Move `offsetDays`
+ * to walk through the units (days, weeks, months, years), switch `locale`, and
+ * `numeric` to always for "1 day ago" instead of "yesterday". Hover the date
+ * for the exact instant (title).
+ */
+export const Playground: Story = {}
+
+/** Playground's checks, kept off the visible story so a Control change cannot fail them. */
+export const PlaygroundChecks: Story = {
+  ...Playground,
+  tags: TEST_ONLY,
+  play: async ({args, canvasElement}) => {
+    const time = canvasElement.querySelector('time')!
+    const iso = new Date(NOW + args.offsetDays * DAY_MS).toISOString()
+    await expect(time).toHaveAttribute('datetime', iso)
+    await expect(time).toHaveAttribute('title', full(iso, args.locale))
+  },
+}
+
+/** The words come from the locale; the exact instant stays in dateTime and title. */
+export const TwoLocales: Story = {
+  render: () => (
+    <Stack gap="sm">
+      <Updated locale="en" label="Updated" />
+      <Updated locale="fr" label="Mis à jour" />
+    </Stack>
+  ),
+}
+
+/** TwoLocales' checks, kept off the visible story so a Control change cannot fail them. */
+export const TwoLocalesChecks: Story = {
+  ...TwoLocales,
+  tags: TEST_ONLY,
+  play: async ({canvasElement}) => {
+    const times = [...canvasElement.querySelectorAll('time')]
+    await expect(times).toHaveLength(2)
+    await expect(times[0]).toHaveTextContent('3 days ago')
+    await expect(times[1]).toHaveTextContent('il y a 3 jours')
+    for (const time of times) {
+      await expect(time).toHaveAttribute('datetime', COMMIT)
+    }
+    await expect(times[0]).toHaveAttribute('title', full(COMMIT, 'en'))
+    await expect(times[1]).toHaveAttribute('title', full(COMMIT, 'fr'))
+  },
+}
+
+/** A Date is written as its ISO string. */
+export const FromDate: Story = {
+  tags: TEST_ONLY,
+  render: () => (
+    <Text>
+      <Time dateTime={new Date(NOW)}>{relative(NOW, {now: NOW, locale: 'en'})}</Time>
+    </Text>
+  ),
+  play: async ({canvasElement}) => {
+    const time = canvasElement.querySelector('time')!
+    await expect(time).toHaveAttribute('datetime', new Date(NOW).toISOString())
+    await expect(time).toHaveTextContent('now')
+  },
+}
+
+/** Server and client render the same text from the same `now`: hydration
+ *  reports nothing. It replaces the canvas's content, so it runs as a test only. */
+export const ServerRender: Story = {
+  tags: TEST_ONLY,
+  render: () => <html.div data-ssr-host="" />,
+  play: async ({canvasElement}) => {
+    const host = canvasElement.querySelector('[data-ssr-host]') as HTMLElement
+    const tree = <Updated locale="en" label="Updated" />
+    host.innerHTML = renderToString(tree)
+    const serverText = host.textContent
+    await expect(host.querySelector('time')).toHaveTextContent('3 days ago')
+
+    const errors: unknown[] = []
+    const consoleError = console.error
+    console.error = (...args: unknown[]) => {
+      errors.push(args)
+      consoleError(...args)
+    }
+    const root = hydrateRoot(host, tree, {onRecoverableError: (error) => errors.push(error)})
+    try {
+      // let React finish hydrating before reading the result
+      await waitFor(() => expect(host.querySelector('time')).toHaveTextContent('3 days ago'))
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      await expect(host.textContent).toBe(serverText)
+      await expect(errors).toEqual([])
+    } finally {
+      console.error = consoleError
+      root.unmount()
+    }
+  },
+}

package/src/components/Time/Time.tsx

@@ -0,0 +1,33 @@
+import type {ReactNode} from 'react'
+
+interface TimeProps {
+  /**
+   * The instant, machine-readable: a `Date` (written as its ISO string) or an
+   * ISO 8601 string, which is passed through unchanged.
+   */
+  dateTime: Date | string
+  /**
+   * The exact date and time, shown on hover ("8 October 2026, 14:03 UTC"),
+   * formatted by you in the reader's locale.
+   */
+  title?: string
+  /** What the reader sees: a relative label from `relative()`, or a date. */
+  children: ReactNode
+}
+
+/**
+ * Time — a date or time in running text as a `<time>` element: the visible
+ * text is yours (often `relative(date, {now, locale})`), the exact instant
+ * goes in `dateTime` for machines and `title` for people.
+ *
+ * Web only. A raw `<time>`: react-strict-dom has no `html.time`, and the
+ * element carries no style of its own (it inherits the text around it).
+ */
+export function Time({dateTime, title, children}: TimeProps) {
+  const iso = typeof dateTime === 'string' ? dateTime : dateTime.toISOString()
+  return (
+    <time dateTime={iso} title={title}>
+      {children}
+    </time>
+  )
+}

package/src/components/Time/relative.ts

@@ -0,0 +1,89 @@
+// Pure date arithmetic behind Time: no React, no react-strict-dom, so the
+// unit project tests it in Node.
+
+export interface RelativeOptions {
+  /**
+   * The instant to measure from. Required: read the clock once where the data
+   * is loaded (a route loader) and pass the same value to the server and the
+   * client render, so both produce the same text. Never `Date.now()` during a
+   * render — the client would hydrate a different string.
+   */
+  now: Date | number
+  /** BCP 47 locale(s) for the words ("3 days ago", "il y a 3 jours"). */
+  locale: string | readonly string[]
+  /**
+   * `auto` (default) says "yesterday" / "tomorrow" / "now" where the locale has
+   * a word for it; `always` keeps the number ("1 day ago").
+   */
+  numeric?: 'auto' | 'always'
+}
+
+type Step = readonly [Intl.RelativeTimeFormatUnit, number]
+
+// Each unit is used while |difference| stays below the next one. Months and
+// years are average lengths: a relative label is a rounded reading, the
+// exact instant goes in the dateTime attribute.
+const SECOND = 1000
+const MINUTE = 60 * SECOND
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+const WEEK = 7 * DAY
+const MONTH = 30.436875 * DAY
+const YEAR = 365.2425 * DAY
+
+const STEPS: readonly Step[] = [
+  ['second', SECOND],
+  ['minute', MINUTE],
+  ['hour', HOUR],
+  ['day', DAY],
+  ['week', WEEK],
+  ['month', MONTH],
+  ['year', YEAR],
+]
+
+const LIMITS: Record<Intl.RelativeTimeFormatUnit, number> = {
+  second: MINUTE,
+  seconds: MINUTE,
+  minute: HOUR,
+  minutes: HOUR,
+  hour: DAY,
+  hours: DAY,
+  day: WEEK,
+  days: WEEK,
+  week: MONTH,
+  weeks: MONTH,
+  month: YEAR,
+  months: YEAR,
+  quarter: Infinity,
+  quarters: Infinity,
+  year: Infinity,
+  years: Infinity,
+}
+
+function toTime(value: Date | number | string): number {
+  return typeof value === 'number' ? value : new Date(value).getTime()
+}
+
+/**
+ * How far `date` is from `now`, in words, in the caller's locale:
+ * `relative(lastCommit, {now, locale: 'en'})` → "3 days ago". Built on
+ * `Intl.RelativeTimeFormat`; the largest unit that keeps the count at least 1
+ * is used, rounded to the nearest whole unit.
+ *
+ * An unparseable date throws a `RangeError` (as `Intl` does): check the data
+ * before rendering it.
+ */
+export function relative(date: Date | number | string, options: RelativeOptions): string {
+  const {now, locale, numeric = 'auto'} = options
+  const target = toTime(date)
+  const from = toTime(now)
+  if (!Number.isFinite(target) || !Number.isFinite(from)) {
+    throw new RangeError(`relative: invalid date ${String(date)}`)
+  }
+  const diff = target - from
+  const [unit, size] =
+    STEPS.find(([unit]) => Math.abs(diff) < LIMITS[unit]) ?? STEPS[STEPS.length - 1]
+  // `+ 0` turns a -0 into 0, so "now" is not "0 seconds ago" in `always` mode.
+  const value = Math.round(diff / size) + 0
+  return new Intl.RelativeTimeFormat(locale as string | string[], {numeric}).format(value, unit)
+}

package/src/components/Timeline/Timeline.meta.ts

@@ -0,0 +1,46 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Rows of date bars against a date axis (milestones, releases, sprints), with a progress fill per bar and a today marker. Dates are calendar days (YYYY-MM-DD, UTC). A bar is a toggle button (selected/onSelect), can be a DragDrop.Zone target (dropZone), and its edges are keyboard sliders whose value text is a date (onStartChange/onEndChange).',
+  anatomy: {required: ['Root', 'Row', 'Bar']},
+  whenToUse: [
+    'Milestones or releases over weeks, where the overlap and today matter',
+    'Dropping work onto a milestone (bars as DragDrop zones)',
+  ],
+  whenNotToUse: [
+    'A schedule by hour — a calendar grid fits (timeGutterW, dayHeaderH)',
+    'A dependency graph or a full Gantt chart with links — this draws bars, not edges',
+    'Moving dates with the pointer — edges are keyboard sliders; give a date field for the rest',
+  ],
+  relatedTo: [
+    {
+      component: 'DragDrop',
+      kind: 'composition',
+      relationship: 'Pass dropZone to make a bar a DragDrop.Zone inside a DragDrop.Root',
+    },
+    {
+      component: 'Meter',
+      kind: 'contrast',
+      relationship: 'Meter shows one level; Timeline places spans of time',
+    },
+  ],
+  example: `<Timeline.Root aria-label="Milestones" start="2026-09-21" end="2026-11-08" today="2026-10-08">
+  {milestones.map((m) => (
+    <Timeline.Row key={m.id} label={m.title} description={\`\${m.done} of \${m.total} done\`}>
+      <Timeline.Bar
+        label={m.title}
+        start={m.start}
+        end={m.end}
+        progress={m.done / m.total}
+        selected={selected === m.id}
+        onSelect={() => select(m.id)}
+        onEndChange={(end) => reschedule(m.id, {end})}
+        dropZone={{id: \`ms:\${m.id}\`, label: m.title}}
+      >
+        {m.done}/{m.total}
+      </Timeline.Bar>
+    </Timeline.Row>
+  ))}
+</Timeline.Root>`,
+}

package/src/components/Timeline/Timeline.stories.tsx

@@ -0,0 +1,238 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, waitFor} from 'storybook/test'
+import {useState} from 'react'
+import {css, html} from 'react-strict-dom'
+import {Timeline, type TimelineDate} from './Timeline'
+import {DragDrop, type DragDropEvent} from '../DragDrop/DragDrop'
+import {Text} from '../Text/Text'
+import {onThemeSurface} from '../../docs/themedSurface'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+
+interface Args {
+  onDrop?: (e: DragDropEvent<Task>) => void
+  onSelect?: (id: string) => void
+}
+
+const meta: Meta<Args> = {
+  title: 'Components/Timeline',
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+}
+export default meta
+type Story = StoryObj<Args>
+
+const s = css.create({
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.lg},
+  card: {
+    padding: spacing.xs,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    borderWidth: borders.hairline,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.sm,
+    backgroundColor: colors.bgCard,
+    fontSize: typography.fontSizeSm,
+  },
+})
+
+interface Milestone {
+  id: string
+  title: string
+  start: TimelineDate
+  end: TimelineDate
+  done: number
+  total: number
+}
+
+const MILESTONES: Milestone[] = [
+  {id: 'alpha', title: 'Alpha', start: '2026-09-21', end: '2026-10-04', done: 7, total: 7},
+  {id: 'beta', title: 'Beta', start: '2026-10-01', end: '2026-10-20', done: 4, total: 9},
+  {id: 'ga', title: 'GA', start: '2026-10-19', end: '2026-11-08', done: 0, total: 5},
+]
+
+interface Task {
+  id: string
+  title: string
+}
+
+function Milestones({
+  onDrop,
+  onSelect,
+  droppable = false,
+}: {
+  onDrop?: (e: DragDropEvent<Task>) => void
+  onSelect?: (id: string) => void
+  droppable?: boolean
+}) {
+  const [items, setItems] = useState(MILESTONES)
+  const [selected, setSelected] = useState<string | null>(null)
+  const [tray, setTray] = useState<Task[]>([
+    {id: 't1', title: 'Write release notes'},
+    {id: 't2', title: 'Load test'},
+  ])
+  const patch = (id: string, change: Partial<Milestone>) =>
+    setItems((list) => list.map((m) => (m.id === id ? {...m, ...change} : m)))
+
+  const timeline = (
+    <Timeline.Root
+      aria-label="Milestones"
+      heading="Milestones"
+      start="2026-09-21"
+      end="2026-11-08"
+      today="2026-10-08"
+      locale="en-GB"
+    >
+      {items.map((m) => (
+        <Timeline.Row key={m.id} label={m.title} description={`${m.done} of ${m.total} done`}>
+          <Timeline.Bar<Task>
+            label={m.title}
+            start={m.start}
+            end={m.end}
+            progress={m.total ? m.done / m.total : 0}
+            tone={m.done === m.total ? 'done' : m.done === 0 ? 'planned' : 'default'}
+            selected={selected === m.id}
+            onSelect={() => {
+              onSelect?.(m.id)
+              setSelected((cur) => (cur === m.id ? null : m.id))
+            }}
+            onStartChange={(start) => patch(m.id, {start})}
+            onEndChange={(end) => patch(m.id, {end})}
+            dropZone={droppable ? {id: `ms:${m.id}`, label: m.title} : undefined}
+          >
+            {m.done}/{m.total}
+          </Timeline.Bar>
+        </Timeline.Row>
+      ))}
+    </Timeline.Root>
+  )
+
+  if (!droppable) return timeline
+  return (
+    <DragDrop.Root<Task>
+      onDrop={(e) => {
+        onDrop?.(e)
+        if (e.target.zone.startsWith('ms:')) {
+          const ms = e.target.zone.slice(3)
+          setTray((t) => t.filter((x) => x.id !== e.item.id))
+          setItems((list) => list.map((m) => (m.id === ms ? {...m, total: m.total + 1} : m)))
+        }
+      }}
+    >
+      <html.div style={s.stack}>
+        <Text variant="label">Unscheduled</Text>
+        <DragDrop.Zone id="tray" label="Unscheduled" list order={0}>
+          {tray.map((t) => (
+            <DragDrop.Item key={t.id} id={t.id} zone="tray" label={t.title} data={t}>
+              <DragDrop.Handle>
+                <html.div style={s.card}>{t.title}</html.div>
+              </DragDrop.Handle>
+            </DragDrop.Item>
+          ))}
+        </DragDrop.Zone>
+        {timeline}
+      </html.div>
+    </DragDrop.Root>
+  )
+}
+
+/** Three milestones over seven weeks, with progress fills, today, a
+ *  selectable bar and keyboard edge sliders. */
+export const Default: Story = {
+  render: (args) => <Milestones onSelect={args.onSelect} />,
+  args: {onSelect: fn()},
+  play: async ({canvas, args, userEvent}) => {
+    await expect(canvas.getByRole('group', {name: 'Milestones'})).toBeInTheDocument()
+    await expect(canvas.getByText('Today')).toBeInTheDocument()
+    const beta = canvas.getByRole('button', {name: 'Beta'})
+    await expect(beta).toHaveAttribute('aria-pressed', 'false')
+    await userEvent.click(beta)
+    await expect(args.onSelect).toHaveBeenCalledWith('beta')
+    await expect(beta).toHaveAttribute('aria-pressed', 'true')
+  },
+}
+
+/** Bar edges are sliders whose value is a date: arrows move a day, Page
+ *  keys a week, Home/End to the limit. */
+export const KeyboardEdges: Story = {
+  render: () => <Milestones />,
+  play: async ({canvas, userEvent}) => {
+    const end = canvas.getByRole('slider', {name: 'Beta, end'})
+    await expect(end).toHaveAttribute('aria-valuetext', '20 Oct')
+    end.focus()
+    await userEvent.keyboard('{ArrowRight}')
+    await waitFor(() => expect(end).toHaveAttribute('aria-valuetext', '21 Oct'))
+    await userEvent.keyboard('{PageUp}')
+    await waitFor(() => expect(end).toHaveAttribute('aria-valuetext', '28 Oct'))
+    await userEvent.keyboard('{End}')
+    await waitFor(() => expect(end).toHaveAttribute('aria-valuetext', '8 Nov'))
+    const start = canvas.getByRole('slider', {name: 'Beta, start'})
+    start.focus()
+    await userEvent.keyboard('{Home}')
+    await waitFor(() => expect(start).toHaveAttribute('aria-valuetext', '21 Sept'))
+    // The start cannot pass the end.
+    await expect(start).toHaveAttribute('aria-valuemax', end.getAttribute('aria-valuenow'))
+  },
+}
+
+/** Drag an unscheduled task onto a milestone bar (or pick it with Space and
+ *  move it with the arrow keys). */
+export const Droppable: Story = {
+  render: () => <Milestones droppable />,
+}
+
+/** Bars are DragDrop zones: drop a task on a milestone bar, by pointer or
+ *  by keyboard. */
+export const DropOnBar: Story = {
+  args: {onDrop: fn()},
+  render: (args) => <Milestones droppable onDrop={args.onDrop} />,
+  play: async ({canvas, args, userEvent}) => {
+    // Keyboard: pick, move right into the next zone in order (Alpha), on to
+    // Beta, drop.
+    canvas.getByRole('button', {name: 'Load test'}).focus()
+    await userEvent.keyboard(' ')
+    await userEvent.keyboard('{ArrowRight}{ArrowRight}')
+    await userEvent.keyboard(' ')
+    await expect(args.onDrop).toHaveBeenCalledTimes(1)
+    const call = (args.onDrop as unknown as ReturnType<typeof fn>).mock
+      .calls[0][0] as DragDropEvent<Task>
+    await expect(call.target.zone).toBe('ms:beta')
+    await expect(canvas.getByText('4/10')).toBeInTheDocument()
+
+    // Pointer: drag the other task onto GA.
+    const notes = canvas.getByRole('button', {name: 'Write release notes'})
+    const ga = canvas.getByRole('button', {name: 'GA'})
+    const a = notes.getBoundingClientRect()
+    const b = ga.getBoundingClientRect()
+    const init = (x: number, y: number, buttons = 1) => ({
+      bubbles: true,
+      pointerId: 21,
+      pointerType: 'mouse',
+      isPrimary: true,
+      button: 0,
+      buttons,
+      clientX: x,
+      clientY: y,
+    })
+    const from = {x: a.left + a.width / 2, y: a.top + a.height / 2}
+    const to = {x: b.left + b.width / 2, y: b.top + b.height / 2}
+    notes.parentElement!.dispatchEvent(new PointerEvent('pointerdown', init(from.x, from.y)))
+    for (let i = 1; i <= 8; i++) {
+      document.dispatchEvent(
+        new PointerEvent(
+          'pointermove',
+          init(from.x + ((to.x - from.x) * i) / 8, from.y + ((to.y - from.y) * i) / 8),
+        ),
+      )
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    }
+    document.dispatchEvent(new PointerEvent('pointerup', init(to.x, to.y, 0)))
+    await expect(args.onDrop).toHaveBeenCalledTimes(2)
+    const second = (args.onDrop as unknown as ReturnType<typeof fn>).mock
+      .calls[1][0] as DragDropEvent<Task>
+    await expect(second.target.zone).toBe('ms:ga')
+  },
+}