@duro-app/ui 5.12.0 → 5.14.0

package/src/components/Tabs/useTabKeys.ts

@@ -0,0 +1,99 @@
+import {useEffect} from 'react'
+import type {Orientation} from '../../shared/types'
+
+interface TabKeysInput {
+  listRef: React.RefObject<HTMLDivElement | null>
+  orientation: Orientation
+  activeValue: string | null
+  onSelect: (value: string) => void
+  tabsRef: React.RefObject<Map<string, boolean>>
+  orderRef: React.RefObject<string[]>
+}
+
+/** Web: arrow keys, Home and End move the selection and focus along the list. */
+export function useTabKeys({
+  listRef,
+  orientation,
+  activeValue,
+  onSelect,
+  tabsRef,
+  orderRef,
+}: TabKeysInput) {
+  useEffect(() => {
+    const el = listRef.current
+    if (!el) return
+    const listEl = el
+
+    function handleKeyDown(e: KeyboardEvent) {
+      const order = orderRef.current
+      const tabs = tabsRef.current
+      if (order.length === 0) return
+
+      const prevKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp'
+      const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown'
+
+      let targetValue: string | null = null
+
+      switch (e.key) {
+        case nextKey: {
+          e.preventDefault()
+          const currentIdx = activeValue ? order.indexOf(activeValue) : -1
+          for (let i = 1; i <= order.length; i++) {
+            const idx = (currentIdx + i) % order.length
+            const val = order[idx]
+            if (!tabs.get(val)) {
+              targetValue = val
+              break
+            }
+          }
+          break
+        }
+        case prevKey: {
+          e.preventDefault()
+          const currentIdx = activeValue ? order.indexOf(activeValue) : 0
+          for (let i = 1; i <= order.length; i++) {
+            const idx = (currentIdx - i + order.length) % order.length
+            const val = order[idx]
+            if (!tabs.get(val)) {
+              targetValue = val
+              break
+            }
+          }
+          break
+        }
+        case 'Home': {
+          e.preventDefault()
+          for (const val of order) {
+            if (!tabs.get(val)) {
+              targetValue = val
+              break
+            }
+          }
+          break
+        }
+        case 'End': {
+          e.preventDefault()
+          for (let i = order.length - 1; i >= 0; i--) {
+            if (!tabs.get(order[i])) {
+              targetValue = order[i]
+              break
+            }
+          }
+          break
+        }
+      }
+
+      if (targetValue) {
+        onSelect(targetValue)
+        // Focus the newly activated tab button
+        const tabEl = listEl.querySelector(
+          `[data-tab-value="${targetValue}"]`,
+        ) as HTMLElement | null
+        tabEl?.focus()
+      }
+    }
+
+    el.addEventListener('keydown', handleKeyDown)
+    return () => el.removeEventListener('keydown', handleKeyDown)
+  }, [listRef, orientation, activeValue, onSelect, tabsRef, orderRef])
+}

package/src/components/Tag/RemoveGlyph.native.tsx

@@ -0,0 +1,17 @@
+import Svg, {Path} from 'react-native-svg'
+import {useResolvedColors} from '../ThemeProvider/ThemeProvider'
+import type {RemoveGlyphProps} from './types'
+
+/**
+ * The same cross as the web's, drawn with react-native-svg (the native icon
+ * renderer, plan N0 Decision 9) in the tag's resolved text colour: a raw
+ * host has no CSS `currentColor` to inherit.
+ */
+export function RemoveGlyph({size, color}: RemoveGlyphProps) {
+  const stroke = useResolvedColors()[color]
+  return (
+    <Svg width={size} height={size} viewBox="0 0 12 12" fill="none" aria-hidden>
+      <Path d="M3 3l6 6M9 3l-6 6" stroke={stroke} strokeWidth={1.5} strokeLinecap="round" />
+    </Svg>
+  )
+}

package/src/components/Tag/RemoveGlyph.tsx

@@ -0,0 +1,10 @@
+import type {RemoveGlyphProps} from './types'
+
+/** The tag's remove cross: 1.5 strokes on a 12 box, drawn in the tag's text colour. */
+export function RemoveGlyph({size}: RemoveGlyphProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 12 12" fill="none">
+      <path d="M3 3l6 6M9 3l-6 6" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" />
+    </svg>
+  )
+}

package/src/components/Tag/Tag.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Interactive tag/chip with optional remove button. Works standalone or inside TagGroup for collection management. Visually similar to Badge but supports interaction.',
+    'Interactive tag/chip with optional remove button. Works standalone or inside TagGroup for collection management. Visually similar to Badge but supports interaction. On React Native a Tag stands alone (TagGroup is web only): the label and, when removable, a remove button named from a string label.',
   whenToUse: [
     'Removable items in a list (emails, categories)',
     'Inside TagGroup for editable tag collections',

package/src/components/Tag/Tag.native.tsx

@@ -0,0 +1,70 @@
+import {html} from 'react-strict-dom'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {styles} from './styles.css'
+import {RemoveGlyph} from './RemoveGlyph'
+import {variantText, type TagProps} from './types'
+
+export type {TagProps, TagSize, TagVariant} from './types'
+
+const sizeMap = {
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+} as const
+
+const removableSizeMap = {
+  sm: styles.removableSm,
+  md: styles.removableMd,
+} as const
+
+/**
+ * Native Tag (plan N0, Slice B): the label and, when removable, the remove
+ * button. TagGroup is not ported (its grid keyboard model is web only,
+ * Decision 6), so `value` is unused here; the remove button's name comes from
+ * a string label.
+ */
+export function Tag({
+  variant = 'default',
+  size = 'md',
+  removable = false,
+  onRemove,
+  disabled = false,
+  wrap = false,
+  children,
+}: TagProps) {
+  const removeLabel = typeof children === 'string' ? `Remove ${children}` : 'Remove'
+  // A div, not the web's span: a native span is a Text, which would lay the
+  // remove button out inline, raised off the label's centre line.
+  return (
+    <html.div
+      style={[
+        styles.base,
+        styles.nativeFlex,
+        sizeMap[size],
+        removable && removableSizeMap[size],
+        styles[variant],
+        disabled && styles.disabled,
+        wrap && styles.wrap,
+      ]}
+    >
+      <html.span>{children}</html.span>
+      {removable && (
+        <html.button
+          type="button"
+          aria-label={removeLabel}
+          disabled={disabled}
+          onClick={disabled ? undefined : onRemove}
+          style={[
+            styles.removeButton,
+            styles.nativeButtonFlex,
+            disabled && styles.removeButtonDisabled,
+          ]}
+        >
+          <RemoveGlyph
+            size={size === 'sm' ? SIZES_PX.glyphXs : SIZES_PX.glyphSm}
+            color={variantText[variant]}
+          />
+        </html.button>
+      )}
+    </html.div>
+  )
+}

package/src/components/Tag/Tag.tsx

@@ -1,31 +1,12 @@
-import {type ReactNode, useCallback, useRef} from 'react'
+import {useCallback, useRef} from 'react'
 import {html} from 'react-strict-dom'
+import {SIZES_PX} from '@duro-app/tokens/keys'
 import {useTagGroup} from '../TagGroup/TagGroupContext'
 import {styles} from './styles.css'
+import {RemoveGlyph} from './RemoveGlyph'
+import {variantText, type TagProps} from './types'
 
-export type TagVariant = 'default' | 'success' | 'warning' | 'error' | 'info'
-export type TagSize = 'sm' | 'md'
-
-interface TagProps {
-  /** Value identifier — required when used inside TagGroup */
-  value?: string
-  variant?: TagVariant
-  size?: TagSize
-  /** Show remove button. Auto-derived from TagGroup context when inside one. */
-  removable?: boolean
-  /** Called when remove button is clicked. Auto-wired to TagGroup when inside one. */
-  onRemove?: () => void
-  disabled?: boolean
-  /**
-   * Allow the label to wrap / break instead of staying on one line. Tags are
-   * `white-space: nowrap` by default (they read as pills); set this for long
-   * identifier-style values (e.g. `lldap.group.member.remove`) sitting in a
-   * constrained column, so they break within their cell instead of leaking
-   * into the next one.
-   */
-  wrap?: boolean
-  children: ReactNode
-}
+export type {TagProps, TagSize, TagVariant} from './types'
 
 const sizeMap = {
   sm: styles.sizeSm,
@@ -112,19 +93,10 @@ export function Tag({
             tabIndex={-1}
             style={[styles.removeButton, disabled && styles.removeButtonDisabled]}
           >
-            <svg
-              width={size === 'sm' ? 10 : 12}
-              height={size === 'sm' ? 10 : 12}
-              viewBox="0 0 12 12"
-              fill="none"
-            >
-              <path
-                d="M3 3l6 6M9 3l-6 6"
-                stroke="currentColor"
-                strokeWidth={1.5}
-                strokeLinecap="round"
-              />
-            </svg>
+            <RemoveGlyph
+              size={size === 'sm' ? SIZES_PX.glyphXs : SIZES_PX.glyphSm}
+              color={variantText[variant]}
+            />
           </html.button>
         </html.span>
       )}

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

@@ -110,6 +110,15 @@ export const styles = css.create({
     },
     outlineWidth: 0,
   },
+  // RSD on native lays out only display: flex, not the web's inline-flex.
+  nativeFlex: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignSelf: 'flex-start',
+  },
+  nativeButtonFlex: {
+    display: 'flex',
+  },
   removeButtonDisabled: {
     cursor: 'not-allowed',
     opacity: 0.4,

package/src/components/Tag/types.ts

@@ -0,0 +1,43 @@
+import type {ReactNode} from 'react'
+import type {ColorToken} from '@duro-app/tokens/keys'
+
+export type TagVariant = 'default' | 'success' | 'warning' | 'error' | 'info'
+
+/** Each variant's text colour, which the remove cross draws in. */
+export const variantText = {
+  default: 'text',
+  success: 'successText',
+  warning: 'warningText',
+  error: 'errorText',
+  info: 'infoText',
+} as const satisfies Record<TagVariant, ColorToken>
+
+export type TagSize = 'sm' | 'md'
+
+export interface TagProps {
+  /** Value identifier — required when used inside TagGroup */
+  value?: string
+  variant?: TagVariant
+  size?: TagSize
+  /** Show remove button. Auto-derived from TagGroup context when inside one. */
+  removable?: boolean
+  /** Called when remove button is clicked. Auto-wired to TagGroup when inside one. */
+  onRemove?: () => void
+  disabled?: boolean
+  /**
+   * Allow the label to wrap / break instead of staying on one line. Tags are
+   * `white-space: nowrap` by default (they read as pills); set this for long
+   * identifier-style values (e.g. `lldap.group.member.remove`) sitting in a
+   * constrained column, so they break within their cell instead of leaking
+   * into the next one.
+   */
+  wrap?: boolean
+  children: ReactNode
+}
+
+export interface RemoveGlyphProps {
+  /** px, from the glyph size tokens */
+  size: number
+  /** Native only: the web inherits the tag's text colour. */
+  color: ColorToken
+}

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}
+}