@duro-app/ui 5.6.0 → 5.7.0

package/src/components/DragDrop/styles.css.ts

@@ -1,10 +1,11 @@
 import {css} from 'react-strict-dom'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
-import {radii} from '@duro-app/tokens/tokens/spacing.css'
+import {radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
 import {shadows} from '@duro-app/tokens/tokens/shadows.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
 import {layers} from '@duro-app/tokens/tokens/layers.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
 
 export const styles = css.create({
   // The item is the drag handle: no browser panning starts on it, so a touch
@@ -26,12 +27,45 @@ export const styles = css.create({
     opacity: 0.4,
     cursor: 'grabbing',
   },
+  // The keyboard path: one focusable widget per item.
+  handle: {
+    borderRadius: radii.sm,
+    outlineStyle: {default: 'none', ':focus-visible': 'solid'},
+    outlineWidth: borders.focusRing,
+    outlineColor: colors.accent,
+    outlineOffset: borders.focusOffset,
+  },
+  // Picked up by keyboard: the ring stays on even without :focus-visible.
+  handlePicked: {
+    outlineStyle: 'dashed',
+  },
   zone: {
     borderRadius: radii.sm,
     transitionProperty: 'box-shadow, background-color',
     transitionDuration: duration.fast,
     transitionTimingFunction: easing.standard,
   },
+  listVertical: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  listHorizontal: {
+    display: 'flex',
+    flexDirection: 'row',
+  },
+  gapXs: {gap: spacing.xs},
+  gapSm: {gap: spacing.sm},
+  gapMs: {gap: spacing.ms},
+  gapMd: {gap: spacing.md},
+  gapLg: {gap: spacing.lg},
+  gapXl: {gap: spacing.xl},
+  gapXxl: {gap: spacing.xxl},
+  gapXxxl: {gap: spacing.xxxl},
+  fill: {
+    boxSizing: 'border-box',
+    width: '100%',
+    height: '100%',
+  },
   // Every zone shows it can receive while something is in the air; the one
   // under the pointer lights up. Drop-target rings, not focus: keyboard focus
   // stays on outlines, which survive forced-colors mode.
@@ -52,6 +86,18 @@ export const styles = css.create({
     outlineColor: 'transparent',
     outlineOffset: `calc(-1 * ${borders.strong})`,
   },
+  // Refused with a reason: the zone says no in the error tone, the ghost
+  // carries the reason.
+  zoneRefused: {
+    backgroundColor: colors.errorBg,
+    outlineStyle: 'dashed',
+    outlineWidth: borders.strong,
+    outlineColor: colors.errorBorder,
+    outlineOffset: `calc(-1 * ${borders.strong})`,
+  },
+  placeholder: {
+    flexShrink: 0,
+  },
   ghost: {
     position: 'fixed',
     top: 0,
@@ -63,9 +109,33 @@ export const styles = css.create({
     opacity: 0.9,
     cursor: 'grabbing',
   },
-  ghostAt: (x: number, y: number, width: number, height: number) => ({
+  // The lifted look: a slight tilt, dropped under reduced motion.
+  ghostTilt: {
+    transform: {
+      default: 'rotate(2deg)',
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+  },
+  refusal: {
+    marginTop: spacing.xs,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    borderRadius: radii.xs,
+    borderWidth: borders.hairline,
+    borderStyle: 'solid',
+    borderColor: colors.errorBorder,
+    backgroundColor: colors.bgCard,
+    color: colors.errorText,
+    fontSize: typography.fontSizeXs,
+    lineHeight: typography.lineHeight,
+    boxShadow: shadows.md,
+    width: 'max-content',
+    maxWidth: '100%',
+  },
+  ghostSize: (width: number, height: number) => ({
     width,
-    height,
-    transform: `translate3d(${x}px, ${y}px, 0)`,
+    minHeight: height,
   }),
 })

package/src/components/Meter/Meter.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'A scalar inside a known range — WIP 2 of 3, a milestone 40% done — as role="meter" with a value text, drawn as a thin bar (the meterH token). The label is the accessible name; valueText says the value in words.',
+  whenToUse: [
+    'A level against a limit or a total: WIP against its limit, tasks done in a milestone, quota used',
+    'Beside a count, when the proportion matters more than the number',
+  ],
+  whenNotToUse: [
+    'Progress of a task that is still running — use Spinner (or a determinate progress pattern)',
+    'Picking a value — use an input; a meter has no thumb',
+    'A status with no range (ok/failing) — use Badge or StatusIcon',
+  ],
+  relatedTo: [
+    {
+      component: 'Badge',
+      kind: 'contrast',
+      relationship: 'Badge states a status or a count; Meter shows a level within a range',
+    },
+  ],
+  example: `<Meter label="In progress WIP" value={2} max={3} valueText="2 of 3" />
+<Meter label="Milestone done" value={0.4} tone="success" />`,
+}

package/src/components/Meter/Meter.stories.tsx

@@ -0,0 +1,64 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {Meter} from './Meter'
+import {Text} from '../Text/Text'
+import {onThemeSurface} from '../../docs/themedSurface'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+
+const s = css.create({
+  col: {display: 'flex', flexDirection: 'column', gap: spacing.md, maxWidth: sizes.gridColMd},
+})
+
+const meta: Meta<typeof Meter> = {
+  title: 'Components/Meter',
+  component: Meter,
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+}
+export default meta
+type Story = StoryObj<typeof Meter>
+
+export const Default: Story = {
+  args: {label: 'Milestone done', value: 0.4},
+  play: async ({canvas}) => {
+    const meter = canvas.getByRole('meter', {name: 'Milestone done'})
+    await expect(meter).toHaveAttribute('aria-valuenow', '0.4')
+    await expect(meter).toHaveAttribute('aria-valuemin', '0')
+    await expect(meter).toHaveAttribute('aria-valuemax', '1')
+    await expect(meter).toHaveAttribute('aria-valuetext', '40%')
+  },
+}
+
+/** Tones for a level against a limit: under, at, over. */
+export const Tones: Story = {
+  render: () => (
+    <html.div style={s.col}>
+      <Text variant="label">Next · 1 of 3</Text>
+      <Meter label="Next WIP" value={1} max={3} valueText="1 of 3" />
+      <Text variant="label">In progress · 3 of 3</Text>
+      <Meter label="In progress WIP" value={3} max={3} valueText="3 of 3" tone="warning" />
+      <Text variant="label">Review · 4 of 3</Text>
+      <Meter label="Review WIP" value={4} max={3} valueText="4 of 3, over the limit" tone="error" />
+      <Text variant="label">Milestone · 70% done</Text>
+      <Meter label="Milestone done" value={0.7} tone="success" />
+    </html.div>
+  ),
+}
+
+/** Over the maximum, aria-valuenow stays in range and the text carries the
+ *  true value; the bar fills, no further. */
+export const OverTheLimit: Story = {
+  args: {label: 'Review WIP', value: 4, max: 3, valueText: '4 of 3, over the limit', tone: 'error'},
+  play: async ({canvas}) => {
+    const meter = canvas.getByRole('meter', {name: 'Review WIP'})
+    await expect(meter).toHaveAttribute('aria-valuenow', '3')
+    await expect(meter).toHaveAttribute('aria-valuetext', '4 of 3, over the limit')
+    const fill = meter.firstElementChild as HTMLElement
+    await expect(fill.getBoundingClientRect().width).toBeCloseTo(
+      meter.getBoundingClientRect().width,
+      0,
+    )
+  },
+}

package/src/components/Meter/Meter.tsx

@@ -0,0 +1,55 @@
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+
+// ---------------------------------------------------------------------------
+// Meter — a scalar inside a known range (WIP 2 of 3, 40% of a milestone's
+// tasks done): role="meter" with a value text, drawn as a thin bar of the
+// `meterH` token. Not a progress bar for a running task (use Spinner) and
+// not an input (no thumb).
+// ---------------------------------------------------------------------------
+
+export type MeterTone = 'accent' | 'success' | 'warning' | 'error'
+
+export interface MeterProps {
+  value: number
+  /** Defaults to 0. */
+  min?: number
+  /** Defaults to 1, so a fraction needs nothing else. */
+  max?: number
+  /** The accessible name, e.g. "In progress WIP". */
+  label: string
+  /** What screen readers read for the value, e.g. "4 of 3, over the limit".
+   *  Defaults to the percentage. */
+  valueText?: string
+  /** The fill's colour; defaults to accent. */
+  tone?: MeterTone
+}
+
+const toneStyle = {
+  accent: styles.accent,
+  success: styles.success,
+  warning: styles.warning,
+  error: styles.error,
+} as const
+
+export function Meter({value, min = 0, max = 1, label, valueText, tone = 'accent'}: MeterProps) {
+  const span = max - min
+  const fraction = span > 0 ? (value - min) / span : 0
+  const clamped = Math.min(Math.max(fraction, 0), 1)
+  // aria-valuenow must sit inside the range; the true value (over the
+  // limit, say) is what valueText is for.
+  const now = Math.min(Math.max(value, min), max)
+  return (
+    <html.div
+      role="meter"
+      aria-label={label}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuenow={now}
+      aria-valuetext={valueText ?? `${Math.round(clamped * 100)}%`}
+      style={styles.track}
+    >
+      <html.div style={[styles.fill, toneStyle[tone], styles.fillAt(clamped * 100)]} />
+    </html.div>
+  )
+}

package/src/components/Meter/styles.css.ts

@@ -0,0 +1,30 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {radii} from '@duro-app/tokens/tokens/spacing.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+
+export const styles = css.create({
+  track: {
+    position: 'relative',
+    width: '100%',
+    height: sizes.meterH,
+    borderRadius: radii.full,
+    backgroundColor: colors.border,
+    overflow: 'hidden',
+  },
+  fill: {
+    height: '100%',
+    borderRadius: radii.full,
+    transitionProperty: 'width',
+    transitionDuration: duration.base,
+    transitionTimingFunction: easing.standard,
+  },
+  accent: {backgroundColor: colors.accent},
+  success: {backgroundColor: colors.success},
+  warning: {backgroundColor: colors.warning},
+  error: {backgroundColor: colors.error},
+  fillAt: (percent: number) => ({
+    width: `${percent}%`,
+  }),
+})

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')
+  },
+}