@titan-design/react-ui 0.9.2 → 0.10.0

package/src/components/ui/surface/SurfaceContext.ts

@@ -0,0 +1,126 @@
+// On-surface colour context (TD-05.12).
+//
+// A <Surface> owns a background from a small elevation scale AND publishes the
+// current theme mode so descendant text/icons resolve their colour from "what
+// surface am I on" instead of a `text-*` className. Those classNames silently
+// fail to black when the tree renders as raw RN in the standalone wall SPA
+// (no global.css, no nativewind) — the bug class this primitive retires.
+import { createContext, useContext } from 'react'
+import { getSemanticColors, type ThemeMode } from '../../../theme/tokens/semantic'
+import { surfaceRampDark } from '../../../theme/tokens/primitives'
+
+type ColorToken = keyof ReturnType<typeof getSemanticColors>
+
+/**
+ * A Surface's depth on the dark surface ramp. Each addressable level maps to an
+ * EXISTING semantic surface/background token (already grounded in the derived
+ * surface ramp — TD-surface-tokens S-1 — and theme-aware) — Surface introduces
+ * no new hexes. Darkest → lightest:
+ *   inset (#13100D) < background (#1C1916) < base (#252321) < elevated (#2A2827) < raised (#2D2C2B) < overlay (#302F2E)
+ *
+ * `inset` is the ramp's deepest pit — the sub-shell well. It's the floor a
+ * `<Surface pressed>` clamps at (see {@link pressedLevel}); it has no shipped
+ * semantic token yet, so {@link surfaceBackground} resolves it from the
+ * `surface-inset` token when present, else the `surfaceRampDark.inset` primitive.
+ */
+export type SurfaceLevel = 'inset' | 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+
+/** On-surface neutral text roles, resolved for the current surface + theme. */
+export type OnSurfaceRole = 'primary' | 'secondary' | 'tertiary'
+
+// Which semantic token backs each ADDRESSABLE level. Values live in `semantic.ts`
+// and stay in sync with the charcoal ramp — this map never carries literal hexes.
+// `inset` is intentionally absent: it has no shipped semantic token yet, so it's
+// resolved separately (token-or-primitive) in `surfaceBackground`.
+export const SURFACE_LEVEL_TOKEN = {
+  background: 'background-base',
+  base: 'surface-base',
+  elevated: 'surface-elevated',
+  raised: 'surface-raised',
+  overlay: 'surface-overlay',
+} as const satisfies Record<Exclude<SurfaceLevel, 'inset'>, ColorToken>
+
+// Darkest → lightest, INCLUDING the inset floor. A `<Surface pressed>` renders
+// one index DOWN from its parent's level and clamps at `inset` (index 0). Kept
+// in lockstep with the derived ramp and the surface.contract.test PLANE_ORDER.
+const PRESSED_RAMP = ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
+
+const ON_SURFACE_TOKEN = {
+  primary: 'text-primary',
+  secondary: 'text-secondary',
+  tertiary: 'text-tertiary',
+} as const satisfies Record<OnSurfaceRole, ColorToken>
+
+export interface SurfaceContextValue {
+  /** Active theme mode. Defaults to dark (the wall). */
+  mode: ThemeMode
+  /** Depth of the nearest enclosing Surface. */
+  level: SurfaceLevel
+}
+
+// Default context: dark 'base' plane, so descendants OUTSIDE any Surface still
+// resolve to real dark colours (never black) on the dark-only wall.
+const DEFAULT_CONTEXT: SurfaceContextValue = { mode: 'dark', level: 'base' }
+
+export const SurfaceContext = createContext<SurfaceContextValue>(DEFAULT_CONTEXT)
+
+/** The nearest surface context ({ mode, level }); default dark 'base'. */
+export function useSurface(): SurfaceContextValue {
+  return useContext(SurfaceContext)
+}
+
+/** The active theme mode from the nearest Surface/provider (default dark). */
+export function useSurfaceMode(): ThemeMode {
+  return useContext(SurfaceContext).mode
+}
+
+/**
+ * Literal-hex on-surface neutral text colours for a theme mode. Uses
+ * `getSemanticColors` (literal hex — the TempoBar pattern), never `resolveColor`
+ * (which returns `var()` under the RNW vitest alias), so values stay real in
+ * tested component code and on raw-RN surfaces alike.
+ */
+export function onSurfaceColors(mode: ThemeMode): Record<OnSurfaceRole, string> {
+  const c = getSemanticColors(mode)
+  return {
+    primary: c[ON_SURFACE_TOKEN.primary],
+    secondary: c[ON_SURFACE_TOKEN.secondary],
+    tertiary: c[ON_SURFACE_TOKEN.tertiary],
+  }
+}
+
+/** Resolve one on-surface text colour for descendants of a Surface. */
+export function useOnSurfaceColor(role: OnSurfaceRole = 'primary'): string {
+  return getSemanticColors(useSurfaceMode())[ON_SURFACE_TOKEN[role]]
+}
+
+/**
+ * The inset floor hex — the ramp's deepest pit that a pressed surface clamps at.
+ * Prefers the `surface-inset` semantic token (theme-aware; being promoted in a
+ * parallel token change) and falls back to the `surfaceRampDark.inset` primitive
+ * (#13100D, dark-ramp only) until that token ships.
+ */
+function insetFloor(mode: ThemeMode): string {
+  const colors = getSemanticColors(mode) as Record<string, string>
+  return colors['surface-inset'] ?? surfaceRampDark.inset
+}
+
+/** The background hex for a surface level under a theme mode (literal hex). */
+export function surfaceBackground(level: SurfaceLevel, mode: ThemeMode): string {
+  if (level === 'inset') return insetFloor(mode)
+  return getSemanticColors(mode)[SURFACE_LEVEL_TOKEN[level]]
+}
+
+/**
+ * The level a `<Surface pressed>` resolves to: its parent's level stepped one
+ * index DOWN the ramp — the symmetric twin of a raised surface stepping up —
+ * clamped at the `inset` floor so a pressed surface never underflows the pit.
+ *   overlay→raised, raised→elevated, elevated→base, base→background,
+ *   background→inset, inset→inset (clamped).
+ * Pressed exposes ONE level of depth only (no pressed-2).
+ */
+export function pressedLevel(parent: SurfaceLevel): SurfaceLevel {
+  const index = PRESSED_RAMP.indexOf(parent)
+  const down = Math.max(0, index - 1)
+  return PRESSED_RAMP[down]
+}

package/src/components/ui/surface/index.ts

@@ -1 +1,14 @@
 export { Surface, type SurfaceProps } from './Surface'
+export {
+  SurfaceContext,
+  useSurface,
+  useSurfaceMode,
+  useOnSurfaceColor,
+  onSurfaceColors,
+  surfaceBackground,
+  pressedLevel,
+  SURFACE_LEVEL_TOKEN,
+  type SurfaceLevel,
+  type OnSurfaceRole,
+  type SurfaceContextValue,
+} from './SurfaceContext'

package/src/components/ui/surface/surface.contract.test.ts

@@ -0,0 +1,283 @@
+import { describe, it, expect } from 'vitest'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+/**
+ * Token-value contract for the dark surface ramp (TD-surface-tokens, S-1).
+ * Mirrors `config.completeness.test.ts`'s role — this fails CI on the raw
+ * token VALUES, independent of any component, the same way the categorical
+ * palette locks its eligibility mask with a value-level test.
+ *
+ * Scope: DARK mode only. The north-star diagnosis
+ * (coordination/design-explorations/surface-system-north-star.md) measured and
+ * fixed the dark ramp specifically; light mode has its own latent collisions
+ * (e.g. `surface-overlay` === `surface-base`, both `#FFFFFF`) that were never
+ * part of this investigation — flagged as a follow-up, not silently patched
+ * here (see the report / open item list).
+ *
+ * ── R1 note — why this does NOT assert a flat ΔL* >= 4 on every step ──
+ * An earlier draft of the north-star doc (§3) proposed 5 EVEN steps at
+ * ΔL*≈4. The LOCKED derivation that ships here (§ "Surface-ramp SYSTEM —
+ * derived, not hand-picked") deliberately supersedes that with DIMINISHING
+ * steps — the frame->content jump is biggest, each plane above adds less.
+ * As of S-3 (this re-space) the steps are 4.5 / 4.5 / 3.5 / 3 / 2.5
+ * (inset->background / background->base / base->elevated / elevated->raised /
+ * raised->overlay) — the top three widened from the original 2.5/2/1.5 taper
+ * so the content planes read as distinct without leaning on the hairline
+ * alone (R3 still carries the rest, per "lightness is a *secondary* cue").
+ * So R1 here asserts what the locked design actually guarantees: strict
+ * monotonicity, a >=4 L* foundational jump at the frame/shell boundary, and
+ * a >=2.5 L* floor on each of the three re-spaced upper steps — not a flat
+ * "always diminishing" rule (quantizing to whole hex bytes can make two
+ * adjacent re-spaced steps land within ~0.02 L* of each other; the floor is
+ * the guarantee that matters, not strict ordering between them).
+ */
+
+// --- CIELAB L* (perceptual lightness), matching the calculation in
+// surface-lab-shared.tsx's `lstar()` (the derivation source) verbatim, so
+// this test measures the SAME metric the ramp was designed against. ---
+function channels(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number]
+}
+
+function lstar(hex: string): number {
+  const lin = channels(hex)
+    .map((c) => c / 255)
+    .map((c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
+  const y = 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+  return y <= 0.008856 ? y * 903.3 : 116 * Math.cbrt(y) - 16
+}
+
+/** Flatten an rgba(...) alpha color over an opaque hex background -> opaque hex. */
+function compositeOver(baseHex: string, overlay: string): string {
+  const match = overlay.match(
+    /rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)/
+  )
+  if (!match) throw new Error(`not an rgba() color: ${overlay}`)
+  const [, r, g, b, a = '1'] = match
+  const alpha = parseFloat(a)
+  const base = channels(baseHex)
+  const tint = [parseFloat(r), parseFloat(g), parseFloat(b)]
+  const mixed = base.map((c, i) => c * (1 - alpha) + tint[i] * alpha)
+  return (
+    '#' +
+    mixed
+      .map((v) =>
+        Math.max(0, Math.min(255, Math.round(v)))
+          .toString(16)
+          .padStart(2, '0')
+      )
+      .join('')
+  )
+}
+
+const dark = getSemanticColors('dark')
+
+// The 6-plane derivation, in darkest -> lightest order. `inset` is now a real
+// shipped token (`surface-inset`, promoted at S-3 — see semantic.ts comment).
+const RAMP_HEX = {
+  inset: dark['surface-inset'],
+  background: dark['background-base'],
+  base: dark['surface-base'],
+  elevated: dark['surface-elevated'],
+  raised: dark['surface-raised'],
+  overlay: dark['surface-overlay'],
+} as const
+
+const PLANE_ORDER = ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
+
+describe('surface ramp contract (dark) — token-value guardrails', () => {
+  it('ships the deriveSurfaceRamp() output verbatim for the addressable planes', () => {
+    // Locked values from surface-system-north-star.md (re-spaced S-3) — see
+    // surfaceRampDark in primitives.ts for the derivation this must match
+    // byte-for-byte. background/base/inset are unchanged by the re-space.
+    expect(dark['surface-inset']).toBe('#13100D')
+    expect(dark['background-base']).toBe('#1C1916')
+    expect(dark['surface-base']).toBe('#252321')
+    expect(dark['surface-elevated']).toBe('#2C2A28')
+    expect(dark['surface-raised']).toBe('#31302F')
+    expect(dark['surface-overlay']).toBe('#373635')
+  })
+
+  describe('R1 — monotonic ramp with a real foundational jump', () => {
+    it('is strictly increasing in L* across all 6 planes', () => {
+      const Ls = PLANE_ORDER.map((name) => lstar(RAMP_HEX[name]))
+      for (let i = 1; i < Ls.length; i++) {
+        expect(
+          Ls[i],
+          `${PLANE_ORDER[i]} should be lighter than ${PLANE_ORDER[i - 1]}`
+        ).toBeGreaterThan(Ls[i - 1])
+      }
+    })
+
+    it('clears ΔL* >= 4 at the two foundational steps (inset->background, background->base)', () => {
+      const dL_insetToBackground = lstar(RAMP_HEX.background) - lstar(RAMP_HEX.inset)
+      const dL_backgroundToBase = lstar(RAMP_HEX.base) - lstar(RAMP_HEX.background)
+      expect(dL_insetToBackground).toBeGreaterThanOrEqual(4)
+      expect(dL_backgroundToBase).toBeGreaterThanOrEqual(4)
+    })
+
+    it('each re-spaced upper step (base->elevated->raised->overlay) clears ΔL* >= 2.5', () => {
+      // S-3 widened the top three steps to 3.5/3/2.5 specifically so they no
+      // longer need to lean on the "keep diminishing" clause the old 2.5/2/1.5
+      // taper required — each step now stands on its own >=2.5 L* floor.
+      // (Quantizing to whole hex bytes can make two of these land within
+      // ~0.02 L* of strict diminishing order; that's expected and not asserted.)
+      const upperSteps = ['base', 'elevated', 'raised', 'overlay'] as const
+      for (let i = 1; i < upperSteps.length; i++) {
+        const d = lstar(RAMP_HEX[upperSteps[i]]) - lstar(RAMP_HEX[upperSteps[i - 1]])
+        expect(d, `${upperSteps[i - 1]} -> ${upperSteps[i]}`).toBeGreaterThanOrEqual(2.5)
+      }
+    })
+  })
+
+  describe('R2 — no footgun collisions', () => {
+    it('surface-elevated and surface-overlay are distinct (previously both #191919)', () => {
+      expect(dark['surface-elevated']).not.toBe(dark['surface-overlay'])
+    })
+
+    it('the 5 addressable surface-family hexes are pairwise distinct', () => {
+      const family = [
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+      ] as const
+      const values = family.map((k) => dark[k])
+      expect(new Set(values).size).toBe(values.length)
+    })
+
+    it('no solid border token equals any surface/background fill hex', () => {
+      const surfaceHexes = new Set([
+        dark['background-base'],
+        dark['background-default'],
+        dark['background-subtle'],
+        dark['background-frame'],
+        dark['surface-base'],
+        dark['surface-elevated'],
+        dark['surface-raised'],
+        dark['surface-overlay'],
+        dark['surface-input'],
+        dark['surface-inset'],
+      ])
+      const solidBorders = [
+        'border-default',
+        'border-subtle',
+        'border-strong',
+        'border-prominent',
+      ] as const
+      for (const token of solidBorders) {
+        expect(
+          surfaceHexes.has(dark[token]),
+          `${token} (${dark[token]}) collides with a surface hex`
+        ).toBe(false)
+      }
+    })
+  })
+
+  describe('R3 — alpha hairline clears its ΔL* floor on every plane', () => {
+    // Doc floors (subtle>=6/default>=9/strong>=13) were calibrated on the OLD,
+    // much darker ramp (L* 4.7-10.3). The S-1 ramp compressed into a narrower,
+    // lighter band (L* 9-19.5); S-3's re-space widens it further still
+    // (L* 4.5-22.5) — the wider top steps push `overlay` even lighter, so the
+    // SAME alpha values composite to a slightly smaller (but still solid,
+    // still near-constant) ΔL* there. Floors below are re-measured against
+    // the S-3 ramp (default dropped 8->7 — the `overlay` plane now measures
+    // ~7.97, just under the old floor); a wall-display calibration pass (S-6)
+    // may retune the alpha values themselves.
+    const HAIRLINES = {
+      subtle: { token: 'hairline-subtle', floor: 5 },
+      default: { token: 'hairline-default', floor: 7 },
+      strong: { token: 'hairline-strong', floor: 12 },
+    } as const
+
+    for (const [name, { token, floor }] of Object.entries(HAIRLINES)) {
+      it(`${name} (${token}) clears ΔL* >= ${floor} on every ramp plane`, () => {
+        const hairlineColor = dark[token as keyof typeof dark]
+        for (const plane of PLANE_ORDER) {
+          const planeHex = RAMP_HEX[plane]
+          const composited = compositeOver(planeHex, hairlineColor)
+          const dL = lstar(composited) - lstar(planeHex)
+          expect(dL, `${name} on ${plane}`).toBeGreaterThanOrEqual(floor)
+        }
+      })
+    }
+
+    it('is near-constant (self-normalizing) across all planes: spread < 4 L* per tier', () => {
+      // Measured spread (inset..overlay): subtle ~1.6, default ~2.2, strong ~3.2 —
+      // still far tighter than a solid border token (which swings ~5.6 -> 0
+      // across this same ramp, see R4). "Near-constant" is relative to that,
+      // not perfectly flat — alpha-over-white is sublinear in L* as the base
+      // lightens, which is exactly the R3 floor-vs-doc discrepancy noted above.
+      for (const { token } of Object.values(HAIRLINES)) {
+        const hairlineColor = dark[token as keyof typeof dark]
+        const deltas = PLANE_ORDER.map((plane) => {
+          const planeHex = RAMP_HEX[plane]
+          return lstar(compositeOver(planeHex, hairlineColor)) - lstar(planeHex)
+        })
+        expect(Math.max(...deltas) - Math.min(...deltas)).toBeLessThan(4)
+      }
+    })
+  })
+
+  describe('R4 — border-on-surface clears ΔL* >= 3 (fixes the invisible-hairline collision)', () => {
+    it('border-subtle is no longer invisible on surface-raised (the original bug)', () => {
+      const dL = Math.abs(lstar(dark['border-subtle']) - lstar(dark['surface-raised']))
+      expect(dL).toBeGreaterThanOrEqual(3)
+    })
+
+    it('border-subtle clears ΔL* >= 3 against base/elevated/raised/overlay', () => {
+      const planes = [
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+      ] as const
+      for (const plane of planes) {
+        const dL = Math.abs(lstar(dark['border-subtle']) - lstar(dark[plane]))
+        expect(dL, `border-subtle vs ${plane}`).toBeGreaterThanOrEqual(3)
+      }
+    })
+  })
+
+  describe('R5 — background-frame and surface-inset (S-3 new tokens)', () => {
+    it('background-frame is darker than background-base', () => {
+      expect(lstar(dark['background-frame'])).toBeLessThan(lstar(dark['background-base']))
+    })
+
+    it('background-frame is distinct from every surface/background token', () => {
+      const otherTokens = [
+        'background-base',
+        'background-default',
+        'background-subtle',
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+        'surface-input',
+        'surface-inset',
+      ] as const
+      for (const token of otherTokens) {
+        expect(dark['background-frame'], `background-frame vs ${token}`).not.toBe(dark[token])
+      }
+    })
+
+    it('surface-inset is the darkest surface-family token', () => {
+      const surfaceFamily = [
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+        'surface-input',
+      ] as const
+      const insetL = lstar(dark['surface-inset'])
+      for (const token of surfaceFamily) {
+        expect(insetL, `surface-inset vs ${token}`).toBeLessThan(lstar(dark[token]))
+      }
+    })
+
+    it('surface-inset is distinct from background-frame', () => {
+      expect(dark['surface-inset']).not.toBe(dark['background-frame'])
+    })
+  })
+})

package/src/test/nativewind-stub.ts

@@ -11,3 +11,16 @@
 export function vars(values: Record<string, string>): Record<string, string> {
   return values
 }
+
+/**
+ * Stand-in for nativewind's `useColorScheme()`. Under the web test env there is
+ * no nativewind theme applied, so it reports `undefined` (the "no explicit
+ * scheme" signal) — matching ThemeProvider's dark fallback for `mode="system"`.
+ */
+export function useColorScheme(): {
+  colorScheme: 'light' | 'dark' | undefined
+  setColorScheme: (scheme: 'light' | 'dark' | 'system') => void
+  toggleColorScheme: () => void
+} {
+  return { colorScheme: undefined, setColorScheme: () => {}, toggleColorScheme: () => {} }
+}