@duro-app/ui 5.6.0 → 5.8.0

package/src/components/Aside/Aside.stories.tsx

@@ -0,0 +1,106 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, waitFor} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+import {SPACING_KEYS, SPACING_PX, type SpacingToken} from '@duro-app/tokens/keys'
+import {Aside} from './Aside'
+import {Grid} from '../Grid/Grid'
+import {Stack} from '../Stack/Stack'
+import {Text} from '../Text/Text'
+import {TextLink} from '../TextLink/TextLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+
+interface AsideArgs {
+  'aria-label': string
+  /** The gap kept between the viewport's top and the Aside while it sticks. */
+  offset: SpacingToken
+}
+
+const meta = {
+  title: 'Layout/Aside',
+  args: {'aria-label': 'Page outline', offset: 'lg'},
+  argTypes: {
+    'aria-label': {control: 'text'},
+    offset: {control: 'select', options: [...SPACING_KEYS]},
+  },
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: (args) => <LongPage {...args} />,
+} satisfies Meta<AsideArgs>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const styles = css.create({
+  page: {width: sizes.pageLg},
+})
+
+const PARAGRAPHS = Array.from({length: 80}, (_, i) => `Paragraph ${i + 1} of a long runbook.`)
+const SECTIONS = Array.from({length: 60}, (_, i) => `Section ${i + 1}`)
+
+const asideRef: {current: HTMLElement | null} = {current: null}
+
+function LongPage({'aria-label': ariaLabel, offset}: AsideArgs) {
+  return (
+    <html.div style={styles.page}>
+      <Grid layout="content-aside" gap="xl">
+        <Stack gap="md">
+          {PARAGRAPHS.map((text) => (
+            <Text key={text}>{text}</Text>
+          ))}
+        </Stack>
+        <Aside aria-label={ariaLabel} offset={offset} ref={asideRef}>
+          <Stack gap="xs">
+            {SECTIONS.map((name) => (
+              <TextLink key={name} href={`#${name}`}>
+                {name}
+              </TextLink>
+            ))}
+          </Stack>
+        </Aside>
+      </Grid>
+    </html.div>
+  )
+}
+
+/**
+ * A long page with its outline beside it. Scroll the canvas: the Aside sticks
+ * `offset` below the viewport's top and scrolls on its own, being taller than
+ * the viewport. Change `offset` to move where it sticks.
+ */
+export const Playground: Story = {}
+
+/**
+ * Sticks within the viewport while the page scrolls, and scrolls on its own
+ * when it is taller than the viewport; a labelled complementary landmark.
+ * It scrolls the page, so it runs as a test only.
+ */
+export const StickyAndScrolling: Story = {
+  tags: ['!dev', '!autodocs'],
+  play: async ({args, canvas}) => {
+    const aside = canvas.getByRole('complementary', {name: args['aria-label']})
+    await expect(asideRef.current).toBe(aside)
+    await expect(aside.tagName).toBe('ASIDE')
+
+    const cs = getComputedStyle(aside)
+    await expect(cs.position).toBe('sticky')
+    // outside AppShell there is no bar to clear: the bar's custom property is
+    // unset, its fallback is 0, and only the offset remains
+    await expect(cs.getPropertyValue('--duro-app-shell-bar')).toBe('')
+    await expect(cs.top).toBe(`${SPACING_PX.lg}px`)
+    await expect(cs.zIndex).toBe('1')
+    // taller than the room it has: it scrolls on its own, inside the viewport
+    await expect(aside.clientHeight).toBeLessThanOrEqual(window.innerHeight - 2 * SPACING_PX.lg)
+    await expect(aside.scrollHeight).toBeGreaterThan(aside.clientHeight)
+
+    const scroller = document.scrollingElement as HTMLElement
+    const start = scroller.scrollTop
+    try {
+      scroller.scrollTop = start + 600
+      await waitFor(() => expect(scroller.scrollTop).toBeGreaterThan(start))
+      await waitFor(() => expect(Math.round(aside.getBoundingClientRect().top)).toBe(SPACING_PX.lg))
+    } finally {
+      scroller.scrollTop = start
+    }
+  },
+}

package/src/components/Aside/Aside.tsx

@@ -0,0 +1,42 @@
+import type {ReactNode, Ref} from 'react'
+import {html} from 'react-strict-dom'
+import type {SpacingToken} from '@duro-app/tokens/keys'
+import {styles} from './styles.css'
+
+interface AsideProps {
+  /** Names the landmark ("Page outline"); required, from your text catalog. */
+  'aria-label': string
+  /**
+   * The gap kept above the aside while it is stuck, and below it when it is
+   * taller than the viewport. Default `lg`.
+   */
+  offset?: SpacingToken
+  /** The `aside` element. */
+  ref?: Ref<HTMLElement>
+  children: ReactNode
+}
+
+const offsetMap = {
+  xs: styles.offsetXs,
+  sm: styles.offsetSm,
+  ms: styles.offsetMs,
+  md: styles.offsetMd,
+  lg: styles.offsetLg,
+  xl: styles.offsetXl,
+  xxl: styles.offsetXxl,
+  xxxl: styles.offsetXxxl,
+} as const satisfies Record<SpacingToken, unknown>
+
+/**
+ * Aside — content beside the main reading column (a table of contents,
+ * related pages): a labelled `aside` landmark that sticks within the viewport
+ * while the page scrolls and scrolls on its own when it is taller than the
+ * viewport. Put it in the second track of `Grid layout="content-aside"`.
+ */
+export function Aside({'aria-label': ariaLabel, offset = 'lg', ref, children}: AsideProps) {
+  return (
+    <html.aside ref={ref} aria-label={ariaLabel} style={[styles.root, offsetMap[offset]]}>
+      {children}
+    </html.aside>
+  )
+}

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

@@ -0,0 +1,60 @@
+import {css} from 'react-strict-dom'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {layers} from '@duro-app/tokens/tokens/layers.css'
+
+// Kept in step with `--duro-app-shell-bar`, which AppShell/styles.css.ts sets (StyleX needs
+// the literal here, so the name is spelled out twice).
+const BAR = 'var(--duro-app-shell-bar, 0px)'
+
+export const styles = css.create({
+  // Sticky within the viewport, and its own scroll box when taller than the
+  // room it has, so a long table of contents never runs off the screen.
+  // alignSelf: as a grid or flex item it would otherwise stretch to the
+  // row's height and have nowhere to stick. The raised layer keeps it over
+  // content that scrolls under it.
+  root: {
+    position: 'sticky',
+    alignSelf: 'start',
+    zIndex: layers.raised,
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
+    minWidth: 0,
+  },
+  // The gap above it while stuck, and the same gap kept below it. Inside
+  // AppShell below its collapse point the sticky bar covers the top of the
+  // viewport, and AppShell sets `--duro-app-shell-bar` to the bar's height (appBarH)
+  // so the aside sticks under it; anywhere else the property is unset and
+  // the fallback 0 leaves the offset alone.
+  offsetXs: {
+    top: `calc(${BAR} + ${spacing.xs})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.xs})`,
+  },
+  offsetSm: {
+    top: `calc(${BAR} + ${spacing.sm})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.sm})`,
+  },
+  offsetMs: {
+    top: `calc(${BAR} + ${spacing.ms})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.ms})`,
+  },
+  offsetMd: {
+    top: `calc(${BAR} + ${spacing.md})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.md})`,
+  },
+  offsetLg: {
+    top: `calc(${BAR} + ${spacing.lg})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.lg})`,
+  },
+  offsetXl: {
+    top: `calc(${BAR} + ${spacing.xl})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.xl})`,
+  },
+  offsetXxl: {
+    top: `calc(${BAR} + ${spacing.xxl})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.xxl})`,
+  },
+  offsetXxxl: {
+    top: `calc(${BAR} + ${spacing.xxxl})`,
+    maxHeight: `calc(100dvh - ${BAR} - 2 * ${spacing.xxxl})`,
+  },
+})

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

@@ -25,6 +25,9 @@ export const styles = css.create({
     transitionTimingFunction: easing.standard,
     textDecoration: 'none',
     whiteSpace: 'nowrap',
+    // A touch screen gets the 44px target, as Toggle and the triggers do; a
+    // mouse keeps the compact control (5.6, the person's decision).
+    minWidth: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
     // Tactile press feedback. The scale is suppressed under reduced motion (and
     // duration.fast collapses to 0ms there too), so it's inert for those users.
     transform: {
@@ -56,6 +59,7 @@ export const styles = css.create({
     paddingBottom: spacing.sm,
     paddingLeft: spacing.md,
     paddingRight: spacing.md,
+    minHeight: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
   },
   sizeSmall: {
     paddingTop: spacing.xs,
@@ -63,8 +67,9 @@ export const styles = css.create({
     paddingLeft: spacing.sm,
     paddingRight: spacing.sm,
     fontSize: typography.fontSizeXs,
-    // Every small control is at least controlSm tall, whatever it holds (5.6).
-    minHeight: sizes.controlSm,
+    // Every small control is at least controlSm tall, whatever it holds (5.6),
+    // and the touch target under a coarse pointer.
+    minHeight: {default: sizes.controlSm, '@media (pointer: coarse)': sizes.touchTarget},
   },
   primary: {
     backgroundColor: {

package/src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -507,13 +507,14 @@ export const SmallTriggersRow: Story = {
   },
 }
 
-/** The same row under a coarse pointer: Toggle and the three triggers reach
- *  touchTarget, the ghost Menu too. Button has no touch size at any size, so the small Button stays
- *  controlSm (the 5.5 plan's addendum). */
+/** The same row under a coarse pointer: every control reaches touchTarget —
+ *  Toggle, the three triggers, the ghost Menu, and since 5.6 Button too (the
+ *  5.5 addendum had left Button out; the person chose to close it). */
 export const SmallTriggersRowCoarsePointer: Story = {
   render: () => <SmallControlsRow />,
   play: async ({canvas}) => {
     const touch = [
+      canvas.getByRole('button', {name: 'Clear'}),
       canvas.getByRole('button', {name: 'Bold'}),
       canvas.getByRole('button', {name: 'Search'}),
       canvas.getByRole('combobox', {name: 'Block type'}),
@@ -521,12 +522,10 @@ export const SmallTriggersRowCoarsePointer: Story = {
       canvas.getByRole('button', {name: 'Text colour'}),
       canvas.getByRole('button', {name: 'More'}),
     ]
-    const button = canvas.getByRole('button', {name: 'Clear'})
     await withCoarsePointer(async () => {
       for (const el of touch) {
         await waitFor(() => expect(el.offsetHeight).toBe(SIZES_PX.touchTarget))
       }
-      await expect(button.offsetHeight).toBe(SIZES_PX.controlSm)
     })
   },
 }

package/src/components/CodeBlock/CodeBlock.meta.ts

@@ -0,0 +1,29 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'A block of code with a copy button: a pre that scrolls sideways when a line is long, and a Button that copies its text, shows the copied label for copiedDuration ms and announces it through a polite LiveRegion. Labels come from props.',
+  whenToUse: [
+    'Code or a command the reader is likely to paste: a docs page, an install step',
+    "A Markdown renderer's pre, inside Prose",
+  ],
+  whenNotToUse: [
+    'A short identifier in running text — use inline code (Prose styles it)',
+    'Editable code — use Textarea',
+  ],
+  relatedTo: [
+    {
+      component: 'Prose',
+      kind: 'composition',
+      relationship: 'CodeBlock keeps its own styles inside Prose',
+    },
+    {
+      component: 'LiveRegion',
+      kind: 'composition',
+      relationship: 'The copied confirmation is announced through a LiveRegion',
+    },
+  ],
+  example: `<CodeBlock copyLabel="Copy" copiedLabel="Copied">
+  <code>pnpm add @duro-app/ui</code>
+</CodeBlock>`,
+}

package/src/components/CodeBlock/CodeBlock.stories.tsx

@@ -0,0 +1,162 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, spyOn, waitFor} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {CodeBlock} from './CodeBlock'
+import {onThemeSurface} from '../../docs/themedSurface'
+
+interface CodeBlockArgs {
+  /** The code shown (and copied). */
+  code: string
+  copyLabel: string
+  copiedLabel: string
+  /** How long the copied label stays, in ms. */
+  copiedDuration: number
+  /** A refused clipboard (permission denied, an insecure page). */
+  onCopyError: (error: unknown) => void
+}
+
+const COMMAND =
+  'flux bootstrap git --url=ssh://git@forge/homelab --branch=main --path=clusters/homelab'
+
+const meta = {
+  title: 'Components/CodeBlock',
+  args: {
+    code: COMMAND,
+    copyLabel: 'Copy',
+    copiedLabel: 'Copied',
+    copiedDuration: 2000,
+    onCopyError: fn(),
+  },
+  argTypes: {
+    code: {control: 'text'},
+    copyLabel: {control: 'text'},
+    copiedLabel: {control: 'text'},
+    copiedDuration: {control: {type: 'number', min: 0, step: 100}},
+  },
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: ({code, ...args}) => (
+    <CodeBlock {...args}>
+      <html.code>{code}</html.code>
+    </CodeBlock>
+  ),
+} satisfies Meta<CodeBlockArgs>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const TEST_ONLY = ['!dev', '!autodocs']
+
+const styles = css.create({
+  half: {maxWidth: '50%'},
+})
+
+/**
+ * Press the copy button: the label changes to `copiedLabel` for
+ * `copiedDuration` ms and a polite region announces it. A refused clipboard
+ * shows up in Actions as `onCopyError`.
+ */
+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, canvas}) => {
+    await expect(canvas.getByRole('button', {name: args.copyLabel})).toBeVisible()
+    await expect(canvas.getByText(args.code)).toBeInTheDocument()
+  },
+}
+
+/** A long line scrolls inside the block instead of widening the page. */
+export const LongLineScrolls: Story = {
+  args: {code: COMMAND.repeat(3)},
+  render: ({code, ...args}) => (
+    <html.div style={styles.half}>
+      <CodeBlock {...args}>
+        <html.code>{code}</html.code>
+      </CodeBlock>
+    </html.div>
+  ),
+}
+
+/** LongLineScrolls's checks, kept off the visible story so a Control change cannot fail them. */
+export const LongLineScrollsChecks: Story = {
+  ...LongLineScrolls,
+  tags: TEST_ONLY,
+  play: async ({canvasElement}) => {
+    const pre = canvasElement.querySelector('pre') as HTMLElement
+    await expect(pre.scrollWidth).toBeGreaterThan(pre.clientWidth)
+    await expect(getComputedStyle(pre).overflowX).toBe('auto')
+    // and a keyboard can reach it to scroll it
+    await waitFor(() => expect(pre).toHaveAttribute('tabindex', '0'))
+  },
+}
+
+/** Copies the text, confirms on the button and announces it, then resets. */
+export const CopiesAndAnnounces: Story = {
+  tags: TEST_ONLY,
+  args: {copiedDuration: 300},
+  play: async ({args, canvas, userEvent}) => {
+    const write = spyOn(navigator.clipboard, 'writeText').mockResolvedValue(undefined)
+    try {
+      const status = canvas.getByRole('status')
+      await expect(status).toBeEmptyDOMElement()
+      await userEvent.click(canvas.getByRole('button', {name: args.copyLabel}))
+      await expect(write).toHaveBeenCalledWith(args.code)
+      await waitFor(() =>
+        expect(canvas.getByRole('button', {name: args.copiedLabel})).toBeVisible(),
+      )
+      await expect(status).toHaveTextContent(args.copiedLabel)
+      // back to the label after copiedDuration; the region stays mounted
+      await waitFor(() => expect(canvas.getByRole('button', {name: args.copyLabel})).toBeVisible())
+      await expect(canvas.getByRole('status')).toBe(status)
+      await expect(status).toBeEmptyDOMElement()
+    } finally {
+      write.mockRestore()
+    }
+  },
+}
+
+/** A refused clipboard confirms nothing and reports the error. */
+export const CopyRefused: Story = {
+  tags: TEST_ONLY,
+  play: async ({args, canvas, userEvent}) => {
+    const write = spyOn(navigator.clipboard, 'writeText').mockRejectedValue(
+      new DOMException('Denied', 'NotAllowedError'),
+    )
+    try {
+      await userEvent.click(canvas.getByRole('button', {name: args.copyLabel}))
+      await waitFor(() => expect(args.onCopyError).toHaveBeenCalledTimes(1))
+      await expect(canvas.getByRole('button', {name: args.copyLabel})).toBeInTheDocument()
+      await expect(canvas.getByRole('status')).toBeEmptyDOMElement()
+    } finally {
+      write.mockRestore()
+    }
+  },
+}
+
+/** Without onCopyError, a refused clipboard still reaches the console. */
+export const CopyRefusedWithoutHandler: Story = {
+  tags: TEST_ONLY,
+  render: ({code, onCopyError: _onCopyError, ...args}) => (
+    <CodeBlock {...args}>
+      <html.code>{code}</html.code>
+    </CodeBlock>
+  ),
+  play: async ({args, canvas, userEvent}) => {
+    const write = spyOn(navigator.clipboard, 'writeText').mockRejectedValue(
+      new DOMException('Denied', 'NotAllowedError'),
+    )
+    const logged = spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      await userEvent.click(canvas.getByRole('button', {name: args.copyLabel}))
+      await waitFor(() => expect(logged).toHaveBeenCalledTimes(1))
+      await expect(String(logged.mock.calls[0]?.[0])).toContain('CodeBlock')
+      await expect(canvas.getByRole('status')).toBeEmptyDOMElement()
+    } finally {
+      logged.mockRestore()
+      write.mockRestore()
+    }
+  },
+}

package/src/components/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,99 @@
+import {useCallback, useEffect, useRef, useState, type ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {Button} from '../Button/Button'
+import {LiveRegion} from '../LiveRegion/LiveRegion'
+import {typePresets} from '@duro-app/tokens/tokens/type-presets.css'
+import {styles} from './styles.css'
+
+interface CodeBlockProps {
+  /**
+   * The code: text, or the `<code>` element a Markdown renderer produced
+   * (highlighted spans included). What is copied is its text content.
+   */
+  children: ReactNode
+  /** The copy button's label ("Copy"), from your text catalog. */
+  copyLabel: string
+  /**
+   * The label while the copy is confirmed ("Copied"), also announced to
+   * screen readers.
+   */
+  copiedLabel: string
+  /** How long the confirmation stays, in milliseconds. Default 2000. */
+  copiedDuration?: number
+  /** Called when the clipboard refuses the write (an insecure context, a denied permission). */
+  onCopyError?: (error: unknown) => void
+}
+
+/**
+ * CodeBlock — a block of code with a copy button: a `pre` that scrolls
+ * sideways when a line is long (and is then focusable, so a keyboard can
+ * scroll it), and a Button that copies its text and
+ * confirms ("Copied") on the button and through a polite LiveRegion. Inside
+ * `Prose`, pass it as the Markdown renderer's `pre`.
+ */
+export function CodeBlock({
+  children,
+  copyLabel,
+  copiedLabel,
+  copiedDuration = 2000,
+  onCopyError,
+}: CodeBlockProps) {
+  const preRef = useRef<HTMLPreElement | null>(null)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [copied, setCopied] = useState(false)
+  // A block that scrolls sideways joins the tab order, so a keyboard can
+  // scroll it too; one that fits stays out of it.
+  const [scrollable, setScrollable] = useState(false)
+
+  useEffect(() => {
+    const pre = preRef.current
+    if (!pre || typeof ResizeObserver === 'undefined') return
+    const measure = () => setScrollable(pre.scrollWidth > pre.clientWidth)
+    const observer = new ResizeObserver(measure)
+    observer.observe(pre)
+    measure()
+    return () => observer.disconnect()
+  }, [])
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current)
+    },
+    [],
+  )
+
+  const copy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(preRef.current?.textContent ?? '')
+    } catch (error) {
+      // Never dropped: without a handler the failure still reaches the console.
+      if (onCopyError) onCopyError(error)
+      else console.error('CodeBlock: copying to the clipboard failed', error)
+      return
+    }
+    if (timerRef.current) clearTimeout(timerRef.current)
+    setCopied(true)
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null
+      setCopied(false)
+    }, copiedDuration)
+  }, [copiedDuration, onCopyError])
+
+  return (
+    <html.div style={styles.root}>
+      <html.pre
+        ref={preRef}
+        tabIndex={scrollable ? 0 : undefined}
+        style={[typePresets.code, styles.pre]}
+      >
+        {children}
+      </html.pre>
+      <html.div style={styles.copy}>
+        <Button variant="secondary" size="small" onClick={() => void copy()}>
+          {copied ? copiedLabel : copyLabel}
+        </Button>
+      </html.div>
+      <LiveRegion visuallyHidden>{copied ? copiedLabel : ''}</LiveRegion>
+    </html.div>
+  )
+}

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

@@ -0,0 +1,36 @@
+import {css} from 'react-strict-dom'
+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'
+
+export const styles = css.create({
+  // Anchors the copy button to the block's top-right corner.
+  root: {
+    position: 'relative',
+    minWidth: 0,
+  },
+  pre: {
+    margin: 0,
+    paddingTop: spacing.md,
+    paddingBottom: spacing.md,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    overflowX: 'auto',
+    color: colors.text,
+    backgroundColor: colors.bgCard,
+    borderWidth: borders.hairline,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.md,
+    whiteSpace: 'pre',
+    outlineWidth: {default: 0, ':focus-visible': borders.focusRing},
+    outlineStyle: {default: 'none', ':focus-visible': 'solid'},
+    outlineColor: {default: 'transparent', ':focus-visible': colors.accent},
+    outlineOffset: {default: 0, ':focus-visible': borders.focusOffset},
+  },
+  copy: {
+    position: 'absolute',
+    top: spacing.sm,
+    right: spacing.sm,
+  },
+})

package/src/components/DragDrop/DragDrop.meta.ts

@@ -2,15 +2,15 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Move items between zones with one pointer — mouse, pen and touch through the same pointer-event path (touch holds briefly, then drags; a moving touch stays a scroll). A ghost follows the pointer, the zone under it lights up, and the Root announces picks and drops to screen readers. Dragging is pointer-only by design: keep a button or remove affordance that does the same thing.',
-  anatomy: {required: ['Root', 'Zone', 'Item']},
+    'Move items between zones by pointer (mouse, pen and touch through one pointer-event path; touch holds briefly, then drags) or by keyboard (a Handle per item: Space picks up, arrows move, Space drops, Escape cancels). The innermost accepting zone wins, so a zone nested in an Item (a card in a column) takes its own drops; a zone can refuse with a reason that is shown and announced. Placeholders, edge auto-scroll and list-style announcements (through `announce`, for catalog strings) come with it.',
+  anatomy: {required: ['Root', 'Zone', 'Item'], optional: ['Handle']},
   whenToUse: [
     'Slotting things into places — people into approval gates, cards into columns, files into folders',
     'Reordering a short row or list when the order is visible and meaningful',
+    'A board: columns as labelled lists (`list`), cards with a Handle, an attach zone nested in each card',
   ],
   whenNotToUse: [
-    'As the ONLY way to do something — every drag needs a tap/click equivalent (WCAG 2.5.7); this component does not provide one',
-    'Long lists that scroll while dragging — the ghost follows the pointer but zones do not auto-scroll',
+    'As the ONLY way to do something — WCAG 2.5.7 asks for a single-pointer alternative to dragging (a button or menu that moves the item); a Handle adds the keyboard path, not a click one',
     'Sorting tabular data — sort the Table instead',
     'React Native — Item renders its children without drag behaviour there',
   ],
@@ -26,24 +26,25 @@ export const meta: ComponentMeta = {
       relationship: 'ScrollArea drags a thumb along one axis; DragDrop moves items between zones',
     },
   ],
-  example: `<DragDrop.Root onDrop={({item, target}) => move(item.id, target.zone, target.index)}>
-  <DragDrop.Zone id="roster" label="Roster">
-    <Cluster gap="sm">
-      {people.map((p) => (
-        <DragDrop.Item key={p.id} id={p.id} zone="roster" label={p.name} data={p}>
-          <Button variant="secondary" size="small" onClick={() => slot(p)}>{p.name}</Button>
+  example: `<DragDrop.Root
+  onDrop={({item, target}) => move(item.id, target.zone, target.index)}
+  renderPlaceholder={({label}) => <Text variant="caption">→ {label}</Text>}
+  announce={(e) => t(\`board.drag.\${e.kind}\`, e)}
+>
+  {columns.map((col) => (
+    <DragDrop.Zone key={col.id} id={col.id} label={col.name} orientation="vertical" list
+      accepts={(item) => item.data.kind === 'task' || {ok: false, reason: t('board.attachOnCard')}}>
+      {col.cards.map((card) => (
+        <DragDrop.Item key={card.id} id={card.id} zone={col.id} label={card.title} data={card}>
+          <DragDrop.Handle>
+            <DragDrop.Zone id={\`attach:\${card.id}\`} label={card.title}
+              accepts={(item) => item.data.kind === 'activity'}>
+              <Card>{card.title}</Card>
+            </DragDrop.Zone>
+          </DragDrop.Handle>
         </DragDrop.Item>
       ))}
-    </Cluster>
-  </DragDrop.Zone>
-  <DragDrop.Zone id="gates" label="Gates" orientation="horizontal">
-    <Inline gap="sm">
-      {gates.map((g) => (
-        <DragDrop.Item key={g.id} id={g.id} zone="gates" label={g.name} data={g}>
-          <Tag removable onRemove={() => unslot(g)}>{g.name}</Tag>
-        </DragDrop.Item>
-      ))}
-    </Inline>
-  </DragDrop.Zone>
+    </DragDrop.Zone>
+  ))}
 </DragDrop.Root>`,
 }