@duro-app/ui 5.32.0 → 5.34.0

package/src/components/Icon/phosphor-names.json

@@ -0,0 +1,130 @@
+[
+  "arrow-circle-down",
+  "arrow-circle-right",
+  "arrow-circle-up",
+  "arrow-clockwise",
+  "arrow-down",
+  "arrow-elbow-down-right",
+  "arrow-left",
+  "arrow-right",
+  "arrow-square-out",
+  "arrows-clockwise",
+  "arrows-down-up",
+  "arrows-left-right",
+  "arrows-out",
+  "article",
+  "at",
+  "bell",
+  "bell-slash",
+  "bookmark",
+  "books",
+  "browsers",
+  "bug",
+  "calendar",
+  "caret-down",
+  "caret-left",
+  "chart-line",
+  "chat",
+  "chat-circle-dots",
+  "chat-dots",
+  "chats-circle",
+  "check",
+  "checks",
+  "circle",
+  "circle-half",
+  "clipboard",
+  "clock-counter-clockwise",
+  "cloud",
+  "cloud-arrow-down",
+  "cloud-arrow-up",
+  "cloud-check",
+  "cloud-slash",
+  "code",
+  "copy",
+  "cpu",
+  "crosshair",
+  "cube",
+  "desktop",
+  "device-mobile",
+  "download",
+  "envelope",
+  "envelope-simple-open",
+  "eye",
+  "eye-slash",
+  "file-arrow-down",
+  "file-arrow-up",
+  "files",
+  "first-aid-kit",
+  "flask",
+  "floppy-disk",
+  "folder",
+  "folder-open",
+  "funnel-simple",
+  "git-diff",
+  "github-logo",
+  "globe",
+  "graph",
+  "grid-four",
+  "hammer",
+  "hand",
+  "hard-drive-download",
+  "hard-drives",
+  "heart",
+  "hourglass",
+  "info",
+  "laptop",
+  "leaf",
+  "lightbulb",
+  "lightning",
+  "link",
+  "list",
+  "magnifying-glass",
+  "microphone",
+  "minus-circle",
+  "navigation-arrow",
+  "palette",
+  "paper-plane",
+  "paper-plane-tilt",
+  "paperclip",
+  "paw-print",
+  "pencil",
+  "pencil-simple",
+  "person",
+  "play-circle",
+  "plus",
+  "plus-circle",
+  "pulse",
+  "push-pin",
+  "puzzle-piece",
+  "qr-code",
+  "question",
+  "radio-button",
+  "resize",
+  "robot",
+  "rocket",
+  "share",
+  "sign-in",
+  "sign-out",
+  "sliders-horizontal",
+  "sparkle",
+  "speaker-high",
+  "speaker-slash",
+  "speedometer",
+  "squares-four",
+  "stack",
+  "stack-simple",
+  "star",
+  "terminal",
+  "text-aa",
+  "timer",
+  "toggle-right",
+  "translate",
+  "trash",
+  "tray",
+  "user-circle",
+  "warning",
+  "warning-circle",
+  "wifi-high",
+  "windows-logo",
+  "wrench"
+]

package/src/components/Icon/types.ts

@@ -1,8 +1,12 @@
 import type {ColorToken, IconSize} from '@duro-app/tokens/keys'
 
+import type {PhosphorIconName} from './phosphor-glyphs'
+
 export type {IconSize}
 
+/** Duro's own glyphs, then the Phosphor-generated ones Happier's React Native icon names use. */
 export type IconName =
+  | PhosphorIconName
   | 'x-circle'
   | 'check-circle'
   | 'check-done'

package/src/components/List/ItemLink.native.tsx

@@ -0,0 +1,60 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+// Explicit suffix: a native-only module has no web file for moduleSuffixes to pair.
+import {followLink} from '../../shared/followLink.native'
+import type {OnNavigate} from '../../shared/navigate'
+import {styles} from './styles.css'
+
+/** Nothing to share on native: the link answers its own press and stops it there. */
+export type ItemLinkState = Record<string, never>
+
+export function createItemLinkState(): ItemLinkState {
+  return {}
+}
+
+/** The modifier keys of the row's press (unused on native). */
+export interface RowPress {
+  altKey: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+  shiftKey: boolean
+  button: number
+}
+
+interface ItemLinkProps {
+  state: ItemLinkState
+  href: string
+  onNavigate: OnNavigate | undefined
+  children: ReactNode
+}
+
+/**
+ * The Content of a List.Item with an href, on native (ADR-0002, native addendum): a
+ * `role="link"` that renders no `href` and follows the press through `followLink`.
+ */
+export function ItemLink({href, onNavigate, children}: ItemLinkProps) {
+  return (
+    <html.div
+      role="link"
+      onClick={(event) => {
+        // Stopped, so the row never follows it a second time (native has no window listener
+        // a stopped press could hide).
+        event.stopPropagation()
+        followLink(href, onNavigate, 'List.Item')
+      }}
+      style={[styles.content, styles.contentLink]}
+    >
+      {children}
+    </html.div>
+  )
+}
+
+/** A press on the row reaches here only from outside the link: it follows the link. */
+export function pressItemLink(
+  _state: ItemLinkState,
+  href: string,
+  onNavigate: OnNavigate | undefined,
+  _event: RowPress,
+) {
+  followLink(href, onNavigate, 'List.Item')
+}

package/src/components/List/ItemLink.tsx

@@ -0,0 +1,80 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {linkClickHandler, type OnNavigate} from '../../shared/navigate'
+import {styles} from './styles.css'
+
+/** What a link row shares with its link: the anchor, and whether the press was the link's. */
+export interface ItemLinkState {
+  anchor: HTMLAnchorElement | null
+  linkPressed: boolean
+}
+
+export function createItemLinkState(): ItemLinkState {
+  return {anchor: null, linkPressed: false}
+}
+
+/** The modifier keys and button of the row's press, replayed on the link. */
+export interface RowPress {
+  altKey: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+  shiftKey: boolean
+  button: number
+}
+
+interface ItemLinkProps {
+  state: ItemLinkState
+  href: string
+  onNavigate: OnNavigate | undefined
+  children: ReactNode
+}
+
+/** The Content of a List.Item with an href: a real `<a href>` (ADR-0002). */
+export function ItemLink({state, href, onNavigate, children}: ItemLinkProps) {
+  const handler = linkClickHandler(href, onNavigate)
+  return (
+    <html.a
+      ref={(anchor: HTMLAnchorElement | null) => {
+        state.anchor = anchor
+      }}
+      href={href}
+      onClick={(event) => {
+        // Marked rather than stopped: stopping it would hide the click from window listeners.
+        state.linkPressed = true
+        handler?.(event)
+      }}
+      style={[styles.content, styles.contentLink]}
+    >
+      {children}
+    </html.a>
+  )
+}
+
+/**
+ * A press on the row: the link's own press bubbling up is left alone; any other (the Leading
+ * icon, the padding) is replayed on the anchor with the same button and modifier keys, so the
+ * browser and `onNavigate` see one link click (a cmd-click still opens a tab, ADR-0002).
+ */
+export function pressItemLink(
+  state: ItemLinkState,
+  _href: string,
+  _onNavigate: OnNavigate | undefined,
+  press: RowPress,
+) {
+  if (state.linkPressed) {
+    state.linkPressed = false
+    return
+  }
+  const {altKey, ctrlKey, metaKey, shiftKey, button} = press
+  state.anchor?.dispatchEvent(
+    new MouseEvent('click', {
+      bubbles: true,
+      cancelable: true,
+      altKey,
+      ctrlKey,
+      metaKey,
+      shiftKey,
+      button,
+    }),
+  )
+}

package/src/components/List/List.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Vertical list of interactive items. Ideal for narrow spaces (detail panels, sidebars) where Table would truncate. Supports selection, descriptions, and action slots. An Item with onClick is pressable anywhere on its row, and its Content becomes a button: focusable, pressed with Enter or Space, announced with its text, disabled with the Item; the Actions stay beside it, so a Button there never nests in it.',
+    'Vertical list of interactive items. Ideal for narrow spaces (detail panels, sidebars) where Table would truncate. Supports selection, descriptions, and action slots. An Item with onClick is pressable anywhere on its row, and its Content becomes a button: focusable, pressed with Enter or Space, announced with its text, disabled with the Item; the Actions stay beside it, so a Button there never nests in it. An Item with href (and onNavigate for client-side routing, ADR-0002) makes its Content a real link instead: a settings-style row that goes somewhere; a disabled link Item is plain text. List.Leading holds an icon or an Avatar before the Content (decorative unless given an aria-label). List.Root takes a title, which names the list, and a footer of muted text under it.',
   whenToUse: [
     'Displaying items in a narrow container (< 480px)',
     'Detail panels, drawers, and sidebars',
@@ -10,12 +10,12 @@ export const meta: ComponentMeta = {
   ],
   whenNotToUse: [
     'Tabular data with many columns — use Table',
-    'Navigation menus — use SideNav or Menu',
+    "An app's main navigation — use SideNav or AppShell (a List of link Items is for rows that each open a page, like a settings index)",
     'Simple text lists without interaction — use Stack with Text',
   ],
   anatomy: {
     required: ['Root', 'Item', 'Content', 'Text'],
-    optional: ['Description', 'Actions', 'Empty'],
+    optional: ['Leading', 'Description', 'Actions', 'Empty'],
   },
   relatedTo: [
     {

package/src/components/List/List.stories.tsx

@@ -1,8 +1,12 @@
 import type {Meta, StoryObj} from '@storybook/react'
 import {useState} from 'react'
-import {expect} from 'storybook/test'
+import {expect, fn} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {List} from './List'
+import {clickLink} from '../../docs/clickLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+import type {OnNavigate} from '../../shared/navigate'
+import {Icon} from '../Icon/Icon'
 import {Badge} from '../Badge/Badge'
 import {Button} from '../Button/Button'
 import {Checkbox} from '../Checkbox/Checkbox'
@@ -275,3 +279,89 @@ export const ClickableItems: Story = {
     await expect(buttons[2]).toBeDisabled()
   },
 }
+
+/**
+ * Settings-style rows: each Item with an `href` is a real link (its Content), with a
+ * category-coloured icon in the Leading slot, a title naming the list and a footer under it.
+ * `onNavigate` gets a plain primary click; a modified click keeps the browser default.
+ */
+export const LinkItems: StoryObj<{onNavigate: OnNavigate}> = {
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  args: {onNavigate: fn()},
+  render: (args) => (
+    <List.Root title="Account" footer="Signed in on this device.">
+      <List.Item href="#account" onNavigate={args.onNavigate}>
+        <List.Leading>
+          <Icon name="user-circle" size="md" color="categoryBlue" />
+        </List.Leading>
+        <List.Content>
+          <List.Text>Account</List.Text>
+          <List.Description>Profile, sign-in, devices</List.Description>
+        </List.Content>
+      </List.Item>
+      <List.Item href="#appearance" onNavigate={args.onNavigate}>
+        <List.Leading>
+          <Icon name="palette" size="md" color="categoryIndigo" />
+        </List.Leading>
+        <List.Content>
+          <List.Text>Appearance</List.Text>
+        </List.Content>
+      </List.Item>
+      <List.Item href="#usage" disabled>
+        <List.Leading>
+          <Icon name="chart-line" size="md" color="categoryOrange" />
+        </List.Leading>
+        <List.Content>
+          <List.Text>Usage</List.Text>
+        </List.Content>
+      </List.Item>
+    </List.Root>
+  ),
+  play: async ({args, canvas}) => {
+    const onNavigate = args.onNavigate as unknown as ReturnType<typeof fn>
+    onNavigate.mockImplementation((_href: string, event: {preventDefault(): void}) =>
+      event.preventDefault(),
+    )
+    // The title names the list; the footer follows it.
+    await expect(canvas.getByRole('list', {name: 'Account'})).toBeInTheDocument()
+    await expect(canvas.getByText('Signed in on this device.')).toBeInTheDocument()
+
+    const account = canvas.getByRole('link', {name: /Account/})
+    await expect(account).toHaveAttribute('href', '#account')
+    await expect(clickLink(account).defaultPrevented).toBe(true)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+    await expect(onNavigate.mock.calls[0][0]).toBe('#account')
+    for (const init of [{metaKey: true}, {ctrlKey: true}, {shiftKey: true}]) {
+      await expect(clickLink(account, init).defaultPrevented).toBe(false)
+    }
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+
+    // A press on the row outside the text (its Leading icon) follows the link once.
+    const appearanceRow = canvas
+      .getByRole('link', {name: 'Appearance'})
+      .closest('[role="listitem"]')
+    ;(appearanceRow?.firstElementChild as HTMLElement).click()
+    await expect(onNavigate).toHaveBeenCalledTimes(2)
+    await expect(onNavigate.mock.calls[1][0]).toBe('#appearance')
+    // A cmd-click there keeps the browser default (a new tab), as on the link itself.
+    const leading = appearanceRow?.firstElementChild as HTMLElement
+    let replayed = false
+    const onWindowClick = (event: MouseEvent) => {
+      // The replayed anchor click, then the outer click on the icon: keep the first answer.
+      if (event.target instanceof HTMLAnchorElement) {
+        replayed = event.metaKey && !event.defaultPrevented
+      }
+      event.preventDefault()
+    }
+    window.addEventListener('click', onWindowClick)
+    leading.dispatchEvent(new MouseEvent('click', {bubbles: true, cancelable: true, metaKey: true}))
+    window.removeEventListener('click', onWindowClick)
+    await expect(replayed).toBe(true)
+    await expect(onNavigate).toHaveBeenCalledTimes(2)
+
+    // A disabled link item is plain text, not a link; the Leading icon is decorative.
+    await expect(canvas.getAllByRole('link')).toHaveLength(2)
+    await expect(canvas.queryByRole('link', {name: 'Usage'})).toBeNull()
+  },
+}

package/src/components/List/List.tsx

@@ -1,5 +1,13 @@
-import {type ReactNode, createContext, useContext, useMemo} from 'react'
+import {type ReactNode, createContext, useContext, useId, useMemo, useState} from 'react'
 import {html} from 'react-strict-dom'
+import type {OnNavigate} from '../../shared/navigate'
+import {
+  ItemLink,
+  createItemLinkState,
+  pressItemLink,
+  type ItemLinkState,
+  type RowPress,
+} from './ItemLink'
 import {styles} from './styles.css'
 
 // --- Types ---
@@ -24,47 +32,115 @@ interface RootProps {
   children: ReactNode
   /** Selection mode: 'none' (default), 'single', or 'multiple' */
   selectionMode?: ListSelectionMode
-  /** Accessible label for the list */
+  /** Accessible label for the list; a `title` names the list instead. */
   'aria-label'?: string
+  /** A heading-styled label above the list, which also names the list (aria-labelledby). */
+  title?: ReactNode
+  /** Muted text after the list: a count, a hint, a note. */
+  footer?: ReactNode
 }
 
-function Root({children, selectionMode = 'none', 'aria-label': ariaLabel}: RootProps) {
+function Root({
+  children,
+  selectionMode = 'none',
+  'aria-label': ariaLabel,
+  title,
+  footer,
+}: RootProps) {
+  const titleId = useId()
+  const hasTitle = title != null
+  const list = (
+    <html.div
+      role="list"
+      aria-label={hasTitle ? undefined : ariaLabel}
+      aria-labelledby={hasTitle ? titleId : undefined}
+      style={styles.root}
+    >
+      {children}
+    </html.div>
+  )
   return (
     <ListContext.Provider value={{selectionMode}}>
-      <html.div role="list" aria-label={ariaLabel} style={styles.root}>
-        {children}
-      </html.div>
+      {hasTitle || footer != null ? (
+        <html.div style={styles.frame}>
+          {hasTitle ? (
+            <html.p id={titleId} style={styles.title}>
+              {title}
+            </html.p>
+          ) : null}
+          {list}
+          {footer != null ? <html.p style={styles.footer}>{footer}</html.p> : null}
+        </html.div>
+      ) : (
+        list
+      )}
     </ListContext.Provider>
   )
 }
 
 // --- Item ---
 
-interface ItemProps {
+interface ItemBaseProps {
   children: ReactNode
   /** Whether this item is selected */
   selected?: boolean
   /** Whether this item is disabled */
   disabled?: boolean
+}
+
+interface PressItemProps extends ItemBaseProps {
   /** Click handler for the item */
   onClick?: () => void
+  href?: undefined
+  onNavigate?: undefined
 }
 
-// What a clickable Item hands its Content, which becomes the item's button.
-interface ItemActionValue {
-  onClick: () => void
-  disabled: boolean
+interface LinkItemProps extends ItemBaseProps {
+  /**
+   * Makes the item's Content a link: a real `<a href>` on the web (a press through
+   * `followLink` on native, ADR-0002). An item is a link or pressable, never both: `href`
+   * excludes `onClick`.
+   */
+  href: string
+  /**
+   * Client-side navigation: called for a plain primary click (no modifier key); the browser
+   * default runs for every other click. Call `event.preventDefault()`, then your router's
+   * navigate. On native, without it a relative href goes to the system.
+   */
+  onNavigate?: OnNavigate
+  onClick?: undefined
 }
 
-const ItemActionContext = createContext<ItemActionValue | null>(null)
+type ItemProps = PressItemProps | LinkItemProps
+
+// What a pressable or linked Item hands its Content, which becomes the item's button or link.
+type ItemAction =
+  | {kind: 'press'; onClick: () => void; disabled: boolean}
+  | {
+      kind: 'link'
+      href: string
+      onNavigate: OnNavigate | undefined
+      disabled: boolean
+      linkState: ItemLinkState
+    }
 
-function Item({children, selected, disabled, onClick}: ItemProps) {
+const ItemActionContext = createContext<ItemAction | null>(null)
+
+function Item({children, selected, disabled, onClick, href, onNavigate}: ItemProps) {
   const {selectionMode} = useList()
   const isSelectable = selectionMode !== 'none'
-  const action = useMemo(
-    () => (onClick ? {onClick, disabled: disabled === true} : null),
-    [onClick, disabled],
-  )
+  const isDisabled = disabled === true
+  const [linkState] = useState(createItemLinkState)
+  const action = useMemo<ItemAction | null>(() => {
+    if (href !== undefined) return {kind: 'link', href, onNavigate, disabled: isDisabled, linkState}
+    return onClick ? {kind: 'press', onClick, disabled: isDisabled} : null
+  }, [href, onNavigate, onClick, isDisabled, linkState])
+  // A press anywhere on a link row (its Leading icon, its padding) follows the link, as a
+  // settings row does; a press on the Content's link is the link's own.
+  const onRowClick =
+    href !== undefined
+      ? (press: RowPress) => pressItemLink(linkState, href, onNavigate, press)
+      : onClick
 
   return (
     <ItemActionContext.Provider value={action}>
@@ -72,12 +148,12 @@ function Item({children, selected, disabled, onClick}: ItemProps) {
         role="listitem"
         aria-selected={isSelectable ? selected : undefined}
         aria-disabled={disabled || undefined}
-        // A press anywhere on the row; the Content's button is what keyboards and screen
-        // readers reach.
-        onClick={disabled ? undefined : onClick}
+        // A press anywhere on the row; the Content's button or link is what keyboards and
+        // screen readers reach.
+        onClick={disabled ? undefined : onRowClick}
         style={[
           styles.item,
-          onClick != null && !disabled && styles.itemClickable,
+          (onClick != null || href !== undefined) && !disabled && styles.itemClickable,
           selected && styles.itemSelected,
           disabled && styles.itemDisabled,
         ]}
@@ -92,7 +168,17 @@ function Item({children, selected, disabled, onClick}: ItemProps) {
 
 function Content({children}: {children: ReactNode}) {
   const action = useContext(ItemActionContext)
-  if (!action) return <html.div style={styles.content}>{children}</html.div>
+  // A disabled link is plain text: an anchor without an href is not a link.
+  if (!action || (action.kind === 'link' && action.disabled)) {
+    return <html.div style={styles.content}>{children}</html.div>
+  }
+  if (action.kind === 'link') {
+    return (
+      <ItemLink state={action.linkState} href={action.href} onNavigate={action.onNavigate}>
+        {children}
+      </ItemLink>
+    )
+  }
   // In a clickable Item the Content is a real button: focusable, pressed with Enter or Space,
   // announced with its text. The Actions stay beside it, never nested inside.
   return (
@@ -111,6 +197,27 @@ function Content({children}: {children: ReactNode}) {
   )
 }
 
+// --- Leading: icon or avatar before the Content ---
+
+interface LeadingProps {
+  children: ReactNode
+  /** Names the slot for assistive tech; without it the slot is decorative and hidden from it. */
+  'aria-label'?: string
+}
+
+function Leading({children, 'aria-label': ariaLabel}: LeadingProps) {
+  return (
+    <html.div
+      role={ariaLabel ? 'img' : undefined}
+      aria-label={ariaLabel}
+      aria-hidden={ariaLabel ? undefined : true}
+      style={styles.leading}
+    >
+      {children}
+    </html.div>
+  )
+}
+
 // --- Text: primary label ---
 
 function ItemText({children}: {children: ReactNode}) {
@@ -144,6 +251,7 @@ function Empty({children}: {children: ReactNode}) {
 export const List = {
   Root,
   Item,
+  Leading,
   Content,
   Text: ItemText,
   Description,

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

@@ -14,6 +14,30 @@ export const styles = css.create({
     padding: 0,
   },
 
+  // Wraps the Root when it has a title or a footer.
+  frame: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacing.xs,
+  },
+  title: {
+    fontSize: typography.fontSizeSm,
+    fontWeight: typography.fontWeightSemibold,
+    lineHeight: typography.lineHeight,
+    color: colors.text,
+    margin: 0,
+    paddingLeft: spacing.ms,
+    paddingRight: spacing.ms,
+  },
+  footer: {
+    fontSize: typography.fontSizeXs,
+    lineHeight: typography.lineHeight,
+    color: colors.textMuted,
+    margin: 0,
+    paddingLeft: spacing.ms,
+    paddingRight: spacing.ms,
+  },
+
   // --- Item ---
   item: {
     display: 'flex',
@@ -78,6 +102,27 @@ export const styles = css.create({
     borderRadius: radii.xs,
   },
 
+  // The Content of an Item with an href: an anchor that reads as the row's text.
+  contentLink: {
+    textDecorationLine: 'none',
+    color: 'inherit',
+    cursor: 'pointer',
+    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},
+    borderRadius: radii.xs,
+  },
+
+  // --- Leading slot (icon or avatar) ---
+  leading: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    color: colors.textMuted,
+  },
+
   // --- Primary text ---
   text: {
     fontSize: typography.fontSizeSm,