@duro-app/ui 5.13.0 → 5.14.0

package/src/components/Select/selectState.ts

@@ -0,0 +1,36 @@
+import {useCallback, useState} from 'react'
+import {useControllableValue} from '../../hooks/useControllableValue'
+
+export interface SelectStateOptions {
+  defaultValue?: string
+  value?: string
+  onValueChange?: (value: string | null) => void
+  initialLabels?: Record<string, string>
+}
+
+/**
+ * The Select's state both platforms share (plan N0, Decision 10): the value
+ * (controlled or not), whether it is open, and each option's label. Focus,
+ * highlight, document order and keys are the web adapter's (useSelectRoot);
+ * native presses and the sheet are Select.native's.
+ */
+export function useSelectState({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  initialLabels,
+}: SelectStateOptions) {
+  const [value, setValue] = useControllableValue<string | null>(
+    controlledValue,
+    defaultValue ?? null,
+    onValueChange,
+  )
+  const [open, setOpen] = useState(false)
+  const [labels, setLabels] = useState<Record<string, string>>(initialLabels ?? {})
+
+  const registerLabel = useCallback((v: string, label: string) => {
+    setLabels((prev) => (prev[v] === label ? prev : {...prev, [v]: label}))
+  }, [])
+
+  return {value, setValue, open, setOpen, labels, registerLabel}
+}

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

@@ -124,4 +124,15 @@ export const styles = css.create({
   hidden: {
     display: 'none',
   },
+  // Popup's `empty`: no items to choose from.
+  empty: {
+    paddingTop: spacing.md,
+    paddingBottom: spacing.md,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.textMuted,
+    textAlign: 'center',
+  },
 })

package/src/components/Select/useSelectRoot.ts

@@ -1,27 +1,13 @@
 import {useState, useCallback, useMemo, useRef, useId, useEffect} from 'react'
-import {useControllableValue} from '../../hooks/useControllableValue'
 import type {SelectContextValue} from './SelectContext'
+import {useSelectState, type SelectStateOptions} from './selectState'
 
-interface UseSelectRootOptions {
-  defaultValue?: string
-  value?: string
-  onValueChange?: (value: string | null) => void
-  initialLabels?: Record<string, string>
-}
-
-export function useSelectRoot({
-  defaultValue,
-  value: controlledValue,
-  onValueChange,
-  initialLabels,
-}: UseSelectRootOptions) {
-  const [value, setValue] = useControllableValue<string | null>(
-    controlledValue,
-    defaultValue ?? null,
-    onValueChange,
-  )
-  const [open, setOpen] = useState(false)
-  const [labels, setLabels] = useState<Record<string, string>>(initialLabels ?? {})
+/**
+ * The web adapter over the shared Select state: the highlighted option,
+ * document order, keys and DOM focus (the WAI-ARIA select-only combobox).
+ */
+export function useSelectRoot(options: SelectStateOptions) {
+  const {value, setValue, open, setOpen, labels, registerLabel} = useSelectState(options)
   const [highlightedId, setHighlightedId] = useState<string | null>(null)
   const listboxId = useId()
   const rootRef = useRef<HTMLDivElement>(null)
@@ -33,7 +19,7 @@ export function useSelectRoot({
     setOpen(false)
     setHighlightedId(null)
     triggerRef.current?.focus()
-  }, [])
+  }, [setOpen])
 
   const toggle = useCallback(() => {
     setOpen((prev) => {
@@ -54,14 +40,7 @@ export function useSelectRoot({
       }
       return !prev
     })
-  }, [value])
-
-  const registerLabel = useCallback((v: string, label: string) => {
-    setLabels((prev) => {
-      if (prev[v] === label) return prev
-      return {...prev, [v]: label}
-    })
-  }, [])
+  }, [value, setOpen])
 
   const registerItem = useCallback((id: string, itemValue: string, element: HTMLElement) => {
     itemsRef.current.set(id, {value: itemValue, element})

package/src/components/ThemeProvider/ThemeOverrides.stories.tsx

@@ -0,0 +1,113 @@
+import {useState} from 'react'
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, waitFor} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {ThemeProvider, type ColorOverrides, type ThemeName} from './ThemeProvider'
+import {Button} from '../Button/Button'
+import {Text} from '../Text/Text'
+
+const meta: Meta = {
+  title: 'Theme/ThemeProvider/Overrides',
+}
+
+export default meta
+
+const styles = css.create({
+  surface: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacing.sm,
+    padding: spacing.md,
+    backgroundColor: colors.bg,
+  },
+})
+
+interface OverrideArgs {
+  theme: ThemeName
+  bg: string
+  accent: string
+}
+
+/** Colours replaced by token key; the controls change them in place. */
+export const Playground: StoryObj<OverrideArgs> = {
+  args: {theme: 'dark', bg: '#1b2433', accent: '#ff5a1f'},
+  argTypes: {
+    theme: {control: 'inline-radio', options: ['dark', 'light', 'high-contrast']},
+    bg: {control: 'color', description: 'overrides.bg'},
+    accent: {control: 'color', description: 'overrides.accent'},
+  },
+  render: ({theme, bg, accent}) => (
+    <ThemeProvider theme={theme} overrides={{bg, accent}}>
+      <html.div style={styles.surface}>
+        <Text>The page background and the primary fill come from overrides.</Text>
+        <Button>Primary</Button>
+      </html.div>
+    </ThemeProvider>
+  ),
+}
+
+const A: ColorOverrides = {bg: 'rgb(27, 36, 51)', accent: 'rgb(255, 90, 31)'}
+const B: ColorOverrides = {bg: 'rgb(10, 60, 30)', accent: 'rgb(30, 144, 255)'}
+const STEPS: readonly (ColorOverrides | undefined)[] = [A, B, A, undefined]
+
+/** Steps through A, B, A and none, with a nested provider under each. */
+function Stepper() {
+  const [step, setStep] = useState(0)
+  const overrides = STEPS[step]
+  return (
+    <ThemeProvider overrides={overrides}>
+      <html.div data-testid="outer" style={styles.surface}>
+        <Button onClick={() => setStep((s) => Math.min(s + 1, STEPS.length - 1))}>Next</Button>
+        <ThemeProvider>
+          <html.div data-testid="inherits" style={styles.surface} />
+        </ThemeProvider>
+        <ThemeProvider overrides={{bg: 'rgb(60, 10, 60)', accent: 'red} body{background:red'}}>
+          <html.div data-testid="inner" style={styles.surface} />
+        </ThemeProvider>
+      </html.div>
+    </ThemeProvider>
+  )
+}
+
+const bgOf = (el: Element) => getComputedStyle(el).backgroundColor
+const aliasOf = (el: Element) => getComputedStyle(el).getPropertyValue('--duro-color-bg').trim()
+
+export const OverridesUpdateInPlace: StoryObj = {
+  render: () => <Stepper />,
+  play: async ({canvas, userEvent}) => {
+    const outer = canvas.getByTestId('outer')
+    const inherits = canvas.getByTestId('inherits')
+    const inner = canvas.getByTestId('inner')
+    const next = canvas.getByRole('button', {name: 'Next'})
+
+    // The outer provider's scope while it has overrides.
+    const provider = outer.parentElement!
+    await waitFor(() => expect(provider.getAttribute('data-duro-theme')).toBeTruthy())
+    const scope = provider.getAttribute('data-duro-theme')!
+
+    for (const step of [A, B, A]) {
+      await waitFor(() => expect(bgOf(outer)).toBe(step.bg))
+      // Button's fill eases between colours: wait for it to settle.
+      await waitFor(() => expect(getComputedStyle(next).backgroundColor).toBe(step.accent))
+      // The --duro-* alias follows the override.
+      await expect(aliasOf(outer)).toBe(step.bg)
+      // A nested provider with no overrides, same theme: the outer's colours.
+      await expect(bgOf(inherits)).toBe(step.bg)
+      await expect(aliasOf(inherits)).toBe(step.bg)
+      // A nested provider with its own: its colours inside, the outer's outside.
+      await expect(bgOf(inner)).toBe('rgb(60, 10, 60)')
+      await userEvent.click(next)
+    }
+
+    // No overrides: the theme's own colours, and no outer rule left.
+    await waitFor(() => expect(bgOf(outer)).toBe('rgb(15, 15, 15)'))
+    const rules = [...document.querySelectorAll('style')].map((s) => s.textContent ?? '')
+    await expect(provider.hasAttribute('data-duro-theme')).toBe(false)
+    await expect(rules.filter((r) => r.includes(`"${scope}"`))).toHaveLength(0)
+    // The invalid value never reaches a rule, and nothing leaked onto body.
+    await expect(rules.some((r) => r.includes('body{'))).toBe(false)
+    await expect(getComputedStyle(document.body).backgroundColor).not.toBe('rgb(255, 0, 0)')
+  },
+}

package/src/components/ThemeProvider/ThemeProvider.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Theme context provider. Must wrap the entire app at the root level. Sets dark, light, or high-contrast theme for all child components via CSS custom properties.',
+    'Theme context provider. Must wrap the entire app at the root level. Sets dark, light, or high-contrast theme for all child components via CSS custom properties. overrides replaces colours by token key ({accent: "#ff5a1f"}) and updates in place, without a re-mount: a scoped rule on the web (values that are not a colour are dropped), a runtime theme on React Native, where useResolvedColors() follows too. Overrides replace a colour whatever the theme, so pass per-mode values when the mode can change. A nested provider on the same theme keeps the outer overrides and lays its own over them; on another theme it starts from that theme\'s colours.',
   whenToUse: [
     'App root — required for all Duro components to render correctly',
     'Theme switching (dark/light mode toggle)',

package/src/components/ThemeProvider/ThemeProvider.native.tsx

@@ -18,11 +18,19 @@ import {
   ThemeScopeContext,
   type ThemeScope,
 } from '../../shared/portal/themeScope'
+import {mergeOverrides, OverridesContext, type ColorOverrides} from './overrides'
 
 export type ThemeName = 'dark' | 'light' | 'high-contrast'
+export type {ColorOverrides}
 
 interface ThemeProviderProps {
   theme?: ThemeName
+  /**
+   * Colours that replace the theme's own, by token key (`{accent: '#ff5a1f'}`).
+   * They update in place, without a re-mount. A nested provider on the same
+   * theme keeps these and lays its own over them.
+   */
+  overrides?: ColorOverrides
   children: ReactNode
 }
 
@@ -80,7 +88,7 @@ export function useResolvedColors(): Record<ColorToken, string> {
   return useContext(ResolvedColorsContext)
 }
 
-export function ThemeProvider({theme = 'dark', children}: ThemeProviderProps) {
+export function ThemeProvider({theme = 'dark', overrides, children}: ThemeProviderProps) {
   const outerRegistry = useContext(HostRegistryContext)
   const outerScope = useContext(ThemeScopeContext)
   // The outermost provider owns the registry and draws the root host.
@@ -88,7 +96,24 @@ export function ThemeProvider({theme = 'dark', children}: ThemeProviderProps) {
     outerRegistry ? null : createHostRegistry(),
   )
   const registry = outerRegistry ?? ownRegistry
-  const themeStyles = themeMap[theme]
+  const outerOverrides = useContext(OverridesContext)
+  const effective = useMemo(
+    () => mergeOverrides(outerOverrides, theme, overrides),
+    [outerOverrides, theme, overrides],
+  )
+  // A runtime theme on native, applied after the base one so RSD styles
+  // cascade it; rebuilt only when the colours change.
+  const overrideKey = JSON.stringify(effective.colors)
+  const themeStyles = useMemo(() => {
+    const base = themeMap[theme]
+    return overrideKey === '{}'
+      ? base
+      : [...base, css.createTheme(colors, JSON.parse(overrideKey) as ColorOverrides)]
+  }, [theme, overrideKey])
+  const resolved = useMemo(
+    () => ({...palettes[theme], ...(JSON.parse(overrideKey) as ColorOverrides)}),
+    [theme, overrideKey],
+  )
   const scope = useMemo<ThemeScope>(
     () => ({styles: [...outerScope.styles, ...themeStyles]}),
     [outerScope, themeStyles],
@@ -97,11 +122,15 @@ export function ThemeProvider({theme = 'dark', children}: ThemeProviderProps) {
   return (
     <HostRegistryContext.Provider value={registry}>
       <ThemeScopeContext.Provider value={scope}>
-        <ResolvedColorsContext.Provider value={palettes[theme]}>
-          <html.div style={[...themeStyles, styles.root, ownRegistry && styles.canvas] as DivStyle}>
-            {children}
-            {ownRegistry ? <PortalHost placement="base" /> : null}
-          </html.div>
+        <ResolvedColorsContext.Provider value={resolved}>
+          <OverridesContext.Provider value={effective}>
+            <html.div
+              style={[...themeStyles, styles.root, ownRegistry && styles.canvas] as DivStyle}
+            >
+              {children}
+              {ownRegistry ? <PortalHost placement="base" /> : null}
+            </html.div>
+          </OverridesContext.Provider>
         </ResolvedColorsContext.Provider>
       </ThemeScopeContext.Provider>
     </HostRegistryContext.Provider>

package/src/components/ThemeProvider/ThemeProvider.tsx

@@ -1,14 +1,24 @@
-import {createContext, type ReactNode, useContext, useState} from 'react'
+import {createContext, type ReactNode, useContext, useId, useMemo, useState} from 'react'
 import {css, html} from 'react-strict-dom'
+import type {ColorToken} from '@duro-app/tokens/keys'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {lightTheme, lightShadows} from '@duro-app/tokens/themes/light.css'
 import {highContrastTheme, highContrastShadows} from '@duro-app/tokens/themes/high-contrast.css'
 import {layers} from '@duro-app/tokens/tokens/layers.css'
+import {mergeOverrides, OverridesContext, type ColorOverrides} from './overrides'
+import {overrideRule} from './overrideRule'
 
 export type ThemeName = 'dark' | 'light' | 'high-contrast'
+export type {ColorOverrides}
 
 interface ThemeProviderProps {
   theme?: ThemeName
+  /**
+   * Colours that replace the theme's own, by token key (`{accent: '#ff5a1f'}`).
+   * They update in place, without a re-mount. A nested provider on the same
+   * theme keeps these and lays its own over them.
+   */
+  overrides?: ColorOverrides
   children: ReactNode
 }
 
@@ -49,14 +59,40 @@ export function usePortalMount(): HTMLElement | null {
   return useContext(PortalMountContext)
 }
 
-export function ThemeProvider({theme = 'dark', children}: ThemeProviderProps) {
-  const overrides = themeMap[theme]
-  const themeStyles = [overrides?.[0], overrides?.[1], styles.root] as DivStyle
+/** `var(--bg-x1y2)` → `--bg-x1y2`: the compiled variable a token key names. */
+function variableOf(key: ColorToken): string | null {
+  const ref = String(colors[key] ?? '')
+  const match = /^var\((--[\w-]+)\)$/.exec(ref)
+  return match ? match[1] : null
+}
+
+export function ThemeProvider({theme = 'dark', overrides, children}: ThemeProviderProps) {
+  const themeStyles = themeMap[theme]
+  const style = [themeStyles?.[0], themeStyles?.[1], styles.root] as DivStyle
   const [mount, setMount] = useState<HTMLElement | null>(null)
+  const scope = useId()
+  const outer = useContext(OverridesContext)
+  const effective = useMemo(
+    () => mergeOverrides(outer, theme, overrides),
+    [outer, theme, overrides],
+  )
+  const rule = useMemo(
+    () =>
+      Object.keys(effective.colors).length > 0
+        ? overrideRule(scope, effective.colors, variableOf)
+        : null,
+    [scope, effective],
+  )
 
   return (
-    <html.div data-theme={theme} style={themeStyles}>
-      <PortalMountContext.Provider value={mount}>{children}</PortalMountContext.Provider>
+    <html.div data-theme={theme} data-duro-theme={rule ? scope : undefined} style={style}>
+      {/* A plain, updating <style> (react-strict-dom has no html.style): no
+          href or precedence, which would make React hoist it once and ignore
+          later changes. */}
+      {rule ? <style>{rule}</style> : null}
+      <OverridesContext.Provider value={effective}>
+        <PortalMountContext.Provider value={mount}>{children}</PortalMountContext.Provider>
+      </OverridesContext.Provider>
       <html.div ref={setMount} data-portal-mount style={styles.portalMount} />
     </html.div>
   )

package/src/components/ThemeProvider/overrideRule.ts

@@ -0,0 +1,39 @@
+/**
+ * The web ThemeProvider's override rule, pure: it runs the same on the server
+ * and in the browser (no `CSS` global), so a server-rendered rule hydrates.
+ */
+import type {ColorToken} from '@duro-app/tokens/keys'
+import type {ColorOverrides} from './overrides'
+
+/** A value that is a colour and nothing else, so it cannot leave its rule. */
+export function isSafeColor(value: string): boolean {
+  // The same answer on the server and in the browser (no CSS.supports), so a
+  // server-rendered rule hydrates unchanged: a hex, a colour function, or a
+  // keyword, with nothing that could close the declaration or the rule.
+  if (/[;{}<>"'\\]/.test(value)) return false
+  return (
+    /^#[0-9a-f]{3,8}$/i.test(value) ||
+    /^(rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\([^()]*\)$/i.test(value) ||
+    /^[a-z]+$/i.test(value)
+  )
+}
+
+/** The scoped rule for a provider's overrides, or null when it has none. */
+export function overrideRule(
+  scope: string,
+  overrides: ColorOverrides,
+  variableOf: (key: ColorToken) => string | null,
+): string | null {
+  const declarations = Object.entries(overrides).flatMap(([key, value]) => {
+    const variable = variableOf(key as ColorToken)
+    return variable && typeof value === 'string' && isSafeColor(value)
+      ? [`${variable}: ${value};`]
+      : []
+  })
+  if (declarations.length === 0) return null
+  // Doubled, so it outranks the theme classes (one class each) wherever the
+  // stylesheets land.
+  // useId output holds neither a quote nor a backslash: safe inside quotes.
+  const selector = `[data-duro-theme="${scope}"]`
+  return `${selector}${selector} { ${declarations.join(' ')} }`
+}

package/src/components/ThemeProvider/overrides.ts

@@ -0,0 +1,27 @@
+import {createContext} from 'react'
+import type {ColorToken} from '@duro-app/tokens/keys'
+
+/** Colours that replace a theme's own, by token key. */
+export type ColorOverrides = Partial<Record<ColorToken, string>>
+
+/** The overrides in force at a provider, and the theme they were made for. */
+export interface EffectiveOverrides {
+  theme: string | null
+  colors: ColorOverrides
+}
+
+export const OverridesContext = createContext<EffectiveOverrides>({theme: null, colors: {}})
+
+/**
+ * One rule on both platforms (plan N0, slice C): a provider on the same theme
+ * as the one above it keeps that one's overrides and lays its own over them;
+ * a provider on another theme starts from its own theme's colours.
+ */
+export function mergeOverrides(
+  outer: EffectiveOverrides,
+  theme: string,
+  own: ColorOverrides | undefined,
+): EffectiveOverrides {
+  const inherited = outer.theme === theme ? outer.colors : {}
+  return {theme, colors: own ? {...inherited, ...own} : inherited}
+}

package/src/form.native.ts

@@ -0,0 +1,7 @@
+/**
+ * `@duro-app/ui/form` on React Native — resolved via the `react-native` export
+ * condition. Form validates the same Effect Schema; a `type="submit"` Button
+ * inside it submits through FormSubmitContext, since native has no DOM
+ * submit event. See `form.ts` for why Form is a subpath.
+ */
+export {Form, type FormProps} from './components/Form/Form'

package/src/index.native.ts

@@ -51,6 +51,13 @@ export {Tag, type TagVariant} from './components/Tag/Tag'
 export {SideNav} from './components/SideNav/SideNav'
 export {Tabs} from './components/Tabs/Tabs'
 export {Tree} from './components/Tree/Tree'
+// 5.14: pickers open a bottom sheet (a Drawer at the medium and large detents)
+export {Select} from './components/Select/Select'
+export {Combobox} from './components/Combobox/Combobox'
+export {Listbox} from './components/Listbox/Listbox'
+// The platform's own scroll indicator: Scrollbar and Thumb draw nothing.
+export {ScrollArea} from './components/ScrollArea/ScrollArea'
+export type {ListboxAnchorProps, ListboxMaxHeight} from './components/Listbox/Listbox'
 // Always stacked on native: a phone is below every collapseBelow.
 export {SplitPane} from './components/SplitPane/SplitPane'
 // Always the phone shape on native: the bar on top, the rail in a left Drawer.
@@ -97,9 +104,17 @@ export type {GridTrack} from './shared/length'
 // no display:contents / portal mount; applies the theme to a flex container).
 export {
   ThemeProvider,
+  type ColorOverrides,
   usePortalMount,
   useResolvedColors,
   type ThemeName,
 } from './components/ThemeProvider/ThemeProvider'
+// 'system' follows RN Appearance; persistence is the app's (preference + onPreferenceChange).
+export {
+  ColorModeProvider,
+  ColorModeToggle,
+  useColorMode,
+  type ColorModePreference,
+} from './components/ColorMode'
 // Where toasts draw on native: mount one inside a natively presented route.
 export {PortalHost} from './shared/portal/PortalHost'

package/src/index.ts

@@ -125,6 +125,7 @@ export {VirtualList, type VirtualListProps} from './components/VirtualList/Virtu
 export {Textarea, type TextareaVariant} from './components/Textarea/Textarea'
 export {
   ThemeProvider,
+  type ColorOverrides,
   usePortalMount,
   type ThemeName,
 } from './components/ThemeProvider/ThemeProvider'

package/src/shared/focusInput.native.ts

@@ -0,0 +1,18 @@
+interface StrictInputRef {
+  getNativeRef?: () => {focus?: () => void} | null
+  focus?: () => void
+}
+
+/**
+ * Focus an html.input on native. react-strict-dom 0.0.55 hands out a copy of
+ * the TextInput instance, whose `focus()` does nothing (#506); the copy keeps
+ * TextInput's own `getNativeRef()`, which returns the real host.
+ *
+ * holds-until: react-strict-dom releases #515 (focus() on the ref itself).
+ */
+export function focusInput(input: unknown): void {
+  const ref = input as StrictInputRef | null
+  const host = ref?.getNativeRef?.()
+  if (host?.focus) host.focus()
+  else ref?.focus?.()
+}

package/src/shared/textOf.ts

@@ -0,0 +1,13 @@
+import {isValidElement, type ReactNode} from 'react'
+
+/**
+ * The text a React node would render, read from its props: a native picker's
+ * option label, where there is no DOM `textContent` to read it from.
+ */
+export function textOf(node: ReactNode): string {
+  if (node == null || typeof node === 'boolean') return ''
+  if (typeof node === 'string' || typeof node === 'number') return String(node)
+  if (Array.isArray(node)) return node.map(textOf).join('')
+  if (isValidElement<{children?: ReactNode}>(node)) return textOf(node.props.children)
+  return ''
+}