@duro-app/ui 5.17.0 → 5.19.0

package/dist/shared/InLandmarkContext.d.ts

@@ -0,0 +1,7 @@
+/**
+ * True inside `AppShell.Rail`, which is already a named navigation landmark.
+ * A `SideNav.Root` reads it and renders no second navigation landmark: a plain
+ * block, or `role="group"` carrying its `aria-label` when it has one.
+ */
+export declare const InLandmarkContext: import('react').Context<boolean>;
+//# sourceMappingURL=InLandmarkContext.d.ts.map

package/dist/shared/InLandmarkContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InLandmarkContext.d.ts","sourceRoot":"","sources":["../../src/shared/InLandmarkContext.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,kCAAuB,CAAA"}

package/dist/shared/navigate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigate.d.ts","sourceRoot":"","sources":["../../src/shared/navigate.ts"],"names":[],"mappings":"AAgBA,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,cAAc,IAAI,IAAI,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;AAEtE,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,CAAC,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC,GAAG,SAAS,CAM/C"}
+{"version":3,"file":"navigate.d.ts","sourceRoot":"","sources":["../../src/shared/navigate.ts"],"names":[],"mappings":"AAkBA,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,cAAc,IAAI,IAAI,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;AAEtE,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,CAAC,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC,GAAG,SAAS,CAM/C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.17.0",
+  "version": "5.19.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -90,9 +90,9 @@
     }
   },
   "dependencies": {
-    "@tanstack/react-virtual": "^3.14.6",
+    "@tanstack/react-virtual": "^3.14.13",
     "qrcode": "^1.5.4",
-    "@duro-app/tokens": "^5.17.0"
+    "@duro-app/tokens": "^5.19.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/AppShell/AppShell.native.tsx

@@ -14,6 +14,7 @@ import {Button} from '../Button/Button'
 import {Drawer} from '../Drawer/Drawer'
 import {Icon} from '../Icon'
 import {useSafeAreaInsets} from '../../shared/safeArea'
+import {InLandmarkContext} from '../../shared/InLandmarkContext'
 import {nativeStyles} from './native.css'
 
 export type AppShellCollapse = 'sm' | 'md' | 'lg'
@@ -117,20 +118,22 @@ function Rail({'aria-label': ariaLabel, children, footer}: RailProps) {
   const foot = typeof footer === 'function' ? footer({close}) : footer
 
   return (
-    <Drawer.Root anchor="left" open={open} onOpenChange={setOpen}>
-      <Drawer.Portal size="sm">
-        <Drawer.Header>
-          <Drawer.Title>{ariaLabel}</Drawer.Title>
-          <Drawer.Close aria-label={closeLabel} />
-        </Drawer.Header>
-        <Drawer.Body>
-          <html.nav aria-label={ariaLabel}>
-            {content}
-            {foot != null && <html.div style={nativeStyles.drawerFooter}>{foot}</html.div>}
-          </html.nav>
-        </Drawer.Body>
-      </Drawer.Portal>
-    </Drawer.Root>
+    <InLandmarkContext.Provider value={true}>
+      <Drawer.Root anchor="left" open={open} onOpenChange={setOpen}>
+        <Drawer.Portal size="sm">
+          <Drawer.Header>
+            <Drawer.Title>{ariaLabel}</Drawer.Title>
+            <Drawer.Close aria-label={closeLabel} />
+          </Drawer.Header>
+          <Drawer.Body>
+            <html.nav aria-label={ariaLabel}>
+              {content}
+              {foot != null && <html.div style={nativeStyles.drawerFooter}>{foot}</html.div>}
+            </html.nav>
+          </Drawer.Body>
+        </Drawer.Portal>
+      </Drawer.Root>
+    </InLandmarkContext.Provider>
   )
 }
 

package/src/components/AppShell/AppShell.stories.tsx

@@ -348,12 +348,41 @@ export const DesktopLandmarks: Story = {
     await expect(canvas.getAllByRole('banner')).toHaveLength(1)
     const names = canvas.getAllByRole('navigation').map((nav) => nav.getAttribute('aria-label'))
     await expect(new Set(names).size).toBe(names.length)
+    // the SideNav inside the rail is a group, not a second navigation landmark
+    await expect(canvas.getAllByRole('navigation')).toHaveLength(1)
     await expect(canvas.queryByRole('button', {name: args.menuLabel})).toBeNull()
     // the brand is the rail's copy
     await expect(rail.contains(canvas.getByRole('link', {name: args.brand}))).toBe(true)
   },
 }
 
+/**
+ * A SideNav without an `aria-label` inside a labelled Rail: the Rail is the one
+ * navigation landmark, the SideNav adds none.
+ */
+export const RailWithUnlabelledSideNav: Story = {
+  tags: TEST_ONLY,
+  render: ({width}) => (
+    <Frame px={FRAME_PX[width]}>
+      <AppShell.Root menuLabel="Menu" closeLabel="Close navigation" skipLabel="Skip to content">
+        <AppShell.Rail aria-label="Main">
+          <SideNav.Root defaultValue="/">
+            <SideNav.Item value="/">Dashboard</SideNav.Item>
+            <SideNav.Item value="/articles">Articles</SideNav.Item>
+          </SideNav.Root>
+        </AppShell.Rail>
+        <AppShell.Main>
+          <Heading level={1}>Docs</Heading>
+        </AppShell.Main>
+      </AppShell.Root>
+    </Frame>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getAllByRole('navigation')).toHaveLength(1)
+    await expect(canvas.getByRole('navigation', {name: 'Main'})).toBeVisible()
+  },
+}
+
 /**
  * The Menu button opens the rail in a Drawer. Focus moves into the drawer,
  * and back to the Menu button when it closes — by Escape, and after a pick.
@@ -368,6 +397,7 @@ export const PhoneDrawer: Story = {
     await expect(menu).toHaveAttribute('aria-expanded', 'true')
     const drawerNav = within(dialog).getByRole('navigation', {name: 'Navigation'})
     await waitFor(() => expect(drawerNav.contains(document.activeElement)).toBe(true))
+    await expect(within(dialog).getAllByRole('navigation')).toHaveLength(1)
     // the rail's content is rendered once, in the drawer while it is open:
     // counted in the DOM (a hidden copy would still duplicate a Tree's ids)
     await expect(page().getAllByText('Articles')).toHaveLength(1)

package/src/components/AppShell/AppShell.tsx

@@ -20,6 +20,7 @@ import {Icon} from '../Icon'
 import {TextLink} from '../TextLink/TextLink'
 import {useContainerBelow} from '../../hooks/useContainerBelow'
 import type {OnNavigate} from '../../shared/navigate'
+import {InLandmarkContext} from '../../shared/InLandmarkContext'
 import {styles} from './styles.css'
 
 /* AppShell — an application's frame: a navigation rail beside the main
@@ -253,7 +254,7 @@ function Rail({'aria-label': ariaLabel, children, footer}: RailProps) {
   }, [open])
 
   return (
-    <>
+    <InLandmarkContext.Provider value={true}>
       {/* Rendered in one place at a time, so ids (a Tree's) and the landmark
           name are never duplicated: the drawer only opens below the collapse
           point, where the rail is hidden. The brand stays: the bar holds the
@@ -281,7 +282,7 @@ function Rail({'aria-label': ariaLabel, children, footer}: RailProps) {
           </Drawer.Body>
         </Drawer.Portal>
       </Drawer.Root>
-    </>
+    </InLandmarkContext.Provider>
   )
 }
 

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

@@ -9,7 +9,7 @@ import {
   useId,
   useRef,
 } from 'react'
-import {Linking, Platform, Pressable, ScrollView, StyleSheet} from 'react-native'
+import {Platform, Pressable, ScrollView, StyleSheet} from 'react-native'
 import {html} from 'react-strict-dom'
 import {SIZES_PX} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
@@ -18,7 +18,8 @@ import {useMenuOpen} from './useMenuOpen'
 import {AnchoredOverlay} from '../../shared/portal/AnchoredOverlay'
 import {focusForAccessibility} from '../../shared/accessibilityFocus'
 import {mergeRefs} from '../../shared/mergeRefs'
-import type {LinkClickEvent, OnNavigate} from '../../shared/navigate'
+import {followLink} from '../../shared/followLink.native'
+import type {OnNavigate} from '../../shared/navigate'
 import type {ControlSize} from '../../shared/types'
 import {useTooltipHint} from '../Tooltip/TooltipHint'
 import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
@@ -223,28 +224,7 @@ interface LinkItemProps {
 
 function LinkItem({href, onNavigate, children}: LinkItemProps) {
   const {closeThen} = useMenu()
-  const follow = () => {
-    let prevented = false
-    const event: LinkClickEvent = {
-      button: 0,
-      metaKey: false,
-      ctrlKey: false,
-      shiftKey: false,
-      altKey: false,
-      get defaultPrevented() {
-        return prevented
-      },
-      preventDefault() {
-        prevented = true
-      },
-    }
-    onNavigate?.(href, event)
-    if (!prevented) {
-      Linking.openURL(href).catch((error: unknown) => {
-        console.warn(`[duro] Menu.LinkItem: could not open ${href}: ${String(error)}`)
-      })
-    }
-  }
+  const follow = () => followLink(href, onNavigate, 'Menu.LinkItem')
   return (
     <Pressable accessibilityRole="link" onPress={() => closeThen(follow)}>
       {({pressed}) => (

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

@@ -8,8 +8,12 @@ export const nativeStyles = css.create({
   nativeFlex: {
     display: 'flex',
   },
+  // The shared popup's `zIndex: layers.popup` is the CSS string '1050', which Android's
+  // view manager refuses (iOS ignores it). The popup sits alone in an OverlayModal
+  // window, where web layering has no job: a number is all it needs.
   popupInPlace: {
     position: 'relative',
+    zIndex: 0,
   },
   // A press shows the highlight that hover and the arrow keys show on the web.
   itemPressed: {

package/src/components/Panel/Panel.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Structural primitive for grouping content with header, body, and footer slots. A "workspace surface" for forms, settings sections, and inspectors. Sub-components are purely structural — no context required.',
+    'Structural primitive for grouping content with header, body, and footer slots. A "workspace surface" for forms, settings sections, and inspectors. Sub-components are purely structural — no context required. On native the Body does not scroll (unlike the web Body): wrap long content in ScrollArea. A TextLink inside needs onNavigate for in-app routes on native.',
   whenToUse: [
     'Organizing content with distinct header/body/footer sections',
     'Settings panels, form containers, inspector views',

package/src/components/Popover/native.css.ts

@@ -7,7 +7,11 @@ export const nativeStyles = css.create({
   nativeFlex: {
     display: 'flex',
   },
+  // The shared popup's `zIndex: layers.floating` is the CSS string '50', which Android's
+  // view manager refuses (iOS ignores it). The popup sits alone in an OverlayModal
+  // window, where web layering has no job: a number is all it needs.
   popupInPlace: {
     position: 'relative',
+    zIndex: 0,
   },
 })

package/src/components/SideNav/SideNav.meta.ts

@@ -4,6 +4,7 @@ export const meta: ComponentMeta = {
   description:
     'Vertical side navigation. `Section` is a labelled block that is always open — the default for primary navigation. `Group` is the same block behind a chevron (a disclosure) — reach for it only for a rare/advanced region, an unbounded data-driven list, or a rail long enough that flat stops reading as an overview; mixing the two in one rail is the healthy shape. `Item`s take an optional `icon` and show an active left-marker. Supports controlled and uncontrolled active item. Compound component — Root is required. On React Native the same parts render, and a Group knows whether it holds the active item from its Items, not from the DOM.',
   whenToUse: [
+    'Inside `AppShell.Rail`: the Rail is the navigation landmark, so Root renders a plain block, or `role="group"` with its `aria-label` when it has one. Name the Rail "Main", not "Navigation" (screen readers would announce "Navigation navigation"). Outside a Rail, Root is a `nav` landmark.',
     'App-level sidebar navigation — flat `Section`s, every destination visible',
     'Settings navigation with labelled regions',
     '`Group` for a rare or advanced region tucked below the flat sections',

package/src/components/SideNav/SideNav.tsx

@@ -13,6 +13,7 @@ import {styles} from './styles.css'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {SideNavContext, useSideNav} from './SideNavContext'
 import {isNative} from '../../platform'
+import {InLandmarkContext} from '../../shared/InLandmarkContext'
 import {Chevron} from './Chevron'
 
 /** A Group's own items: each Item inside it registers its value here. */
@@ -51,7 +52,8 @@ interface RootProps {
   /**
    * Names the navigation landmark ("Main", "Settings"). Give one whenever
    * the page has another nav (a breadcrumb, a pager): screen readers list
-   * landmarks by name.
+   * landmarks by name. Inside `AppShell.Rail` it is not a landmark (the Rail
+   * is): the name then labels a `role="group"`.
    */
   'aria-label'?: string
   value?: string
@@ -75,6 +77,7 @@ function Root({
         }
       : undefined,
   )
+  const inLandmark = useContext(InLandmarkContext)
   const [expandedGroups, setExpandedGroups] = useState<Set<string>>(new Set())
   const orderRef = useRef<string[]>([])
 
@@ -124,9 +127,20 @@ function Root({
         orderRef,
       }}
     >
-      <html.nav role="navigation" aria-label={ariaLabel} style={styles.root}>
-        {children}
-      </html.nav>
+      {inLandmark ? (
+        // AppShell.Rail is already the navigation landmark: keep the name as a group.
+        <html.div
+          role={ariaLabel != null ? 'group' : undefined}
+          aria-label={ariaLabel}
+          style={styles.root}
+        >
+          {children}
+        </html.div>
+      ) : (
+        <html.nav role="navigation" aria-label={ariaLabel} style={styles.root}>
+          {children}
+        </html.nav>
+      )}
     </SideNavContext.Provider>
   )
 }

package/src/components/TextLink/TextLink.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Inline hyperlink for running text and standalone text links ("View all", "Edit profile"). Always underlined, so colour is never the only cue: default is accent text with an accent underline; subtle keeps the surrounding text colour with a muted underline and turns accent on hover. target="_blank" defaults rel to noopener noreferrer. onNavigate(href, event) hands a plain primary click to a client router (the app calls event.preventDefault(), then navigates); modified clicks keep the browser default.',
+    'Inline hyperlink for running text and standalone text links ("View all", "Edit profile"). Always underlined, so colour is never the only cue: default is accent text with an accent underline; subtle keeps the surrounding text colour with a muted underline and turns accent on hover. target="_blank" defaults rel to noopener noreferrer. onNavigate(href, event) hands a plain primary click to a client router (the app calls event.preventDefault(), then navigates); modified clicks keep the browser default. On native the link renders no href and a press goes through onNavigate, then the system (Linking.openURL): onNavigate is required for in-app routes on native, and a target set skips it.',
   whenToUse: [
     'A link inside a sentence or paragraph',
     'A standalone text link under a list or card ("View all requests")',

package/src/components/TextLink/TextLink.native.tsx

@@ -0,0 +1,55 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {nativeStyles} from './native.css'
+// 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'
+
+export type TextLinkVariant = 'default' | 'subtle'
+
+interface TextLinkProps {
+  href: string
+  /** `_blank` hands the URL to the system; `onNavigate` is then not called. */
+  target?: '_blank' | '_self'
+  /** Ignored on native: there is no `rel`. */
+  rel?: string
+  variant?: TextLinkVariant
+  /** Accessible name, when the visible text alone does not say where it goes. */
+  'aria-label'?: string
+  /**
+   * Client-side navigation: called for a press on a link with no `target`.
+   * Call `event.preventDefault()`, then your router's navigate. Required for
+   * an in-app route on native: without it, the URL opens with the system.
+   */
+  onNavigate?: OnNavigate
+  children: ReactNode
+}
+
+/**
+ * Native TextLink (ADR-0002): an inline `Text` with `role="link"` that renders
+ * NO `href`, and follows the link through `followLink` on press.
+ *
+ * holds-until: a react-strict-dom release forwards the press of an `html.a`
+ * that has an `href` (react/react-strict-dom#58). Until then RSD 0.0.55
+ * replaces that `onPress` with a dev-only "href handling is not implemented"
+ * stub (dist/native/index.js:3094-3100), so `href` stays off the element and
+ * scripts/check-native-graph.mjs refuses it. Then: pass `href`, drop the rule.
+ */
+export function TextLink({
+  href,
+  target,
+  variant = 'default',
+  'aria-label': ariaLabel,
+  onNavigate,
+  children,
+}: TextLinkProps) {
+  return (
+    <html.a
+      aria-label={ariaLabel}
+      onClick={() => followLink(href, target ? undefined : onNavigate, 'TextLink')}
+      style={[nativeStyles.base, nativeStyles[variant]]}
+    >
+      {children}
+    </html.a>
+  )
+}

package/src/components/TextLink/native.css.ts

@@ -0,0 +1,36 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+
+// Native TextLink: the same colour and underline facts as ./styles.css.ts —
+// change both together. A copy, not a composition: the web file's base style
+// carries transition* and :focus-visible outline keys that react-strict-dom
+// rejects on native, and its :hover state becomes :active (a press) here.
+export const nativeStyles = css.create({
+  base: {
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    lineHeight: 'inherit',
+    textDecorationLine: 'underline',
+    textDecorationStyle: 'solid',
+  },
+  default: {
+    color: {
+      default: colors.accent,
+      ':active': colors.accentHover,
+    },
+    textDecorationColor: {
+      default: colors.accent,
+      ':active': colors.accentHover,
+    },
+  },
+  subtle: {
+    color: {
+      default: 'inherit',
+      ':active': colors.accent,
+    },
+    textDecorationColor: {
+      default: colors.textMuted,
+      ':active': colors.accent,
+    },
+  },
+})

package/src/components/Tree/Tree.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. An Item with href renders its row as a real link (cmd-click opens a tab) outside the tab order; Enter/Space follows it, through onNavigate(href, event) when given. Compound component — Root is required. On React Native selection, expansion and aria-level are the same; the keyboard model (arrows, Home/End, typeahead) is web only.',
+    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. A click or Enter on a branch row with no href selects it and toggles it open or closed (a folder); a branch with href navigates, and its chevron toggles. An Item with href renders its row as a real link (cmd-click opens a tab) outside the tab order; Enter/Space follows it, through onNavigate(href, event) when given. Compound component — Root is required. On React Native each row is a pressable link (href) or button, and a branch has its own chevron control that expands it (named by the optional Root prop expandLabel(text), default the item text); selection, expansion and aria-level are the same, the keyboard model (arrows, Home/End, typeahead) is web only. On native onNavigate is required for in-app routes: without it a relative href goes to the system (Linking.openURL). On web a tree with more items than Root virtualizeThreshold (default 150, open or not) is windowed: only the rows in view mount, as flat treeitems with aria-level, aria-setsize and aria-posinset; maxHeight caps its scroll viewport. Items must be JSX descendants of Root (fragments and arrays are fine, an Item hidden inside another component is not seen by the window). Native renders every row.',
   whenToUse: [
     'Browsing data that nests to any depth — a file tree, zones › services › capabilities, namespace › resource',
     'Picking one node of a hierarchy to show its details beside the tree',