@duro-app/ui 5.29.0 → 5.31.0

package/dist/table.js

@@ -1,4 +1,4 @@
-import { M as F, q as gt, R as it, H as kt, t as pt, v as bt, w as ft, x as mt, b as ht, g as yt, r as St, y as Tt } from "./Table-Cw1B14R3.js";
+import { M as F, q as gt, R as it, H as kt, t as pt, v as bt, w as ft, x as mt, b as ht, g as yt, r as St, y as Tt } from "./Table-ypIvytAS.js";
 import { jsx as u, jsxs as q } from "react/jsx-runtime";
 import { c as H, m as p, d as b } from "./compiler-runtime-BuugS4D0.js";
 import { flexRender as E, useReactTable as rt, getPaginationRowModel as Ct, getFilteredRowModel as vt, getSortedRowModel as at, getCoreRowModel as st } from "@tanstack/react-table";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.29.0",
+  "version": "5.31.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.29.0"
+    "@duro-app/tokens": "^5.31.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Menu/Menu.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars; size="small" matches small Toggles and Buttons (a small ghost trigger is iconButtonSm). The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog. On React Native the popup is placed against the trigger in a modal overlay; a press outside or the Android back button closes it, and an item runs its onClick after the menu has gone (so an item can open a Dialog). Menu.LinkItem takes onNavigate(href, event) on both platforms (ADR-0002); on native, without it or without preventDefault, the link opens with the system. Native has no arrow keys: each item is its own screen-reader stop.',
+    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars; size="small" matches small Toggles and Buttons (a small ghost trigger is iconButtonSm). The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog. On React Native the popup is placed against the trigger in a modal overlay; a press outside or the Android back button closes it, and an item runs its onClick after the menu has gone (so an item can open a Dialog). Menu.LinkItem takes onNavigate(href, event) on both platforms (ADR-0002); on native, without it or without preventDefault, the link opens with the system. Native has no arrow keys: each item is its own screen-reader stop. A Menu.Item can be disabled: it stays listed and is announced as disabled, but the highlight and the arrow keys skip it and a press or Enter does nothing.',
   whenToUse: [
     'Context menu or "more actions" dropdown',
     'Navigation links in a dropdown',

package/src/components/Menu/Menu.native.tsx

@@ -197,15 +197,30 @@ const layout = StyleSheet.create({scroll: {maxHeight: SIZES_PX.listMaxH, flexGro
 
 interface ItemProps {
   onClick?: () => void
+  /** Shown but not available: inert to a press and announced as disabled. */
+  disabled?: boolean
   children: ReactNode
 }
 
-function Item({onClick, children}: ItemProps) {
+function Item({onClick, disabled = false, children}: ItemProps) {
   const {closeThen} = useMenu()
   return (
-    <Pressable accessibilityRole="menuitem" onPress={() => closeThen(onClick)}>
+    <Pressable
+      accessibilityRole="menuitem"
+      accessibilityState={{disabled}}
+      disabled={disabled}
+      onPress={() => closeThen(onClick)}
+    >
       {({pressed}) => (
-        <html.div style={[styles.item, pressed && nativeStyles.itemPressed]}>{children}</html.div>
+        <html.div
+          style={[
+            styles.item,
+            pressed && nativeStyles.itemPressed,
+            disabled && styles.itemDisabled,
+          ]}
+        >
+          {children}
+        </html.div>
       )}
     </Pressable>
   )

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

@@ -539,3 +539,45 @@ export const TouchTargets: Story = {
 const touchStyles = css.create({
   row: {display: 'flex', gap: spacing.md, alignItems: 'center'},
 })
+
+// A disabled item stays listed and is announced as disabled, but the highlight and the arrow keys
+// skip it and a press does nothing (a Sync menu whose Pull is blocked while a push is running).
+const onPull = fn()
+const onPush = fn()
+export const DisabledItem: Story = {
+  render: () => (
+    <Menu.Root>
+      <Menu.Trigger>Sync</Menu.Trigger>
+      <Menu.Popup>
+        <Menu.Item disabled onClick={onPull}>
+          Pull
+        </Menu.Item>
+        <Menu.Item onClick={onPush}>Push</Menu.Item>
+        <Menu.Item>Fetch</Menu.Item>
+      </Menu.Popup>
+    </Menu.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    onPull.mockClear()
+    onPush.mockClear()
+    await userEvent.click(canvas.getByRole('button', {name: 'Sync'}))
+    const menu = await page().findByRole('menu', {name: 'Sync'})
+    const pull = page().getByRole('menuitem', {name: 'Pull'})
+    const push = page().getByRole('menuitem', {name: 'Push'})
+    await expect(pull).toHaveAttribute('aria-disabled', 'true')
+    // The highlight opens on the first item that can be chosen.
+    await waitFor(() => expect(menu).toHaveAttribute('aria-activedescendant', push.id))
+    await userEvent.click(pull)
+    await expect(onPull).not.toHaveBeenCalled()
+    await expect(menu).toBeInTheDocument()
+    // Up from Push wraps to Fetch, never landing on Pull.
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(menu).toHaveAttribute(
+      'aria-activedescendant',
+      page().getByRole('menuitem', {name: 'Fetch'}).id,
+    )
+    await userEvent.keyboard('{ArrowDown}')
+    await userEvent.keyboard('{Enter}')
+    await expect(onPush).toHaveBeenCalledOnce()
+  },
+}

package/src/components/Menu/Menu.tsx

@@ -186,10 +186,12 @@ function Popup({children, align = 'start'}: PopupProps) {
 // --- Item ---
 interface ItemProps {
   onClick?: () => void
+  /** Shown but not available: skipped by the arrow keys, inert to a press, announced as disabled. */
+  disabled?: boolean
   children: ReactNode
 }
 
-function Item({onClick, children}: ItemProps) {
+function Item({onClick, disabled = false, children}: ItemProps) {
   const {close, highlightedId, setHighlightedId, registerItem} = useMenu()
   const id = useId()
   const ref = useRef<HTMLDivElement>(null)
@@ -198,10 +200,11 @@ function Item({onClick, children}: ItemProps) {
   useEffect(() => {
     const el = ref.current
     if (!el) return
-    return registerItem(id, el)
-  }, [id, registerItem])
+    return registerItem(id, el, disabled)
+  }, [disabled, id, registerItem])
 
   const handleClick = () => {
+    if (disabled) return
     onClick?.()
     close()
   }
@@ -211,9 +214,14 @@ function Item({onClick, children}: ItemProps) {
       ref={ref}
       id={id}
       role="menuitem"
+      aria-disabled={disabled || undefined}
       onClick={handleClick}
-      onPointerEnter={() => setHighlightedId(id)}
-      style={[styles.item, isHighlighted && styles.itemHighlighted]}
+      onPointerEnter={disabled ? undefined : () => setHighlightedId(id)}
+      style={[
+        styles.item,
+        isHighlighted && styles.itemHighlighted,
+        disabled && styles.itemDisabled,
+      ]}
     >
       {children}
     </html.div>

package/src/components/Menu/MenuContext.ts

@@ -9,7 +9,8 @@ export interface MenuContextValue {
   triggerId: string
   highlightedId: string | null
   setHighlightedId: (id: string | null) => void
-  registerItem: (id: string, element: HTMLElement) => () => void
+  /** A disabled item stays listed but the keys skip it and Enter does nothing. */
+  registerItem: (id: string, element: HTMLElement, disabled?: boolean) => () => void
   triggerRef: React.RefObject<HTMLButtonElement | null>
   popupRef: React.RefObject<HTMLDivElement | null>
 }

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

@@ -111,6 +111,10 @@ export const styles = css.create({
     transitionProperty: 'background-color',
     transitionDuration: duration.fast,
   },
+  itemDisabled: {
+    color: colors.textDisabled,
+    cursor: 'not-allowed',
+  },
   // The fill is the highlight; the transparent outline is what forced-colors
   // mode paints, where fills are dropped.
   itemHighlighted: {

package/src/components/Menu/useMenuRoot.ts

@@ -29,6 +29,12 @@ export function useMenuRoot(options: MenuRootOptions) {
   const popupRef = useRef<HTMLDivElement | null>(null)
   const itemsRef = useRef(new Map<string, HTMLElement>())
   const orderRef = useRef<string[]>([])
+  const disabledRef = useRef(new Set<string>())
+  // What the keys move through: the items in document order, without the disabled ones.
+  const enabledOrder = useCallback(
+    () => orderRef.current.filter((id) => !disabledRef.current.has(id)),
+    [],
+  )
   // Closes and leaves focus where it is (a press elsewhere put it there).
   const dismiss = useCallback(() => {
     if (!openRef.current) return
@@ -54,13 +60,13 @@ export function useMenuRoot(options: MenuRootOptions) {
   useEffect(() => {
     if (open && !wasOpenRef.current) {
       popupRef.current?.focus({preventScroll: true})
-      const first = orderRef.current[0]
+      const first = enabledOrder()[0]
       if (first) setHighlightedId(first)
     } else if (!open && wasOpenRef.current) {
       setHighlightedId(null)
     }
     wasOpenRef.current = open
-  }, [open])
+  }, [open, enabledOrder])
 
   // Keep the highlighted item in view when the popup scrolls.
   useEffect(() => {
@@ -69,8 +75,10 @@ export function useMenuRoot(options: MenuRootOptions) {
     el?.scrollIntoView?.({block: 'nearest'})
   }, [highlightedId])
 
-  const registerItem = useCallback((id: string, element: HTMLElement) => {
+  const registerItem = useCallback((id: string, element: HTMLElement, disabled = false) => {
     itemsRef.current.set(id, element)
+    if (disabled) disabledRef.current.add(id)
+    else disabledRef.current.delete(id)
     const map = itemsRef.current
     const ids = [...map.keys()]
     ids.sort((a, b) => {
@@ -82,6 +90,7 @@ export function useMenuRoot(options: MenuRootOptions) {
     orderRef.current = ids
     return () => {
       itemsRef.current.delete(id)
+      disabledRef.current.delete(id)
       orderRef.current = orderRef.current.filter((i) => i !== id)
     }
   }, [])
@@ -104,7 +113,7 @@ export function useMenuRoot(options: MenuRootOptions) {
         close()
         return
       }
-      const order = orderRef.current
+      const order = enabledOrder()
       if (order.length === 0) return
 
       switch (e.key) {
@@ -138,7 +147,7 @@ export function useMenuRoot(options: MenuRootOptions) {
         case ' ': {
           e.preventDefault()
           const current = highlightedRef.current
-          if (current) itemsRef.current.get(current)?.click()
+          if (current && !disabledRef.current.has(current)) itemsRef.current.get(current)?.click()
           break
         }
       }
@@ -146,7 +155,7 @@ export function useMenuRoot(options: MenuRootOptions) {
 
     popup.addEventListener('keydown', handleKeyDown)
     return () => popup.removeEventListener('keydown', handleKeyDown)
-  }, [open, close])
+  }, [open, close, enabledOrder])
 
   // A press outside the trigger and the popup closes the menu, and leaves
   // focus where the press put it.

package/src/components/Select/Select.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it). Select.Trigger takes size="small" to match small Toggles and Buttons in a toolbar. Select.Popup takes label (the list\'s accessible name) and empty (shown in place of the list when it has no items). On the web the list opens below the trigger, or above it when it would overflow the viewport below and fits above. On React Native the trigger opens a bottom sheet (a Drawer at the medium and large detents) titled by label, with a Cancel text button (cancelLabel); the chosen option is filled with a trailing check, and a press picks an option and closes the sheet. Native has no arrow keys: each option is its own screen-reader stop. An Item can be disabled (shown, skipped by the keys, inert to a press, announced as disabled), and onOpenChange on Root reports the list opening and closing, so work such as checking which options are available starts only once someone is choosing.',
+    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it). Select.Trigger takes size="small" to match small Toggles and Buttons in a toolbar. Select.Popup takes label (the list\'s accessible name) and empty (shown in place of the list when it has no items). On the web the list opens below the trigger, or above it when it would overflow the viewport below and fits above. On React Native the trigger opens a bottom sheet (a Drawer at the medium and large detents) titled by label, with a Cancel text button (cancelLabel); the chosen option is filled with a trailing check, and a press picks an option and closes the sheet. Native has no arrow keys: each option is its own screen-reader stop. An Item can be disabled (shown, skipped by the keys, inert to a press, announced as disabled), and onOpenChange on Root reports the list opening and closing, so work such as checking which options are available starts only once someone is choosing. Root takes disabled for the whole control: the trigger is a disabled button (announced so, on native too) and does not open.',
   whenToUse: [
     'User must pick one option from a predefined list',
     'Form field for country, category, role selection',

package/src/components/Select/Select.native.tsx

@@ -28,6 +28,7 @@ const SNAP_POINTS = ['medium', 'large'] as const
 interface NativeSelectContextValue {
   value: string | null
   open: boolean
+  disabled: boolean
   setOpen: (open: boolean) => void
   choose: (value: string) => void
   labels: Record<string, string>
@@ -59,6 +60,8 @@ interface RootProps {
   initialLabels?: Record<string, string>
   /** Called when the sheet opens or closes. */
   onOpenChange?: (open: boolean) => void
+  /** The whole control is disabled: the trigger does not open the sheet. */
+  disabled?: boolean
   children: ReactNode
 }
 
@@ -74,6 +77,7 @@ function Root({
   onValueChange,
   initialLabels,
   onOpenChange,
+  disabled = false,
   children,
 }: RootProps) {
   const state = useSelectState({defaultValue, value, onValueChange, initialLabels, onOpenChange})
@@ -90,6 +94,7 @@ function Root({
   const ctx: NativeSelectContextValue = {
     value: state.value,
     open,
+    disabled,
     setOpen,
     choose: (v) => {
       setValue(v)
@@ -123,19 +128,25 @@ function Trigger({
   'aria-label'?: string
   size?: ControlSize
 }) {
-  const {open, setOpen, triggerRef} = useSelect()
+  const {open, disabled, setOpen, triggerRef} = useSelect()
   const hint = useTooltipHint()
   return (
     <Pressable
       ref={triggerRef as RefObject<never>}
+      disabled={disabled}
       onPress={() => setOpen(true)}
       accessibilityRole="combobox"
       accessibilityLabel={ariaLabel}
       accessibilityHint={hint}
-      accessibilityState={{expanded: open}}
+      accessibilityState={{expanded: open, disabled}}
     >
       <html.div
-        style={[styles.trigger, nativeStyles.nativeFlex, size === 'small' && styles.triggerSmall]}
+        style={[
+          styles.trigger,
+          nativeStyles.nativeFlex,
+          size === 'small' && styles.triggerSmall,
+          disabled && styles.triggerDisabled,
+        ]}
       >
         {children}
       </html.div>

package/src/components/Select/Select.stories.tsx

@@ -349,3 +349,34 @@ export const DisabledOptionAndOpenChange: Story = {
     await waitFor(() => expect(onAgentOpenChange).toHaveBeenLastCalledWith(false))
   },
 }
+
+const onDisabledOpenChange = fn()
+
+/**
+ * The whole control can be `disabled` (a choice that does not apply right now: a write
+ * that is not allowed): the trigger is a disabled button, announced so, and does not open.
+ */
+export const DisabledControl: Story = {
+  render: () => (
+    <Select.Root defaultValue="private" disabled onOpenChange={onDisabledOpenChange}>
+      <Select.Trigger aria-label="Visibility">
+        <Select.Value />
+        <Select.Icon />
+      </Select.Trigger>
+      <Select.Popup label="Visibility">
+        <Select.Item value="private">Private</Select.Item>
+        <Select.Item value="public">Public</Select.Item>
+      </Select.Popup>
+    </Select.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    onDisabledOpenChange.mockClear()
+    const trigger = canvas.getByRole('combobox', {name: 'Visibility'})
+    await expect(trigger).toBeDisabled()
+    await expect(trigger).toHaveTextContent(/Private/)
+    await userEvent.click(trigger)
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    await expect(screen.queryByRole('listbox')).toBeNull()
+    await expect(onDisabledOpenChange).not.toHaveBeenCalled()
+  },
+}

package/src/components/Select/Select.tsx

@@ -1,4 +1,13 @@
-import {Children, type ReactNode, useRef, useId, useEffect, useLayoutEffect, useState} from 'react'
+import {
+  Children,
+  type ReactNode,
+  useRef,
+  useId,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from 'react'
 import {createPortal} from 'react-dom'
 import {html} from 'react-strict-dom'
 import {SPACING_PX} from '@duro-app/tokens/keys'
@@ -23,6 +32,8 @@ interface RootProps {
   initialLabels?: Record<string, string>
   /** Called when the list opens or closes (to start work only once someone is choosing). */
   onOpenChange?: (open: boolean) => void
+  /** The whole control is disabled: the trigger is a disabled button and does not open. */
+  disabled?: boolean
   children: ReactNode
 }
 
@@ -33,15 +44,17 @@ function Root({
   onValueChange,
   initialLabels,
   onOpenChange,
+  disabled = false,
   children,
 }: RootProps) {
-  const {ctx, rootRef} = useSelectRoot({
+  const {ctx: rootCtx, rootRef} = useSelectRoot({
     defaultValue,
     value,
     onValueChange,
     initialLabels,
     onOpenChange,
   })
+  const ctx = useMemo(() => ({...rootCtx, disabled}), [rootCtx, disabled])
 
   return (
     <SelectContext.Provider value={ctx}>
@@ -64,7 +77,7 @@ function Trigger({
   /** `small` matches a small Toggle or Button beside it. Default: `default`. */
   size?: ControlSize
 }) {
-  const {open, toggle, listboxId, highlightedId, triggerRef} = useSelect()
+  const {open, disabled, toggle, listboxId, highlightedId, triggerRef} = useSelect()
   const localRef = useRef<HTMLButtonElement>(null)
   const grouped = useGroupedControl<HTMLButtonElement>()
   // Inside a <Field.Root>, adopt its controlId so <Field.Label for={controlId}>
@@ -88,6 +101,7 @@ function Trigger({
       id={fieldCtx?.controlId}
       type="button"
       role={'combobox' as 'listbox'}
+      disabled={disabled}
       onClick={toggle}
       aria-label={ariaLabel}
       aria-expanded={open}
@@ -96,7 +110,12 @@ function Trigger({
       aria-activedescendant={highlightedId ?? undefined}
       aria-describedby={describedBy || undefined}
       aria-invalid={fieldCtx?.invalid || undefined}
-      style={[styles.trigger, size === 'small' && styles.triggerSmall, grouped.style]}
+      style={[
+        styles.trigger,
+        size === 'small' && styles.triggerSmall,
+        disabled && styles.triggerDisabled,
+        grouped.style,
+      ]}
     >
       {children}
     </html.button>

package/src/components/Select/SelectContext.ts

@@ -2,6 +2,8 @@ import {createContext, useContext} from 'react'
 
 export interface SelectContextValue {
   open: boolean
+  /** The whole control is disabled: the trigger does not open. */
+  disabled: boolean
   toggle: () => void
   close: () => void
   value: string | null

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

@@ -37,6 +37,12 @@ export const styles = css.create({
     transitionProperty: 'border-color',
     transitionDuration: duration.fast,
   },
+  // The whole control disabled: Button's disabled look, and no hover accent.
+  triggerDisabled: {
+    opacity: 0.5,
+    cursor: 'not-allowed',
+    borderColor: colors.border,
+  },
   // size="small": Toggle sizeSmall's values, as longhands so they win over the
   // trigger's own longhands. Every small control is at least controlSm tall,
   // whatever it holds, and the touch target under a coarse pointer.

package/src/components/Select/useSelectRoot.ts

@@ -157,6 +157,7 @@ export function useSelectRoot(options: SelectStateOptions) {
   const ctx: SelectContextValue = useMemo(
     () => ({
       open,
+      disabled: false,
       toggle,
       close,
       value,

package/src/components/Video/Video.meta.ts

@@ -0,0 +1,15 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    "A video file with the browser's own controls: a <video> as wide as its container (never wider, at its own ratio) with one source of the given MIME type, named for assistive tech by label. preload is metadata by default (duration and first frame, not the whole file). Web only: on React Native, host your own player (expo-video) behind a .native.tsx leaf.",
+  whenToUse: [
+    'A video file the person opened: a screen recording, a clip in a file viewer',
+    'A video an app turned into an object URL from bytes it fetched',
+  ],
+  whenNotToUse: [
+    'A decorative or autoplaying background — Duro has none',
+    'An image — use an img or Prose',
+  ],
+  example: `<Video src={objectUrl} type="video/mp4" label={fileName} />`,
+}

package/src/components/Video/Video.stories.tsx

@@ -0,0 +1,28 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {Video} from './Video'
+
+const meta: Meta<typeof Video> = {
+  title: 'Components/Video',
+  component: Video,
+}
+export default meta
+type Story = StoryObj<typeof Video>
+
+// A tiny inline WebM is not needed to check the element: the source and its type are what a test reads.
+const SRC = 'https://example.invalid/clip.mp4'
+
+/** A video file shown with the browser's own controls, named for assistive tech by `label`. */
+export const Default: Story = {
+  args: {src: SRC, type: 'video/mp4', label: 'Screen recording of the failing test'},
+  play: async ({canvasElement}) => {
+    const video = canvasElement.querySelector('video')
+    await expect(video).not.toBeNull()
+    await expect(video).toHaveAttribute('aria-label', 'Screen recording of the failing test')
+    await expect(video).toHaveAttribute('controls')
+    await expect(video).toHaveAttribute('preload', 'metadata')
+    const source = video!.querySelector('source')
+    await expect(source).toHaveAttribute('src', SRC)
+    await expect(source).toHaveAttribute('type', 'video/mp4')
+  },
+}

package/src/components/Video/Video.tsx

@@ -0,0 +1,31 @@
+import type {Ref} from 'react'
+
+interface VideoProps {
+  /** The video's URL: a file URL, or an object URL an app made from bytes it fetched. */
+  src: string
+  /** Its MIME type (`video/mp4`, `video/webm`), so the browser picks a playable source. */
+  type: string
+  /** The accessible name: what the video shows (its file name, a caption). */
+  label: string
+  /** The browser's own play, seek and volume controls. Default: true. */
+  controls?: boolean
+  /** How much to fetch before play: metadata (duration, first frame) by default. */
+  preload?: 'none' | 'metadata' | 'auto'
+  /** The video element, e.g. to pause it from elsewhere. */
+  ref?: Ref<HTMLVideoElement>
+}
+
+// Relative sizes only: the video is as wide as its container, never wider, at its own ratio.
+const VIDEO_STYLE = {display: 'block', maxWidth: '100%', height: 'auto'} as const
+
+/**
+ * Video — a video file with the browser's controls. react-strict-dom has no video element, so
+ * this is a raw <video> (as Icon is a raw <svg>). Web only: on native, host your own player.
+ */
+export function Video({src, type, label, controls = true, preload = 'metadata', ref}: VideoProps) {
+  return (
+    <video ref={ref} controls={controls} preload={preload} aria-label={label} style={VIDEO_STYLE}>
+      <source src={src} type={type} />
+    </video>
+  )
+}

package/src/index.ts

@@ -76,6 +76,7 @@ export {Meter, type MeterProps, type MeterTone} from './components/Meter/Meter'
 export {PageNav} from './components/PageNav/PageNav'
 export {Panel} from './components/Panel/Panel'
 export {Prose} from './components/Prose/Prose'
+export {Video} from './components/Video/Video'
 export {RadioGroup} from './components/RadioGroup/RadioGroup'
 export {ScrollArea} from './components/ScrollArea/ScrollArea'
 export {Combobox} from './components/Combobox/Combobox'