@duro-app/ui 5.6.0 → 5.8.0

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

package/src/components/Prose/prose.css

@@ -0,0 +1,177 @@
+/*
+ * Prose — styles for HTML that Duro does not author: rendered Markdown, CMS
+ * output. StyleX cannot write descendant rules, so these ship as plain CSS in
+ * dist/index.css. Only var(--duro-*) tokens: the check in
+ * packages/ui/test/prose-css.test.ts fails on any raw length or colour.
+ *
+ * Two things keep it out of everyone's way:
+ *
+ * - The `duro-prose` layer sits after `reset` (so these margins beat the
+ *   reset's `margin: 0`) and before StyleX's own layers (strict.css declares
+ *   the order). A Duro component rendered inside Prose (a TextLink, a
+ *   CodeBlock) keeps its own styles, and any unlayered app CSS — a CSS
+ *   Module rule — wins over every rule here.
+ * - Every selector is wrapped in :where(), so the rules weigh nothing even
+ *   against an app's own layered CSS.
+ *
+ * Scoped to the Prose element: `data-duro-prose` (what the component renders;
+ * react-strict-dom elements take no className) or a `duro-prose` class.
+ */
+
+@layer reset, duro-prose;
+
+@layer duro-prose {
+  :where(.duro-prose, [data-duro-prose]) {
+    color: var(--duro-color-text);
+    font-family: var(--duro-typography-font-family);
+    font-size: var(--duro-type-scale-font-size4);
+    line-height: var(--duro-type-scale-line-height4);
+    overflow-wrap: break-word;
+  }
+
+  /* Flow: one gap between blocks, none before the first. */
+  :where(.duro-prose, [data-duro-prose]) > :where(* + *) {
+    margin-block-start: var(--duro-spacing-md);
+  }
+
+  /* Headings: the Heading presets, with more room above than below. */
+  :where(.duro-prose, [data-duro-prose]) :where(h1, h2, h3, h4, h5, h6) {
+    font-family: var(--duro-typography-font-family);
+    letter-spacing: var(--duro-type-scale-letter-spacing-tight);
+    margin-block-start: var(--duro-spacing-xl);
+    margin-block-end: var(--duro-spacing-sm);
+    /* A table-of-contents jump lands with room above the heading. */
+    scroll-margin-top: var(--duro-spacing-lg);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(h1) {
+    font-size: var(--duro-type-scale-font-size9);
+    line-height: var(--duro-type-scale-line-height9);
+    font-weight: var(--duro-typography-font-weight-bold);
+  }
+  /* h2 down follow the picked docs artboard (Reader.dc.html): a reading
+     column's sections are a step below the page title, not a second one. */
+  :where(.duro-prose, [data-duro-prose]) :where(h2) {
+    font-size: var(--duro-type-scale-font-size6);
+    line-height: var(--duro-type-scale-line-height6);
+    font-weight: var(--duro-typography-font-weight-semibold);
+    margin-block-start: var(--duro-spacing-lg);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(h3) {
+    font-size: var(--duro-type-scale-font-size5);
+    line-height: var(--duro-type-scale-line-height5);
+    font-weight: var(--duro-typography-font-weight-semibold);
+    margin-block-start: var(--duro-spacing-lg);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(h4, h5, h6) {
+    font-size: var(--duro-type-scale-font-size4);
+    line-height: var(--duro-type-scale-line-height4);
+    font-weight: var(--duro-typography-font-weight-semibold);
+    margin-block-start: var(--duro-spacing-md);
+  }
+  :where(.duro-prose, [data-duro-prose]) > :where(:first-child) {
+    margin-block-start: 0;
+  }
+
+  /* Lists: markers back (the reset removes the indent they hang in). */
+  :where(.duro-prose, [data-duro-prose]) :where(ul, ol) {
+    padding-inline-start: var(--duro-spacing-lg);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(ul) {
+    list-style-type: disc;
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(ol) {
+    list-style-type: decimal;
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(li + li, li > ul, li > ol) {
+    margin-block-start: var(--duro-spacing-xs);
+  }
+
+  /* Links: the accent, underlined so they read as links in running text. */
+  :where(.duro-prose, [data-duro-prose]) :where(a) {
+    color: var(--duro-color-accent);
+    text-decoration-line: underline;
+    text-underline-offset: var(--duro-micro-spacing-px2);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(a:hover) {
+    color: var(--duro-color-accent-hover);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(a:focus-visible) {
+    outline: var(--duro-border-focus-ring) solid var(--duro-color-accent);
+    outline-offset: var(--duro-border-focus-offset);
+    border-radius: var(--duro-radius-xs);
+  }
+
+  :where(.duro-prose, [data-duro-prose]) :where(strong, b) {
+    font-weight: var(--duro-typography-font-weight-semibold);
+  }
+
+  :where(.duro-prose, [data-duro-prose]) :where(blockquote) {
+    padding-inline-start: var(--duro-spacing-md);
+    border-inline-start: var(--duro-border-accent) solid var(--duro-color-border);
+    color: var(--duro-color-text-muted);
+  }
+
+  /* Inline code; a heading keeps its own size around it. */
+  :where(.duro-prose, [data-duro-prose]) :where(code) {
+    font-family: var(--duro-typography-font-family-mono);
+    font-size: var(--duro-type-scale-font-size3);
+    padding-inline: var(--duro-spacing-xs);
+    background-color: var(--duro-color-bg-card);
+    border: var(--duro-border-hairline) solid var(--duro-color-border);
+    border-radius: var(--duro-radius-xs);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(h1, h2, h3, h4, h5, h6) :where(code) {
+    font-size: inherit;
+  }
+
+  /* A code block outside CodeBlock (CodeBlock styles its own). */
+  :where(.duro-prose, [data-duro-prose]) :where(pre) {
+    font-family: var(--duro-typography-font-family-mono);
+    font-size: var(--duro-type-scale-font-size3);
+    line-height: var(--duro-type-scale-line-height3);
+    padding: var(--duro-spacing-md);
+    overflow-x: auto;
+    background-color: var(--duro-color-bg-card);
+    border: var(--duro-border-hairline) solid var(--duro-color-border);
+    border-radius: var(--duro-radius-md);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(pre code) {
+    padding: 0;
+    font-size: inherit;
+    background-color: transparent;
+    border: 0;
+  }
+
+  /* Tables as the docs artboard draws them: the column's full width,
+     horizontal rules only, a muted header. A long cell wraps rather than
+     widening the page (a full-width table cannot also scroll on its own). */
+  :where(.duro-prose, [data-duro-prose]) :where(table) {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: var(--duro-type-scale-font-size3);
+    line-height: var(--duro-type-scale-line-height3);
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(th, td) {
+    padding: var(--duro-spacing-xs) var(--duro-spacing-sm);
+    border-block-end: var(--duro-border-hairline) solid var(--duro-color-border);
+    text-align: start;
+    vertical-align: top;
+    overflow-wrap: anywhere;
+  }
+  :where(.duro-prose, [data-duro-prose]) :where(th) {
+    color: var(--duro-color-text-muted);
+    font-weight: var(--duro-typography-font-weight-medium);
+  }
+
+  :where(.duro-prose, [data-duro-prose]) :where(img) {
+    max-width: 100%;
+    height: auto;
+    border-radius: var(--duro-radius-sm);
+  }
+
+  :where(.duro-prose, [data-duro-prose]) :where(hr) {
+    border: 0;
+    border-block-start: var(--duro-border-hairline) solid var(--duro-color-border);
+    margin-block: var(--duro-spacing-xl);
+  }
+}

package/src/components/SideNav/SideNav.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn} from 'storybook/test'
 import {SideNav} from './SideNav'
 import {Icon} from '../Icon/Icon'
+import {onThemeSurface} from '../../docs/themedSurface'
 
 const meta: Meta<typeof SideNav.Root> = {
   title: 'Components/SideNav',
@@ -200,3 +201,31 @@ export const FlatWithIcons: Story = {
     await expect(identities).toHaveAttribute('aria-current', 'page')
   },
 }
+
+/** `aria-label` names the landmark, so a page with a breadcrumb or a pager
+ *  beside it still lists the side navigation by name. */
+export const Named: Story = {
+  parameters: {
+    a11y: {
+      test: 'error',
+      // holds-until: https://github.com/fredericrous/duro-design-system/issues/79
+      // — the selected item's accent on bgCardHover is 6.76:1, under AAA's
+      // 7:1 (AA passes). Re-enable this rule when that pair reaches 7:1.
+      options: {rules: {'color-contrast-enhanced': {enabled: false}}},
+    },
+  },
+  decorators: [onThemeSurface],
+  render: (args) => (
+    <SideNav.Root {...args} aria-label="Settings" defaultValue="profile">
+      <SideNav.Section label="Account">
+        <SideNav.Item value="profile">Profile</SideNav.Item>
+        <SideNav.Item value="security">Security</SideNav.Item>
+      </SideNav.Section>
+    </SideNav.Root>
+  ),
+  play: async ({canvas}) => {
+    const nav = canvas.getByRole('navigation', {name: 'Settings'})
+    await expect(nav).toHaveAttribute('aria-label', 'Settings')
+    await expect(canvas.getByRole('button', {name: 'Profile'})).toBeInTheDocument()
+  },
+}

package/src/components/SideNav/SideNav.tsx

@@ -34,12 +34,24 @@ import {SideNavContext, useSideNav} from './SideNavContext'
 
 interface RootProps {
   children: ReactNode
+  /**
+   * Names the navigation landmark ("Main", "Settings"). Give one whenever
+   * the page has another nav (a breadcrumb, a pager): screen readers list
+   * landmarks by name.
+   */
+  'aria-label'?: string
   value?: string
   defaultValue?: string
   onValueChange?: (value: string) => void
 }
 
-function Root({children, value: controlledValue, defaultValue, onValueChange}: RootProps) {
+function Root({
+  children,
+  'aria-label': ariaLabel,
+  value: controlledValue,
+  defaultValue,
+  onValueChange,
+}: RootProps) {
   const [activeValue, onSelect] = useControllableValue<string | null>(
     controlledValue,
     defaultValue ?? null,
@@ -98,7 +110,7 @@ function Root({children, value: controlledValue, defaultValue, onValueChange}: R
         orderRef,
       }}
     >
-      <html.nav role="navigation" style={styles.root}>
+      <html.nav role="navigation" aria-label={ariaLabel} style={styles.root}>
         {children}
       </html.nav>
     </SideNavContext.Provider>

package/src/components/Time/Time.meta.ts

@@ -0,0 +1,17 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'A date or time in running text as a <time> element: the visible text comes from you, the exact instant goes in dateTime (an ISO string) and title. relative(date, {now, locale}) gives the text on Intl.RelativeTimeFormat ("3 days ago", "il y a 3 jours"); now is required, so the server and the client render the same string. Web only.',
+  whenToUse: [
+    'When something happened: "Updated 3 days ago", a commit date, a last-indexed time',
+    'Any date shown as relative text whose exact value should stay available',
+  ],
+  whenNotToUse: [
+    'A date the person edits — use an Input',
+    'A live countdown or a clock — Time renders once from the now you pass',
+  ],
+  example: `<Time dateTime={doc.lastCommitAt} title={formatFull(doc.lastCommitAt, locale)}>
+  {relative(doc.lastCommitAt, {now: loaderNow, locale})}
+</Time>`,
+}