@duro-app/ui 5.7.0 → 5.8.0

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/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>`,
+}

package/src/components/Prose/Prose.stories.tsx

@@ -0,0 +1,233 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, waitFor} from 'storybook/test'
+import {Prose} from './Prose'
+import {Heading} from '../Heading/Heading'
+import {Text} from '../Text/Text'
+import {CodeBlock} from '../CodeBlock/CodeBlock'
+import {onThemeSurface} from '../../docs/themedSurface'
+
+// What a Markdown renderer hands over: HTML that is never authored as JSX.
+const RENDERED_MARKDOWN = `
+<p>Flux reconciles every cluster from <code>kubernetes/</code>. Read the
+<a href="#bootstrap">bootstrap notes</a> first.</p>
+<h2 id="bootstrap" class="docs_title__a1b2">Bootstrap</h2>
+<p>Each cluster starts from the same three steps:</p>
+<ol>
+  <li>Install the operator.</li>
+  <li>Seed the secrets:
+    <ul>
+      <li>the Vault token</li>
+      <li>the registry pull secret</li>
+    </ul>
+  </li>
+  <li>Point Flux at the repository.</li>
+</ol>
+<blockquote><p>Never commit a decrypted secret.</p></blockquote>
+<h3>Clusters</h3>
+<table>
+  <thead><tr><th>Cluster</th><th>Nodes</th><th>Role</th></tr></thead>
+  <tbody>
+    <tr><td>homelab</td><td>5</td><td>Applications</td></tr>
+    <tr><td>nas</td><td>1</td><td>Storage</td></tr>
+  </tbody>
+</table>
+<pre><code>flux bootstrap git --url=ssh://git@forge/homelab</code></pre>
+<hr>
+<p><img alt="" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='8'/%3E"></p>
+`
+
+const RELEASE_NOTES = `
+<h2>5.6.0</h2>
+<p>Small controls line up: every <code>size="small"</code> control is at least
+<code>controlSm</code> tall, whatever it holds.</p>
+<h3>Fixed</h3>
+<ul>
+  <li>A small <code>Menu.Trigger</code> in a toolbar no longer shrinks.</li>
+  <li>Toggle and Button share one small padding.</li>
+</ul>
+<blockquote><p>Upgrade with <code>pnpm add @duro-app/ui@5.6.0</code>.</p></blockquote>
+`
+
+const REFERENCE = `
+<h2>relative(date, options)</h2>
+<p>Formats <code>date</code> against <code>options.now</code> with
+<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat">Intl.RelativeTimeFormat</a>.</p>
+<table>
+  <thead><tr><th>Option</th><th>Type</th><th>Default</th></tr></thead>
+  <tbody>
+    <tr><td><code>now</code></td><td>Date | number</td><td>required</td></tr>
+    <tr><td><code>locale</code></td><td>string</td><td>required</td></tr>
+    <tr><td><code>numeric</code></td><td>'auto' | 'always'</td><td>'auto'</td></tr>
+  </tbody>
+</table>
+<pre><code>relative(commit.date, {now, locale: 'fr'})</code></pre>
+`
+
+const DOCUMENTS = {
+  runbook: RENDERED_MARKDOWN,
+  'release-notes': RELEASE_NOTES,
+  reference: REFERENCE,
+} as const
+
+type DocumentName = keyof typeof DOCUMENTS
+
+interface ProseArgs {
+  /** A sample of what a Markdown renderer hands over. */
+  document: DocumentName
+  /** Your own HTML, in place of the sample; empty to show the sample. */
+  html: string
+}
+
+/** Sets the HTML on the element, as a Markdown renderer's output arrives. */
+function Markdown({html = RENDERED_MARKDOWN}: {html?: string}) {
+  return (
+    <Prose
+      ref={(el) => {
+        if (el) el.innerHTML = html
+      }}
+    >
+      {null}
+    </Prose>
+  )
+}
+
+const meta = {
+  title: 'Components/Prose',
+  args: {document: 'runbook', html: ''},
+  argTypes: {
+    document: {
+      control: {
+        type: 'select',
+        labels: {runbook: 'runbook', 'release-notes': 'release notes', reference: 'API reference'},
+      },
+      options: Object.keys(DOCUMENTS),
+    },
+    html: {control: 'text'},
+  },
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: (args) => <Markdown html={args.html || DOCUMENTS[args.document]} />,
+} satisfies Meta<ProseArgs>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const TEST_ONLY = ['!dev', '!autodocs']
+
+/** The computed value of a token, read the way the page resolves it. */
+function resolved(property: 'color' | 'fontSize', token: string, host: HTMLElement) {
+  const probe = document.createElement('span')
+  probe.style[property] = `var(${token})`
+  host.appendChild(probe)
+  const value = getComputedStyle(probe)[property]
+  probe.remove()
+  return value
+}
+
+const style = (el: Element) => getComputedStyle(el)
+
+/**
+ * Rendered Markdown styled by Prose. Pick another sample in `document`, or
+ * paste your own HTML in `html`.
+ */
+export const Playground: Story = {}
+
+/** The runbook sample, measured: flow, headings, lists, tables, code, links. */
+export const RenderedMarkdown: Story = {
+  tags: TEST_ONLY,
+  play: async ({canvasElement}) => {
+    const prose = canvasElement.querySelector('[data-duro-prose]') as HTMLElement
+    await waitFor(() => expect(prose.querySelector('h2')).not.toBeNull())
+    const q = (selector: string) => prose.querySelector(selector) as HTMLElement
+
+    // flow: no gap before the first block, the scale between the rest
+    await expect(style(q('p')).marginTop).toBe('0px')
+    await expect(style(q('ol')).marginTop).toBe('16px')
+    // headings as the docs artboard draws them (Reader.dc.html): a section is
+    // a step below the page title, with more room above than below
+    await expect(style(q('h2')).fontSize).toBe('20px')
+    await expect(style(q('h2')).fontWeight).toBe('600')
+    await expect(style(q('h2')).marginTop).toBe('24px')
+    await expect(style(q('h2')).marginBottom).toBe('8px')
+    await expect(style(q('h3')).fontSize).toBe('18px')
+    // lists keep their markers and indent
+    await expect(style(q('ol')).listStyleType).toBe('decimal')
+    await expect(style(q('ol ul')).listStyleType).toBe('disc')
+    await expect(style(q('ol')).paddingLeft).toBe('24px')
+    await expect(style(q('li + li')).marginTop).toBe('4px')
+    // tables: the column's full width, horizontal rules only, a muted header
+    const table = q('table')
+    await expect(table.getBoundingClientRect().width).toBe(prose.getBoundingClientRect().width)
+    await expect(style(q('td')).borderBottomWidth).toBe('1px')
+    await expect(style(q('td')).borderLeftWidth).toBe('0px')
+    await expect(style(q('th')).borderTopWidth).toBe('0px')
+    await expect(style(q('th')).fontWeight).toBe('500')
+    await expect(style(q('th')).color).toBe(resolved('color', '--duro-color-text-muted', prose))
+    await expect(style(q('td')).paddingLeft).toBe('8px')
+    // code: monospace inline and in a block
+    await expect(style(q('p code')).fontFamily).toMatch(/mono|Menlo|Consolas|monospace/i)
+    await expect(style(q('pre')).overflowX).toBe('auto')
+    await expect(style(q('pre code')).borderTopWidth).toBe('0px')
+    // links read as links
+    await expect(style(q('a')).color).toBe(resolved('color', '--duro-color-accent', prose))
+    await expect(style(q('a')).textDecorationLine).toBe('underline')
+    await expect(style(q('blockquote')).borderLeftWidth).toBe('3px')
+    await expect(style(q('img')).maxWidth).toBe('100%')
+  },
+}
+
+/**
+ * An app's own CSS wins over every Prose rule: a CSS Module class and even a
+ * bare element selector, loaded after Duro's stylesheet. Prose sits in its
+ * own cascade layer and weighs nothing (:where()).
+ */
+export const AppCssWins: Story = {
+  tags: TEST_ONLY,
+  play: async ({canvasElement}) => {
+    const prose = canvasElement.querySelector('[data-duro-prose]') as HTMLElement
+    await waitFor(() => expect(prose.querySelector('h2')).not.toBeNull())
+    const h2 = prose.querySelector('h2') as HTMLElement
+    const h3 = prose.querySelector('h3') as HTMLElement
+    await expect(style(h2).fontSize).toBe('20px')
+    await expect(style(h3).fontSize).toBe('18px')
+
+    const sheet = document.createElement('style')
+    // what kb-vision's docs.module.css compiles to, and the weakest rule an app can write
+    sheet.textContent = `.docs_title__a1b2 { font-size: 13px; margin-top: 0px; } h3 { font-size: 15px; }`
+    document.head.appendChild(sheet)
+    try {
+      await expect(style(h2).fontSize).toBe('13px')
+      await expect(style(h2).marginTop).toBe('0px')
+      await expect(style(h3).fontSize).toBe('15px')
+    } finally {
+      sheet.remove()
+    }
+  },
+}
+
+/** A Duro component inside Prose keeps its own styles: Prose is below them. */
+export const DuroComponentsInside: Story = {
+  render: () => (
+    <Prose>
+      <Heading level={2} variant="headingLg">
+        Kept at headingLg
+      </Heading>
+      <Text>A paragraph from Text.</Text>
+      <CodeBlock copyLabel="Copy" copiedLabel="Copied">
+        pnpm add @duro-app/ui
+      </CodeBlock>
+    </Prose>
+  ),
+}
+
+/** DuroComponentsInside's checks, kept off the visible story so a Control change cannot fail them. */
+export const DuroComponentsInsideChecks: Story = {
+  ...DuroComponentsInside,
+  tags: TEST_ONLY,
+  play: async ({canvas}) => {
+    const heading = canvas.getByRole('heading', {level: 2, name: 'Kept at headingLg'})
+    // headingLg is 30px; a Prose h2 would be 20px
+    await expect(style(heading).fontSize).toBe('30px')
+    await expect(canvas.getByRole('button', {name: 'Copy'})).toBeVisible()
+  },
+}

package/src/components/Prose/Prose.tsx

@@ -0,0 +1,25 @@
+import type {ReactNode, Ref} from 'react'
+import {html} from 'react-strict-dom'
+import './prose.css'
+
+interface ProseProps {
+  /** HTML Duro does not author: the output of a Markdown renderer. */
+  children: ReactNode
+  /** The container element. */
+  ref?: Ref<HTMLDivElement>
+}
+
+/**
+ * Prose — 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.
+ * Duro components inside it (a TextLink, a CodeBlock) keep their own styles,
+ * and an app's own CSS wins over every Prose rule. Web only.
+ */
+export function Prose({children, ref}: ProseProps) {
+  return (
+    <html.div ref={ref} data-duro-prose="">
+      {children}
+    </html.div>
+  )
+}