@duro-app/ui 5.6.0 → 5.8.0

package/src/components/LiveRegion/LiveRegion.meta.ts

@@ -0,0 +1,29 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Tells assistive tech about a change that has no focus move: a polite (role="status") or assertive (role="alert") region. Always mounted — render it empty and change its content to announce; visuallyHidden keeps it off screen.',
+  whenToUse: [
+    'Confirming an action that leaves focus where it is ("Link copied", "Saved")',
+    'A result that arrives later ("12 results", "Answer ready")',
+    'An error the person must hear now — politeness="assertive"',
+  ],
+  whenNotToUse: [
+    'A message that also needs to be seen and dismissed — use Toast (it announces itself)',
+    'An inline field error — use Field.Error',
+  ],
+  relatedTo: [
+    {
+      component: 'VisuallyHidden',
+      kind: 'contrast',
+      relationship:
+        'VisuallyHidden hides static text; LiveRegion visuallyHidden announces changing text',
+    },
+    {
+      component: 'CodeBlock',
+      kind: 'composition',
+      relationship: 'CodeBlock announces "copied" through a LiveRegion',
+    },
+  ],
+  example: `<LiveRegion visuallyHidden>{copied ? 'Link copied' : ''}</LiveRegion>`,
+}

package/src/components/LiveRegion/LiveRegion.stories.tsx

@@ -0,0 +1,139 @@
+import {useState} from 'react'
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn} from 'storybook/test'
+import {LiveRegion, type LiveRegionPoliteness} from './LiveRegion'
+import {Button} from '../Button/Button'
+import {Inline} from '../Inline/Inline'
+import {Stack} from '../Stack/Stack'
+import {onThemeSurface} from '../../docs/themedSurface'
+
+interface LiveRegionArgs {
+  /** `polite` (role="status") waits for a pause; `assertive` (role="alert") interrupts. */
+  politeness: LiveRegionPoliteness
+  /** Off screen, still in the accessibility tree. */
+  visuallyHidden: boolean
+  /** What the region announces when the trigger button is pressed. */
+  message: string
+  /** The trigger button's label. */
+  triggerLabel: string
+  /** The button that empties the region. */
+  clearLabel: string
+  /** Called with the message the region now holds. */
+  onAnnounce: (message: string) => void
+}
+
+/**
+ * The region is mounted empty from the start; a button puts the message in
+ * it, which is what assistive tech announces.
+ */
+function Announcer({
+  politeness,
+  visuallyHidden,
+  message,
+  triggerLabel,
+  clearLabel,
+  onAnnounce,
+}: LiveRegionArgs) {
+  const [content, setContent] = useState('')
+  return (
+    <Stack gap="sm">
+      <Inline gap="sm">
+        <Button
+          variant="secondary"
+          onClick={() => {
+            setContent(message)
+            onAnnounce(message)
+          }}
+        >
+          {triggerLabel}
+        </Button>
+        <Button variant="secondary" onClick={() => setContent('')}>
+          {clearLabel}
+        </Button>
+      </Inline>
+      <LiveRegion politeness={politeness} visuallyHidden={visuallyHidden}>
+        {content}
+      </LiveRegion>
+    </Stack>
+  )
+}
+
+const meta = {
+  title: 'Components/LiveRegion',
+  args: {
+    politeness: 'polite',
+    visuallyHidden: false,
+    message: 'Link copied',
+    triggerLabel: 'Copy link',
+    clearLabel: 'Clear',
+    onAnnounce: fn(),
+  },
+  argTypes: {
+    politeness: {control: 'radio', options: ['polite', 'assertive']},
+    visuallyHidden: {control: 'boolean'},
+    message: {control: 'text'},
+    triggerLabel: {control: 'text'},
+    clearLabel: {control: 'text'},
+  },
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: (args) => <Announcer {...args} />,
+} satisfies Meta<LiveRegionArgs>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const TEST_ONLY = ['!dev', '!autodocs']
+
+/**
+ * Press the trigger: the message appears in the region (unless
+ * `visuallyHidden`) and the Actions panel logs `onAnnounce`. Switch
+ * `politeness` to assertive for role="alert".
+ */
+export const Playground: Story = {}
+
+/** Mounted empty from the start; a change of content is what gets announced. */
+export const Polite: Story = {
+  tags: TEST_ONLY,
+  play: async ({args, canvas, userEvent}) => {
+    const region = canvas.getByRole('status')
+    await expect(region).toHaveAttribute('aria-live', 'polite')
+    await expect(region).toHaveAttribute('aria-atomic', 'true')
+    await expect(region).toBeEmptyDOMElement()
+
+    await userEvent.click(canvas.getByRole('button', {name: args.triggerLabel}))
+    // the same element, now holding the message: a change, not a new region
+    await expect(canvas.getByRole('status')).toBe(region)
+    await expect(region).toHaveTextContent(args.message)
+    await expect(args.onAnnounce).toHaveBeenCalledWith(args.message)
+
+    await userEvent.click(canvas.getByRole('button', {name: args.clearLabel}))
+    await expect(region).toBeInTheDocument()
+    await expect(canvas.getByRole('status')).toBe(region)
+    await expect(region).toBeEmptyDOMElement()
+  },
+}
+
+export const Assertive: Story = {
+  tags: TEST_ONLY,
+  render: () => <LiveRegion politeness="assertive">Connection lost</LiveRegion>,
+  play: async ({canvas}) => {
+    const region = canvas.getByRole('alert')
+    await expect(region).toHaveAttribute('aria-live', 'assertive')
+    await expect(region).toHaveTextContent('Connection lost')
+  },
+}
+
+/** Off screen, still in the accessibility tree. */
+export const VisuallyHidden: Story = {
+  tags: TEST_ONLY,
+  args: {visuallyHidden: true},
+  play: async ({args, canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: args.triggerLabel}))
+    const region = canvas.getByRole('status')
+    await expect(region).toHaveTextContent(args.message)
+    const box = region.getBoundingClientRect()
+    await expect(box.width).toBeLessThanOrEqual(1)
+    await expect(box.height).toBeLessThanOrEqual(1)
+  },
+}

package/src/components/LiveRegion/LiveRegion.tsx

@@ -0,0 +1,48 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {visuallyHidden as hidden} from '../../styles/visually-hidden.css'
+
+export type LiveRegionPoliteness = 'polite' | 'assertive'
+
+interface LiveRegionProps {
+  /**
+   * What to announce. Change it to announce; leave it empty when there is
+   * nothing to say — never unmount the region to clear it.
+   */
+  children?: ReactNode
+  /**
+   * `polite` (default) waits for the screen reader to finish (`role="status"`):
+   * "Copied", "3 results". `assertive` interrupts (`role="alert"`): only for
+   * what the person must hear now, such as an error that blocks them.
+   */
+  politeness?: LiveRegionPoliteness
+  /** Keeps the region off screen and in the accessibility tree. Default false. */
+  visuallyHidden?: boolean
+  id?: string
+}
+
+/**
+ * LiveRegion — tells assistive tech about a change that has no focus move to
+ * go with it ("Link copied", "Answer ready"). A screen reader only announces
+ * a change to a region that was already in the page, so render it from the
+ * start (empty) and change its content; a region mounted together with its
+ * message is often not read at all.
+ */
+export function LiveRegion({
+  children,
+  politeness = 'polite',
+  visuallyHidden = false,
+  id,
+}: LiveRegionProps) {
+  return (
+    <html.div
+      id={id}
+      role={politeness === 'assertive' ? 'alert' : 'status'}
+      aria-live={politeness}
+      aria-atomic={true}
+      style={visuallyHidden ? [hidden.base, hidden.text] : null}
+    >
+      {children}
+    </html.div>
+  )
+}

package/src/components/Menu/Menu.stories.tsx

@@ -8,6 +8,9 @@ import {Menu} from './Menu'
 import {Button} from '../Button/Button'
 import {Dialog} from '../Dialog/Dialog'
 import {Icon} from '../Icon/Icon'
+import {onThemeSurface} from '../../docs/themedSurface'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {withCoarsePointer, withFinePointer} from '../../docs/coarsePointer'
 
 const meta: Meta = {
   title: 'Components/Menu',
@@ -477,3 +480,62 @@ async function realKeyboard(): Promise<((keys: string) => Promise<void>) | null>
     return null
   }
 }
+
+/**
+ * A touch screen gets 44px triggers (coarse pointer), the default and the
+ * ghost variant alike; a mouse keeps the compact control.
+ * It drives Chrome's touch emulation through Vitest's CDP session, so it runs
+ * as a test and stays out of the dev sidebar (there is no Vitest there).
+ */
+export const TouchTargets: Story = {
+  tags: ['!dev', '!autodocs'],
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: () => (
+    <html.div style={touchStyles.row}>
+      <Menu.Root>
+        <Menu.Trigger>Actions</Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item>Rename</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+      <Menu.Root>
+        <Menu.Trigger variant="ghost" aria-label="Page actions">
+          <Icon name="menu" size="sm" />
+        </Menu.Trigger>
+        <Menu.Popup align="end">
+          <Menu.Item>Copy link</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+      <Menu.Root>
+        <Menu.Trigger size="small">Sort</Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item>Name</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const triggers = () => [
+      canvas.getByRole('button', {name: 'Actions'}),
+      canvas.getByRole('button', {name: 'Page actions'}),
+      canvas.getByRole('button', {name: 'Sort'}),
+    ]
+    await withFinePointer()
+    const ghost = canvas.getByRole('button', {name: 'Page actions'}).getBoundingClientRect()
+    await expect(ghost.height).toBeLessThan(SIZES_PX.touchTarget)
+    await withCoarsePointer(async () => {
+      for (const trigger of triggers()) {
+        await waitFor(() => {
+          const box = trigger.getBoundingClientRect()
+          expect(box.height).toBeGreaterThanOrEqual(SIZES_PX.touchTarget)
+          expect(box.width).toBeGreaterThanOrEqual(SIZES_PX.touchTarget)
+        })
+      }
+    })
+  },
+}
+
+const touchStyles = css.create({
+  row: {display: 'flex', gap: spacing.md, alignItems: 'center'},
+})

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

@@ -32,6 +32,9 @@ export const styles = css.create({
     borderStyle: 'solid',
     borderColor: colors.border,
     borderRadius: radii.sm,
+    // A touch screen gets the 44px target; a mouse keeps the compact control.
+    minWidth: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
+    minHeight: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
     cursor: 'pointer',
     transitionProperty: 'background-color, border-color',
     transitionDuration: duration.fast,
@@ -39,8 +42,8 @@ export const styles = css.create({
   // Toolbar trigger: no border or fill until hover, at least icon-button size.
   triggerGhost: {
     justifyContent: 'center',
-    minWidth: sizes.iconButton,
-    minHeight: sizes.iconButton,
+    minWidth: {default: sizes.iconButton, '@media (pointer: coarse)': sizes.touchTarget},
+    minHeight: {default: sizes.iconButton, '@media (pointer: coarse)': sizes.touchTarget},
     paddingTop: spacing.xs,
     paddingBottom: spacing.xs,
     paddingLeft: spacing.xs,
@@ -62,7 +65,7 @@ export const styles = css.create({
   // A small ghost trigger keeps the ghost's xs padding at the small icon-button size.
   triggerGhostSmall: {
     fontSize: typography.fontSizeXs,
-    minWidth: sizes.iconButtonSm,
+    minWidth: {default: sizes.iconButtonSm, '@media (pointer: coarse)': sizes.touchTarget},
     minHeight: {default: sizes.iconButtonSm, '@media (pointer: coarse)': sizes.touchTarget},
   },
   popup: {

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/Prose/Prose.meta.ts

@@ -0,0 +1,32 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    "The container for HTML Duro does not author — rendered Markdown, CMS output: headings, paragraphs, lists, tables, blockquotes, inline code, links and images are styled from tokens by descendant rules scoped to it (plain CSS in dist/index.css, :where() and its own cascade layer). Duro components inside it keep their styles, and an app's own CSS wins over every Prose rule. Web only.",
+  whenToUse: [
+    'The body of a docs page rendered from Markdown',
+    'Any HTML produced by a renderer you do not write as JSX',
+  ],
+  whenNotToUse: [
+    'Text you write as components — use Heading, Text and Stack',
+    'A short label or paragraph — use Text',
+  ],
+  relatedTo: [
+    {
+      component: 'CodeBlock',
+      kind: 'composition',
+      relationship: "Pass CodeBlock as the Markdown renderer's pre, for a copy button",
+    },
+    {
+      component: 'TextLink',
+      kind: 'composition',
+      relationship:
+        "Pass TextLink as the renderer's a, for onNavigate; it keeps its own styles inside Prose",
+    },
+  ],
+  example: `<Prose>
+  <ReactMarkdown components={{pre: ({children}) => <CodeBlock copyLabel="Copy" copiedLabel="Copied">{children}</CodeBlock>}}>
+    {body}
+  </ReactMarkdown>
+</Prose>`,
+}