@duro-app/ui 0.35.4 → 0.36.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.35.4",
+  "version": "0.36.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -54,7 +54,7 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.35.4"
+    "@duro-app/tokens": "^0.36.1"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/ColorMode/ColorMode.meta.ts

@@ -0,0 +1,40 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Color-mode controller + toggle. ColorModeProvider owns the preference (system/light/dark/high-contrast), resolves "system" against the OS scheme, persists it to localStorage, and applies the resolved theme via ThemeProvider. ColorModeToggle is an icon button that cycles the preference; useColorMode() reads it.',
+  whenToUse: [
+    'App-level light/dark (and high-contrast) switching that persists across reloads',
+    'Respecting the OS prefers-color-scheme with a user override',
+    'Any place that needs the resolved theme name (useColorMode().theme)',
+  ],
+  whenNotToUse: [
+    'A single static theme — use ThemeProvider directly with a fixed theme prop',
+    'On/off setting unrelated to theming — use Switch',
+  ],
+  anatomy: {
+    required: ['ColorModeProvider'],
+    optional: ['ColorModeToggle', 'useColorMode'],
+  },
+  relatedTo: [
+    {
+      component: 'ThemeProvider',
+      relationship:
+        'ColorModeProvider renders ThemeProvider with the resolved theme; use ThemeProvider alone for a fixed theme',
+    },
+    {
+      component: 'Toggle',
+      relationship: 'Toggle is a generic pressed button; ColorModeToggle cycles theme modes',
+    },
+  ],
+  example: `// At the app root — replaces a bare <ThemeProvider>:
+<ColorModeProvider defaultPreference="system" modes={['light', 'dark']}>
+  <App />
+</ColorModeProvider>
+
+// Anywhere inside (e.g. the top bar):
+<ColorModeToggle />
+
+// Or read the resolved theme:
+const {theme, preference, setPreference} = useColorMode()`,
+}

package/src/components/ColorMode/ColorMode.stories.tsx

@@ -0,0 +1,87 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {ColorModeProvider, ColorModeToggle, useColorMode} from './ColorMode'
+
+const meta: Meta<typeof ColorModeToggle> = {
+  title: 'Components/ColorMode',
+  component: ColorModeToggle,
+}
+
+export default meta
+type Story = StoryObj<typeof ColorModeToggle>
+
+/** Default cycle: light ⇄ dark. Starts on `system`. */
+export const Default: Story = {
+  render: (args) => (
+    // storageKey null keeps stories isolated (no cross-test localStorage leak).
+    <ColorModeProvider storageKey={null} onPreferenceChange={fn()}>
+      <ColorModeToggle {...args} />
+    </ColorModeProvider>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const btn = canvas.getByRole('button')
+    await expect(btn.getAttribute('aria-label')).toContain('Color mode: system')
+
+    await userEvent.click(btn)
+    await expect(btn.getAttribute('aria-label')).toContain('Color mode: light')
+
+    await userEvent.click(btn)
+    await expect(btn.getAttribute('aria-label')).toContain('Color mode: dark')
+
+    // Wraps back to the first mode.
+    await userEvent.click(btn)
+    await expect(btn.getAttribute('aria-label')).toContain('Color mode: light')
+  },
+}
+
+/** A four-way cycle including `system` and `high-contrast`. */
+export const AllModes: Story = {
+  render: () => (
+    <ColorModeProvider
+      storageKey={null}
+      defaultPreference="system"
+      modes={['system', 'light', 'dark', 'high-contrast']}
+    >
+      <ColorModeToggle />
+    </ColorModeProvider>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const btn = canvas.getByRole('button')
+    await expect(btn.getAttribute('aria-label')).toContain('Switch to light')
+    await userEvent.click(btn)
+    await expect(btn.getAttribute('aria-label')).toContain('Color mode: light')
+    await userEvent.click(btn)
+    await userEvent.click(btn)
+    await expect(btn.getAttribute('aria-label')).toContain('high contrast')
+  },
+}
+
+const readout = css.create({
+  row: {display: 'flex', alignItems: 'center', gap: 12},
+})
+
+function Readout() {
+  const {preference, theme} = useColorMode()
+  return (
+    <html.div style={readout.row}>
+      <ColorModeToggle />
+      <html.span>
+        preference: {preference} → theme: {theme}
+      </html.span>
+    </html.div>
+  )
+}
+
+/** Reading the resolved theme via `useColorMode()`. */
+export const WithReadout: Story = {
+  render: () => (
+    <ColorModeProvider storageKey={null} defaultPreference="light">
+      <Readout />
+    </ColorModeProvider>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByText(/preference: light/)).toBeInTheDocument()
+    await expect(canvas.getByText(/theme: light/)).toBeInTheDocument()
+  },
+}

package/src/components/ColorMode/ColorMode.tsx

@@ -0,0 +1,203 @@
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react'
+import {html} from 'react-strict-dom'
+import {isNative} from '../../platform'
+import {Icon, type IconName} from '../Icon/Icon'
+import {ThemeProvider, type ThemeName} from '../ThemeProvider/ThemeProvider'
+import {styles} from './styles.css'
+
+/**
+ * The user's *preference*. `'system'` follows the OS `prefers-color-scheme`;
+ * the others pin a concrete {@link ThemeName}. Resolves to a ThemeName via
+ * {@link useColorMode}().theme.
+ */
+export type ColorModePreference = 'system' | ThemeName
+
+const PREFERENCES: readonly ColorModePreference[] = ['system', 'light', 'dark', 'high-contrast']
+
+const ICON: Record<ColorModePreference, IconName> = {
+  system: 'monitor',
+  light: 'sun',
+  dark: 'moon',
+  'high-contrast': 'contrast',
+}
+
+const LABEL: Record<ColorModePreference, string> = {
+  system: 'system',
+  light: 'light',
+  dark: 'dark',
+  'high-contrast': 'high contrast',
+}
+
+interface ColorModeContextValue {
+  /** The user's chosen preference. */
+  preference: ColorModePreference
+  /** The concrete theme the preference resolves to (system → OS scheme). */
+  theme: ThemeName
+  /** Set the preference explicitly. */
+  setPreference: (preference: ColorModePreference) => void
+  /** Advance to the next preference in {@link modes} (wraps). */
+  cycle: () => void
+  /** The cycle order used by `cycle()` and the toggle. */
+  modes: readonly ColorModePreference[]
+}
+
+const ColorModeContext = createContext<ColorModeContextValue | null>(null)
+
+/**
+ * Read the active color mode. Throws if used outside a {@link ColorModeProvider}.
+ */
+export function useColorMode(): ColorModeContextValue {
+  const ctx = useContext(ColorModeContext)
+  if (!ctx) {
+    throw new Error('useColorMode must be used within a <ColorModeProvider>')
+  }
+  return ctx
+}
+
+const canUseDom =
+  !isNative && typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+
+function isPreference(value: unknown): value is ColorModePreference {
+  return typeof value === 'string' && (PREFERENCES as readonly string[]).includes(value)
+}
+
+function readStored(key: string | null): ColorModePreference | null {
+  if (!key || isNative || typeof window === 'undefined') return null
+  try {
+    const raw = window.localStorage.getItem(key)
+    return isPreference(raw) ? raw : null
+  } catch {
+    // Private mode / blocked storage — degrade to no persistence.
+    return null
+  }
+}
+
+function writeStored(key: string | null, value: ColorModePreference): void {
+  if (!key || isNative || typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(key, value)
+  } catch {
+    /* ignore */
+  }
+}
+
+interface ColorModeProviderProps {
+  children: ReactNode
+  /** Initial preference (uncontrolled). Default `'system'`. For SSR with no
+   * hydration flash, pass the value you persisted server-side (e.g. a cookie). */
+  defaultPreference?: ColorModePreference
+  /** Controlled preference — when set, the provider does not own the state. */
+  preference?: ColorModePreference
+  /** Fired whenever the preference changes (controlled or not). */
+  onPreferenceChange?: (preference: ColorModePreference) => void
+  /** Cycle order for `cycle()` / `<ColorModeToggle>`. Default `['light', 'dark']`. */
+  modes?: readonly ColorModePreference[]
+  /** localStorage key for persistence; `null` disables it. Default `'duro-color-mode'`. */
+  storageKey?: string | null
+  /** Wrap children in the DS `ThemeProvider` with the resolved theme. Default `true`.
+   * Set `false` to drive your own ThemeProvider from `useColorMode().theme`. */
+  applyTheme?: boolean
+}
+
+/**
+ * Owns color-mode state, resolves `'system'` against the OS scheme, persists the
+ * choice, and (by default) applies the resolved theme via `ThemeProvider`.
+ * Pair with {@link ColorModeToggle} or read state via {@link useColorMode}.
+ */
+export function ColorModeProvider({
+  children,
+  defaultPreference = 'system',
+  preference: controlled,
+  onPreferenceChange,
+  modes = ['light', 'dark'],
+  storageKey = 'duro-color-mode',
+  applyTheme = true,
+}: ColorModeProviderProps) {
+  const [internal, setInternal] = useState<ColorModePreference>(controlled ?? defaultPreference)
+  const preference = controlled ?? internal
+
+  // Hydrate from storage AFTER mount (not in the initializer) so the first
+  // client render matches the server and React doesn't warn about a mismatch.
+  useEffect(() => {
+    if (controlled !== undefined) return
+    const stored = readStored(storageKey)
+    if (stored) setInternal(stored)
+    // Only on mount / when the key changes.
+  }, [controlled, storageKey])
+
+  const setPreference = useCallback(
+    (next: ColorModePreference) => {
+      if (controlled === undefined) setInternal(next)
+      writeStored(storageKey, next)
+      onPreferenceChange?.(next)
+    },
+    [controlled, storageKey, onPreferenceChange],
+  )
+
+  // Track the OS scheme so `'system'` stays live. The initial value MUST be the
+  // SSR-stable default ('dark', what the server renders without a DOM) so the
+  // first client render matches the server — reading matchMedia in the
+  // initializer would diverge (server 'dark' vs client's real scheme) and trip
+  // a hydration mismatch. The effect reconciles to the real scheme after mount.
+  const [systemTheme, setSystemTheme] = useState<'light' | 'dark'>('dark')
+  useEffect(() => {
+    if (!canUseDom) return
+    const mq = window.matchMedia('(prefers-color-scheme: dark)')
+    const onChange = () => setSystemTheme(mq.matches ? 'dark' : 'light')
+    onChange()
+    mq.addEventListener('change', onChange)
+    return () => mq.removeEventListener('change', onChange)
+  }, [])
+
+  const theme: ThemeName = preference === 'system' ? systemTheme : preference
+
+  const cycle = useCallback(() => {
+    const i = modes.indexOf(preference)
+    const next = modes[(i + 1) % modes.length] ?? modes[0]
+    if (next) setPreference(next)
+  }, [modes, preference, setPreference])
+
+  const value = useMemo<ColorModeContextValue>(
+    () => ({preference, theme, setPreference, cycle, modes}),
+    [preference, theme, setPreference, cycle, modes],
+  )
+
+  return (
+    <ColorModeContext.Provider value={value}>
+      {applyTheme ? <ThemeProvider theme={theme}>{children}</ThemeProvider> : children}
+    </ColorModeContext.Provider>
+  )
+}
+
+interface ColorModeToggleProps {
+  /** Icon size in px. Default `20`. */
+  size?: number
+  /** Override the announced label (otherwise auto-generated from current/next). */
+  'aria-label'?: string
+}
+
+/**
+ * A compact icon button that cycles the color-mode preference through the
+ * provider's `modes`. The glyph reflects the current preference
+ * (sun/moon/monitor/contrast). Must be inside a {@link ColorModeProvider}.
+ */
+export function ColorModeToggle({size = 20, 'aria-label': ariaLabel}: ColorModeToggleProps) {
+  const {preference, cycle, modes} = useColorMode()
+  const i = modes.indexOf(preference)
+  const next = modes[(i + 1) % modes.length] ?? modes[0] ?? preference
+  const label = ariaLabel ?? `Color mode: ${LABEL[preference]}. Switch to ${LABEL[next]}.`
+
+  return (
+    <html.button type="button" aria-label={label} onClick={cycle} style={styles.button}>
+      <Icon name={ICON[preference]} size={size} />
+    </html.button>
+  )
+}

package/src/components/ColorMode/index.ts

@@ -0,0 +1,6 @@
+export {
+  ColorModeProvider,
+  ColorModeToggle,
+  useColorMode,
+  type ColorModePreference,
+} from './ColorMode'

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

@@ -0,0 +1,32 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
+
+export const styles = css.create({
+  button: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: spacing.sm,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: {
+      default: colors.border,
+      ':hover': colors.textMuted,
+    },
+    borderRadius: radii.sm,
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+    color: colors.text,
+    cursor: 'pointer',
+    transitionProperty: 'background-color, border-color, color',
+    transitionDuration: '150ms',
+    transitionTimingFunction: 'ease',
+    outlineWidth: {default: 0, ':focus-visible': 2},
+    outlineStyle: 'solid',
+    outlineColor: colors.accent,
+    outlineOffset: 2,
+  },
+})

package/src/components/Icon/Icon.tsx

@@ -11,6 +11,21 @@ export type IconName =
   | 'shield'
   | 'lock'
   | 'key'
+  // Navigation / wayfinding glyphs
+  | 'map'
+  | 'layers'
+  | 'repeat'
+  | 'database'
+  | 'shield-check'
+  | 'route'
+  | 'git-branch'
+  | 'menu'
+  | 'pin'
+  // Color-mode glyphs
+  | 'sun'
+  | 'moon'
+  | 'monitor'
+  | 'contrast'
   // Filled variants (solid shape with cutout symbol)
   | 'info-circle-filled'
   | 'alert-triangle-filled'
@@ -78,6 +93,101 @@ const strokeIcons: Partial<Record<IconName, ReactNode>> = {
       <path d="M21 2l-2 2m-7.61 7.61a5.5 5.5 0 1 1-7.78 7.78 5.5 5.5 0 0 1 7.78-7.78zm0 0L15.5 7.5m0 0l3 3L22 7l-3-3m-3.5 3.5L19 4" />
     </>
   ),
+  // ---- navigation / wayfinding ----
+  map: (
+    <>
+      <polygon points="1 6 1 22 8 18 16 22 23 18 23 2 16 6 8 2 1 6" />
+      <line x1="8" y1="2" x2="8" y2="18" />
+      <line x1="16" y1="6" x2="16" y2="22" />
+    </>
+  ),
+  layers: (
+    <>
+      <polygon points="12 2 2 7 12 12 22 7 12 2" />
+      <polyline points="2 17 12 22 22 17" />
+      <polyline points="2 12 12 17 22 12" />
+    </>
+  ),
+  // Two crossing arrows — exchange / interface flows.
+  repeat: (
+    <>
+      <polyline points="17 1 21 5 17 9" />
+      <path d="M3 11V9a4 4 0 0 1 4-4h14" />
+      <polyline points="7 23 3 19 7 15" />
+      <path d="M21 13v2a4 4 0 0 1-4 4H3" />
+    </>
+  ),
+  database: (
+    <>
+      <ellipse cx="12" cy="5" rx="9" ry="3" />
+      <path d="M21 12c0 1.66-4 3-9 3s-9-1.34-9-3" />
+      <path d="M3 5v14c0 1.66 4 3 9 3s9-1.34 9-3V5" />
+    </>
+  ),
+  'shield-check': (
+    <>
+      <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
+      <polyline points="9 12 11 14 15 10" />
+    </>
+  ),
+  // Milestone path — roadmap / itinerary.
+  route: (
+    <>
+      <circle cx="6" cy="19" r="3" />
+      <path d="M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15" />
+      <circle cx="18" cy="5" r="3" />
+    </>
+  ),
+  'git-branch': (
+    <>
+      <line x1="6" y1="3" x2="6" y2="15" />
+      <circle cx="18" cy="6" r="3" />
+      <circle cx="6" cy="18" r="3" />
+      <path d="M18 9a9 9 0 0 1-9 9" />
+    </>
+  ),
+  menu: (
+    <>
+      <line x1="3" y1="6" x2="21" y2="6" />
+      <line x1="3" y1="12" x2="21" y2="12" />
+      <line x1="3" y1="18" x2="21" y2="18" />
+    </>
+  ),
+  pin: (
+    <>
+      <line x1="12" y1="17" x2="12" y2="22" />
+      <path d="M9 10.76V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v6.76a2 2 0 0 0 .55 1.38l1.68 1.78A1 1 0 0 1 16.5 16h-9a1 1 0 0 1-.73-1.68l1.68-1.78A2 2 0 0 0 9 10.76z" />
+    </>
+  ),
+  // ---- color mode ----
+  sun: (
+    <>
+      <circle cx="12" cy="12" r="5" />
+      <line x1="12" y1="1" x2="12" y2="3" />
+      <line x1="12" y1="21" x2="12" y2="23" />
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+      <line x1="1" y1="12" x2="3" y2="12" />
+      <line x1="21" y1="12" x2="23" y2="12" />
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+    </>
+  ),
+  moon: <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />,
+  monitor: (
+    <>
+      <rect x="2" y="3" width="20" height="14" rx="2" ry="2" />
+      <line x1="8" y1="21" x2="16" y2="21" />
+      <line x1="12" y1="17" x2="12" y2="21" />
+    </>
+  ),
+  // Circle, half solid — high-contrast / mode indicator.
+  contrast: (
+    <>
+      <circle cx="12" cy="12" r="10" />
+      <path d="M12 2a10 10 0 0 1 0 20z" fill="currentColor" stroke="none" />
+    </>
+  ),
 }
 
 /**

package/src/index.ts

@@ -62,6 +62,12 @@ export {
   usePortalMount,
   type ThemeName,
 } from './components/ThemeProvider/ThemeProvider'
+export {
+  ColorModeProvider,
+  ColorModeToggle,
+  useColorMode,
+  type ColorModePreference,
+} from './components/ColorMode'
 export {Text, type TextVariant, type TextColor} from './components/Text/Text'
 export {Toggle, type ToggleSize} from './components/Toggle/Toggle'
 export {ToggleGroup} from './components/ToggleGroup/ToggleGroup'