@duro-app/ui 5.25.0 → 5.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.25.0",
+  "version": "5.27.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -92,7 +92,7 @@
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.13",
     "qrcode": "^1.5.4",
-    "@duro-app/tokens": "^5.25.0"
+    "@duro-app/tokens": "^5.27.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

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

@@ -2,10 +2,11 @@ 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. With language="diff", added, removed and hunk lines are coloured from tokens. On native the text is selectable and scrolls sideways; there is no copy button.',
+    '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. With language="diff", added, removed and hunk lines are coloured from tokens. On native the text is selectable and scrolls sideways; there is no copy button. A diff can carry a lineAction (a button beside each line inside a hunk, one tab stop, Up and Down between them; the line handed over has its old and new line numbers) and renderAfterLine (content under a line, full width: a review comment, an editor); the copied text stays the diff.',
   whenToUse: [
     'Code or a command the reader is likely to paste: a docs page, an install step',
     "A Markdown renderer's pre, inside Prose",
+    'A diff people comment on line by line (lineAction, renderAfterLine)',
   ],
   whenNotToUse: [
     'A short identifier in running text — use inline code (Prose styles it)',

package/src/components/CodeBlock/CodeBlock.native.tsx

@@ -2,6 +2,7 @@ import {ScrollView} from 'react-native'
 import {html} from 'react-strict-dom'
 import {typePresets} from '@duro-app/tokens/tokens/type-presets.css'
 import {DiffLines} from './DiffLines'
+import {DiffRows} from './DiffRows'
 import {textOf} from './diffRoles'
 import {styles} from './styles.css'
 import type {CodeBlockProps} from './types'
@@ -12,9 +13,19 @@ export type {CodeBlockProps} from './types'
  * Native CodeBlock: selectable monospace text that scrolls sideways, with the
  * same diff line roles as the web. The copy button is web only: a phone
  * copies by selecting the text, so the labels and `onCopyError` are unused.
+ * With a line action or content under lines, the diff is rows: each line's
+ * button and content as on the web (no arrow-key roving on a phone).
  */
-export function CodeBlock({children, language}: CodeBlockProps) {
+export function CodeBlock({children, language, lineAction, renderAfterLine}: CodeBlockProps) {
   const text = textOf(children)
+  if (language === 'diff' && (lineAction !== undefined || renderAfterLine !== undefined)) {
+    // Content under a line can hold its own controls, so the rows do not scroll sideways as one text.
+    return (
+      <html.div style={[styles.root, typePresets.code, styles.rows]}>
+        <DiffRows text={text} lineAction={lineAction} renderAfterLine={renderAfterLine} />
+      </html.div>
+    )
+  }
   return (
     <html.div style={styles.root}>
       <ScrollView horizontal>

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

@@ -2,6 +2,9 @@ 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 type {DiffLineInfo} from './diffRoles'
+import {Card} from '../Card/Card'
+import {Text} from '../Text/Text'
 import {onThemeSurface} from '../../docs/themedSurface'
 import {withCoarsePointer, withFinePointer} from '../../docs/coarsePointer'
 import {SIZES_PX} from '@duro-app/tokens/keys'
@@ -244,3 +247,98 @@ export const DiffChecks: Story = {
     }
   },
 }
+
+const REVIEW_DIFF = `@@ -10,3 +10,4 @@
+ export function guard(req, res) {
+-  const token = req.headers.authorization
++  const token = readBearer(req.headers.authorization)
++  if (!token) return unauthorized(res, 'missing_token')
+`
+
+// A removed line exists only in the old file: its name says so, so no two buttons share one.
+const commentOn = (line: DiffLineInfo) =>
+  line.role === 'removed'
+    ? `Comment on old line ${line.oldLine}`
+    : `Comment on line ${line.newLine}`
+
+/**
+ * `lineAction` puts a button beside each line inside a hunk (a review
+ * comment, say), and `renderAfterLine` shows content under a line, full
+ * width. The gutter is one tab stop: Up and Down move between its buttons.
+ */
+export const DiffLineActions: Story = {
+  args: {code: REVIEW_DIFF},
+  render: ({code, ...args}) => (
+    <CodeBlock
+      {...args}
+      language="diff"
+      lineAction={{label: commentOn, onAction: fn()}}
+      renderAfterLine={(line) =>
+        line.newLine === 11 ? (
+          <Card variant="outlined" size="compact">
+            <Text variant="bodySm">Keep the 401 status text: clients read it.</Text>
+          </Card>
+        ) : null
+      }
+    >
+      <html.code>{code}</html.code>
+    </CodeBlock>
+  ),
+}
+
+/** DiffLineActions' checks: one tab stop, arrows move, the line handed over is numbered, copy keeps the diff. */
+export const DiffLineActionsChecks: Story = {
+  ...DiffLineActions,
+  tags: TEST_ONLY,
+  args: {code: REVIEW_DIFF, onCopyError: fn()},
+  render: ({code, ...args}) => {
+    const onAction = onLineAction
+    return (
+      <CodeBlock
+        {...args}
+        language="diff"
+        lineAction={{label: commentOn, onAction}}
+        renderAfterLine={(line) =>
+          line.newLine === 11 ? <Text variant="bodySm">Saved comment</Text> : null
+        }
+      >
+        <html.code>{code}</html.code>
+      </CodeBlock>
+    )
+  },
+  play: async ({args, canvas, canvasElement, userEvent}) => {
+    onLineAction.mockClear()
+    const lineButtons = canvas.getAllByRole('button', {name: /^Comment on/})
+    // The hunk header has no line number, so no button: four lines, four buttons.
+    await expect(lineButtons).toHaveLength(4)
+    await expect(lineButtons.filter((button) => button.tabIndex === 0)).toHaveLength(1)
+
+    lineButtons[0].focus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(canvas.getByRole('button', {name: 'Comment on old line 11'})).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await expect(onLineAction).toHaveBeenCalledWith(
+      expect.objectContaining({role: 'removed', oldLine: 11, newLine: null}),
+    )
+
+    await userEvent.click(canvas.getByRole('button', {name: 'Comment on line 12'}))
+    await expect(onLineAction).toHaveBeenLastCalledWith(
+      expect.objectContaining({role: 'added', oldLine: null, newLine: 12}),
+    )
+
+    // Content under a line comes right after that line's row.
+    const saved = canvas.getByText('Saved comment')
+    const row = canvasElement.querySelector('[data-diff-line="added"]')!
+    await expect(row.compareDocumentPosition(saved) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+
+    const write = spyOn(navigator.clipboard, 'writeText').mockResolvedValue(undefined)
+    try {
+      await userEvent.click(canvas.getByRole('button', {name: args.copyLabel}))
+      await expect(write).toHaveBeenCalledWith(args.code)
+    } finally {
+      write.mockRestore()
+    }
+  },
+}
+
+const onLineAction = fn()

package/src/components/CodeBlock/CodeBlock.tsx

@@ -6,6 +6,7 @@ import {typePresets} from '@duro-app/tokens/tokens/type-presets.css'
 import {styles} from './styles.css'
 import type {CodeBlockProps} from './types'
 import {DiffLines} from './DiffLines'
+import {DiffRows} from './DiffRows'
 import {textOf} from './diffRoles'
 
 export type {CodeBlockProps} from './types'
@@ -24,7 +25,11 @@ export function CodeBlock({
   copiedLabel,
   copiedDuration = 2000,
   onCopyError,
+  lineAction,
+  renderAfterLine,
 }: CodeBlockProps) {
+  // Lines that carry an action or content under them are rows, not text in a pre.
+  const asRows = language === 'diff' && (lineAction !== undefined || renderAfterLine !== undefined)
   const preRef = useRef<HTMLPreElement | null>(null)
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const [copied, setCopied] = useState(false)
@@ -51,7 +56,10 @@ export function CodeBlock({
 
   const copy = useCallback(async () => {
     try {
-      await navigator.clipboard.writeText(preRef.current?.textContent ?? '')
+      // Rows hold buttons and comments: what is copied is still the diff text.
+      await navigator.clipboard.writeText(
+        asRows ? textOf(children) : (preRef.current?.textContent ?? ''),
+      )
     } catch (error) {
       // Never dropped: without a handler the failure still reaches the console.
       if (onCopyError) onCopyError(error)
@@ -64,7 +72,7 @@ export function CodeBlock({
       timerRef.current = null
       setCopied(false)
     }, copiedDuration)
-  }, [copiedDuration, onCopyError])
+  }, [asRows, children, copiedDuration, onCopyError])
 
   return (
     <html.div style={styles.root}>
@@ -73,14 +81,24 @@ export function CodeBlock({
           {copied ? copiedLabel : copyLabel}
         </Button>
       </html.div>
-      <html.pre
-        ref={preRef}
-        tabIndex={scrollable ? 0 : undefined}
-        data-language={language}
-        style={[typePresets.code, styles.pre]}
-      >
-        {language === 'diff' ? <DiffLines text={textOf(children)} /> : children}
-      </html.pre>
+      {asRows ? (
+        <html.div data-language={language} style={[typePresets.code, styles.rows]}>
+          <DiffRows
+            text={textOf(children)}
+            lineAction={lineAction}
+            renderAfterLine={renderAfterLine}
+          />
+        </html.div>
+      ) : (
+        <html.pre
+          ref={preRef}
+          tabIndex={scrollable ? 0 : undefined}
+          data-language={language}
+          style={[typePresets.code, styles.pre]}
+        >
+          {language === 'diff' ? <DiffLines text={textOf(children)} /> : children}
+        </html.pre>
+      )}
       <LiveRegion visuallyHidden>{copied ? copiedLabel : ''}</LiveRegion>
     </html.div>
   )

package/src/components/CodeBlock/DiffRows.tsx

@@ -0,0 +1,101 @@
+import {
+  Fragment,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react'
+import {html} from 'react-strict-dom'
+import {numberDiffLines, splitDiffLines, type DiffLineInfo, type DiffLineRole} from './diffRoles'
+import {styles} from './styles.css'
+import type {CodeBlockLineAction} from './types'
+
+const roleStyle = {
+  added: styles.added,
+  removed: styles.removed,
+  hunk: styles.hunk,
+  context: undefined,
+} as const satisfies Record<DiffLineRole, unknown>
+
+const inHunk = (line: DiffLineInfo) => line.oldLine !== null || line.newLine !== null
+
+/**
+ * A diff as rows rather than one `pre`, for when lines carry an action or
+ * content under them (a pre holds text only). Each row is a gutter and the
+ * line; content after a line spans the row. The gutter is one tab stop: the
+ * active line's button takes Tab, Up and Down move between the buttons.
+ */
+export function DiffRows({
+  text,
+  lineAction,
+  renderAfterLine,
+}: {
+  text: string
+  lineAction?: CodeBlockLineAction
+  renderAfterLine?: (line: DiffLineInfo) => ReactNode
+}) {
+  const lines = useMemo(() => numberDiffLines(splitDiffLines(text)), [text])
+  const available = lineAction?.available ?? inHunk
+  const actionable = useMemo(
+    () => (lineAction ? lines.filter((line) => available(line)).map((line) => line.index) : []),
+    [available, lineAction, lines],
+  )
+  const [activeIndex, setActiveIndex] = useState<number | null>(null)
+  const active =
+    activeIndex !== null && actionable.includes(activeIndex) ? activeIndex : (actionable[0] ?? null)
+  // Structural, so the native build (no DOM lib) types it too; focus exists only on the web.
+  const buttons = useRef(new Map<number, {focus?: () => void}>())
+
+  const move = (from: number, step: 1 | -1) => {
+    const position = actionable.indexOf(from) + step
+    const next = actionable[position]
+    if (next === undefined) return
+    setActiveIndex(next)
+    buttons.current.get(next)?.focus?.()
+  }
+  const onKeyDown = (line: DiffLineInfo) => (event: KeyboardEvent<HTMLButtonElement>) => {
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+    event.preventDefault()
+    move(line.index, event.key === 'ArrowDown' ? 1 : -1)
+  }
+
+  return (
+    <Fragment>
+      {lines.map((line) => {
+        const after = renderAfterLine?.(line)
+        const offered = lineAction !== undefined && actionable.includes(line.index)
+        return (
+          <Fragment key={line.index}>
+            <html.div data-diff-line={line.role} style={[styles.row, roleStyle[line.role]]}>
+              {lineAction ? (
+                <html.span style={styles.gutter}>
+                  {offered ? (
+                    <html.button
+                      type="button"
+                      ref={(node: {focus?: () => void} | null) => {
+                        if (node) buttons.current.set(line.index, node)
+                        else buttons.current.delete(line.index)
+                      }}
+                      aria-label={lineAction.label(line)}
+                      tabIndex={line.index === active ? 0 : -1}
+                      onFocus={() => setActiveIndex(line.index)}
+                      onKeyDown={onKeyDown(line) as ComponentProps<typeof html.button>['onKeyDown']}
+                      onClick={() => lineAction.onAction(line)}
+                      style={styles.lineAction}
+                    >
+                      +
+                    </html.button>
+                  ) : null}
+                </html.span>
+              ) : null}
+              <html.span style={styles.rowText}>{line.text}</html.span>
+            </html.div>
+            {after ? <html.div style={styles.after}>{after}</html.div> : null}
+          </Fragment>
+        )
+      })}
+    </Fragment>
+  )
+}

package/src/components/CodeBlock/diffRoles.ts

@@ -38,3 +38,45 @@ export function textOf(node: ReactNode): string {
   }
   return ''
 }
+
+/** One line of a diff as a line action or after-line content sees it. */
+export interface DiffLineInfo {
+  /** The line's position in the diff text, from 0. */
+  index: number
+  role: DiffLineRole
+  /** The line without its newline. */
+  text: string
+  /** Its line number in the old file: removed and context lines inside a hunk, else null. */
+  oldLine: number | null
+  /** Its line number in the new file: added and context lines inside a hunk, else null. */
+  newLine: number | null
+}
+
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/
+
+/**
+ * Numbers a diff's lines from its hunk headers (`@@ -12,4 +12,6 @@`). Lines
+ * before the first hunk (file headers) and the headers themselves have no
+ * line numbers.
+ */
+export function numberDiffLines(lines: readonly DiffLine[]): DiffLineInfo[] {
+  let oldNext: number | null = null
+  let newNext: number | null = null
+  return lines.map((line, index) => {
+    const text = line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text
+    if (line.role === 'hunk') {
+      const match = HUNK_HEADER.exec(text)
+      oldNext = match ? Number(match[1]) : null
+      newNext = match ? Number(match[2]) : null
+      return {index, role: line.role, text, oldLine: null, newLine: null}
+    }
+    if (oldNext === null || newNext === null) {
+      return {index, role: line.role, text, oldLine: null, newLine: null}
+    }
+    const oldLine = line.role === 'added' ? null : oldNext
+    const newLine = line.role === 'removed' ? null : newNext
+    if (oldLine !== null) oldNext += 1
+    if (newLine !== null) newNext += 1
+    return {index, role: line.role, text, oldLine, newLine}
+  })
+}

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

@@ -2,6 +2,7 @@ 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'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 export const styles = css.create({
   // One bordered block: a row for the copy button, then the code. The button
@@ -50,6 +51,46 @@ export const styles = css.create({
   added: {backgroundColor: colors.successBg},
   removed: {backgroundColor: colors.errorBg},
   hunk: {backgroundColor: colors.infoBg, color: colors.infoText},
+  // Diff rows (a line action or content under lines): the block scrolls
+  // sideways as a whole, each row as wide as the longest line so its tint
+  // bands the full width.
+  rows: {
+    display: 'flex',
+    flexDirection: 'column',
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.md,
+    overflowX: 'auto',
+    color: colors.text,
+  },
+  row: {display: 'flex', alignItems: 'center', minWidth: 'max-content'},
+  gutter: {
+    display: 'flex',
+    justifyContent: 'center',
+    flexShrink: 0,
+    width: sizes.iconButtonSm,
+  },
+  rowText: {whiteSpace: 'pre', paddingRight: spacing.md},
+  lineAction: {
+    width: sizes.chip,
+    height: sizes.chip,
+    padding: 0,
+    borderWidth: 0,
+    borderRadius: radii.xs,
+    backgroundColor: {default: 'transparent', ':hover': colors.bgCardHover},
+    color: colors.textMuted,
+    font: 'inherit',
+    cursor: 'pointer',
+    outlineWidth: {default: 0, ':focus-visible': borders.focusRing},
+    outlineStyle: {default: 'none', ':focus-visible': 'solid'},
+    outlineColor: {default: 'transparent', ':focus-visible': colors.accent},
+  },
+  // Content under a line spans the block, indented past the gutter.
+  after: {
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.sm,
+    paddingLeft: sizes.iconButtonSm,
+    paddingRight: spacing.md,
+  },
   // Native: the code scrolls sideways inside the block.
   scroll: {
     paddingTop: spacing.xs,

package/src/components/CodeBlock/types.ts

@@ -1,4 +1,16 @@
 import type {ReactNode} from 'react'
+import type {DiffLineInfo} from './diffRoles'
+
+export type {DiffLineInfo} from './diffRoles'
+
+/** An action offered on diff lines (comment on a line, link to it). */
+export interface CodeBlockLineAction {
+  /** The button's accessible name for a line ("Comment on line 12"), from your text catalog. */
+  label: (line: DiffLineInfo) => string
+  onAction: (line: DiffLineInfo) => void
+  /** Which lines offer it. Default: every line inside a hunk (one with a line number). */
+  available?: (line: DiffLineInfo) => boolean
+}
 
 export interface CodeBlockProps {
   /**
@@ -26,4 +38,16 @@ export interface CodeBlockProps {
   copiedDuration?: number
   /** Called when the clipboard refuses the write (an insecure context, a denied permission). */
   onCopyError?: (error: unknown) => void
+  /**
+   * With `language="diff"`: a button in a gutter beside each line it is
+   * available on. The gutter is one tab stop; Up and Down move between its
+   * buttons.
+   */
+  lineAction?: CodeBlockLineAction
+  /**
+   * With `language="diff"`: content shown under a line, full width (a comment
+   * thread, an editor). Return null for lines with nothing under them. What
+   * is copied stays the diff text.
+   */
+  renderAfterLine?: (line: DiffLineInfo) => ReactNode
 }

package/src/components/Textarea/Textarea.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Multi-line text input with automatic Field/Form integration. Same Field binding behavior as Input. autoGrow makes the height follow the content from rows up to maxRows, then it scrolls (CSS field-sizing, with a scrollHeight fallback; native grows with the content and caps at maxRows). The anchor props of Listbox.getAnchorProps() (role combobox, aria-controls, aria-expanded, aria-activedescendant) are forwarded as ARIA attributes on web and as the matching accessibility props on native, so a Listbox can be anchored to it while the editor keeps focus.',
+    'Multi-line text input with automatic Field/Form integration. Same Field binding behavior as Input. autoGrow makes the height follow the content from rows up to maxRows, then it scrolls (CSS field-sizing, with a scrollHeight fallback; native grows with the content and caps at maxRows). The anchor props of Listbox.getAnchorProps() (role combobox, aria-controls, aria-expanded, aria-activedescendant) are forwarded as ARIA attributes on web and as the matching accessibility props on native, so a Listbox can be anchored to it while the editor keeps focus. On the web, onFiles receives files pasted into the field or dropped on it (the drop ring shows while files are dragged over it); text pastes stay text.',
   whenToUse: [
     'Multi-line text entry (comments, messages, descriptions)',
     'A composer that grows with its text (autoGrow, maxRows)',

package/src/components/Textarea/Textarea.stories.tsx

@@ -231,3 +231,44 @@ export const AnchoredListbox: Story = {
     await expect(editor).toHaveFocus()
   },
 }
+
+/**
+ * `onFiles` (web): a file pasted into the field or dropped on it goes to
+ * `onFiles`; while files are dragged over it the field shows the drop ring.
+ * Pasted text stays text.
+ */
+export const PasteAndDropFiles: Story = {
+  args: {placeholder: 'Paste or drop a screenshot', onFiles: fn()},
+  play: async ({canvas, args}) => {
+    const field = canvas.getByPlaceholderText('Paste or drop a screenshot')
+    const withFile = () => {
+      const transfer = new DataTransfer()
+      transfer.items.add(new File(['png'], 'shot.png', {type: 'image/png'}))
+      return transfer
+    }
+
+    field.dispatchEvent(
+      new ClipboardEvent('paste', {clipboardData: withFile(), bubbles: true, cancelable: true}),
+    )
+    await expect(args.onFiles).toHaveBeenCalledTimes(1)
+    await expect((args.onFiles as ReturnType<typeof fn>).mock.calls[0][0][0].name).toBe('shot.png')
+
+    const text = new DataTransfer()
+    text.setData('text/plain', 'hello')
+    field.dispatchEvent(
+      new ClipboardEvent('paste', {clipboardData: text, bubbles: true, cancelable: true}),
+    )
+    await expect(args.onFiles).toHaveBeenCalledTimes(1)
+
+    const ringBefore = getComputedStyle(field).boxShadow
+    field.dispatchEvent(
+      new DragEvent('dragenter', {dataTransfer: withFile(), bubbles: true, cancelable: true}),
+    )
+    await waitFor(() => expect(getComputedStyle(field).boxShadow).not.toBe(ringBefore))
+    const drop = new DragEvent('drop', {dataTransfer: withFile(), bubbles: true, cancelable: true})
+    field.dispatchEvent(drop)
+    await expect(drop.defaultPrevented).toBe(true)
+    await expect(args.onFiles).toHaveBeenCalledTimes(2)
+    await waitFor(() => expect(getComputedStyle(field).boxShadow).toBe(ringBefore))
+  },
+}

package/src/components/Textarea/Textarea.tsx

@@ -3,6 +3,7 @@ import {html} from 'react-strict-dom'
 import {useFieldContext} from '../Field/FieldContext'
 import type {ListboxAnchorProps} from '../Listbox/Listbox'
 import {useAutoGrowFallback} from './useAutoGrowFallback'
+import {useFileDrop} from './useFileDrop'
 import {grow} from './grow'
 import {styles} from './styles.css'
 
@@ -39,6 +40,12 @@ interface TextareaBaseProps {
    *  navigation of a list driven by this field. */
   onKeyDown?: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void
   onKeyUp?: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void
+  /**
+   * Web: files pasted into the field or dropped on it (a screenshot, a log).
+   * The field shows the drop ring while files are dragged over it. Text
+   * pastes and drops stay text. Native: never called; attach with FileTrigger.
+   */
+  onFiles?: (files: readonly File[]) => void
   ref?: React.Ref<HTMLTextAreaElement>
 }
 
@@ -65,6 +72,7 @@ export function Textarea({
   onFocus,
   onKeyDown,
   onKeyUp,
+  onFiles,
   ref,
 }: TextareaProps) {
   const ctx = useFieldContext()
@@ -92,6 +100,17 @@ export function Textarea({
     [effectiveRef],
   )
   useAutoGrowFallback(innerRef, autoGrow ? 'content' : 'fixed')
+  const dropOver = useFileDrop(innerRef, onFiles)
+  const onPaste = onFiles
+    ? // Structural: the native build (no DOM lib) types this file too; only the web pastes files.
+      (event: {clipboardData?: {files?: ArrayLike<File>} | null; preventDefault: () => void}) => {
+        const files = Array.from(event.clipboardData?.files ?? [])
+        if (files.length === 0) return
+        // Files only: the field keeps no file name as text.
+        event.preventDefault()
+        onFiles(files)
+      }
+    : undefined
 
   return (
     <html.textarea
@@ -112,6 +131,7 @@ export function Textarea({
       onFocus={onFocus as StrictTextareaProps['onFocus']}
       onKeyDown={onKeyDown as StrictTextareaProps['onKeyDown']}
       onKeyUp={onKeyUp as StrictTextareaProps['onKeyUp']}
+      onPaste={onPaste as StrictTextareaProps['onPaste']}
       role={role}
       aria-controls={ariaControls}
       aria-expanded={ariaExpanded}
@@ -124,6 +144,7 @@ export function Textarea({
         styles[effectiveVariant],
         autoGrow && grow.autoGrow,
         autoGrow && maxRows !== undefined && grow.maxRows(maxRows),
+        dropOver && styles.dropOver,
       ]}
       {...extraProps}
     />

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

@@ -1,4 +1,5 @@
 import {css} from 'react-strict-dom'
+import {shadows} from '@duro-app/tokens/tokens/shadows.css'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
@@ -56,4 +57,6 @@ export const styles = css.create({
       ':focus': colors.error,
     },
   },
+  // Files dragged over the field: the same ring as a DragDrop zone under the pointer.
+  dropOver: {boxShadow: shadows.dropOver},
 })

package/src/components/Textarea/useFileDrop.native.ts

@@ -0,0 +1,6 @@
+import type {RefObject} from 'react'
+
+/** A phone has no drag and drop of files onto a field; attach with FileTrigger. */
+export function useFileDrop(_ref: RefObject<unknown>, _onFiles: unknown): boolean {
+  return false
+}

package/src/components/Textarea/useFileDrop.ts

@@ -0,0 +1,46 @@
+import {useEffect, useState, type RefObject} from 'react'
+
+const carriesFiles = (event: DragEvent) =>
+  Array.from(event.dataTransfer?.types ?? []).includes('Files')
+
+/**
+ * Files dropped on the field go to `onFiles`, and `over` says files are
+ * being dragged over it (for the drop ring). A listener on the element:
+ * react-strict-dom passes no drag events through. Text drags stay the
+ * browser's.
+ */
+export function useFileDrop(
+  ref: RefObject<HTMLTextAreaElement | null>,
+  onFiles: ((files: readonly File[]) => void) | undefined,
+): boolean {
+  const [over, setOver] = useState(false)
+  useEffect(() => {
+    const field = ref.current
+    if (!field || !onFiles) return
+    const enter = (event: DragEvent) => {
+      if (!carriesFiles(event)) return
+      // Claimed, or the browser opens the file instead of dropping it here.
+      event.preventDefault()
+      setOver(true)
+    }
+    const leave = () => setOver(false)
+    const drop = (event: DragEvent) => {
+      if (!carriesFiles(event)) return
+      event.preventDefault()
+      setOver(false)
+      const files = Array.from(event.dataTransfer?.files ?? [])
+      if (files.length > 0) onFiles(files)
+    }
+    field.addEventListener('dragenter', enter)
+    field.addEventListener('dragover', enter)
+    field.addEventListener('dragleave', leave)
+    field.addEventListener('drop', drop)
+    return () => {
+      field.removeEventListener('dragenter', enter)
+      field.removeEventListener('dragover', enter)
+      field.removeEventListener('dragleave', leave)
+      field.removeEventListener('drop', drop)
+    }
+  }, [onFiles, ref])
+  return over
+}