@titan-design/react-ui 0.9.3 → 0.11.0

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

@@ -7,29 +7,43 @@
 // (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 charcoal ramp. Each level maps to an EXISTING
- * semantic surface/background token (already grounded in the charcoal ramp and
- * theme-aware) — Surface introduces no new hexes. Darkest → lightest:
- *   background (#101010) < base (#161616) < elevated (#191919) < raised (#1C1C1C)
+ * 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 = 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+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 level. Values live in `semantic.ts` and stay
-// in sync with the charcoal ramp — this map never carries literal hexes.
+// 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<SurfaceLevel, ColorToken>
+} 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',
@@ -80,7 +94,33 @@ 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

@@ -6,6 +6,7 @@ export {
   useOnSurfaceColor,
   onSurfaceColors,
   surfaceBackground,
+  pressedLevel,
   SURFACE_LEVEL_TOKEN,
   type SurfaceLevel,
   type OnSurfaceRole,

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/raw-color-patterns.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import { createRequire } from 'node:module'
+
+const { extractRawColors } = createRequire(import.meta.url)(
+  '../../eslint-rules/raw-color-patterns.js'
+) as { extractRawColors: (text: string) => Array<{ value: string; id: string }> }
+
+const ids = (text: string) => extractRawColors(text).map((c) => c.id)
+const values = (text: string) => extractRawColors(text).map((c) => c.value)
+
+/**
+ * Detection for the `no-raw-color` ratchet. The rule and its baseline generator
+ * share this module, so a gap here silently widens the allowance rather than
+ * failing loudly — worth pinning the notations directly.
+ */
+describe('extractRawColors', () => {
+  it('detects every hex length', () => {
+    expect(ids('#fff')).toEqual(['hex'])
+    expect(ids('#ffff')).toEqual(['hex'])
+    expect(ids('#1C1916')).toEqual(['hex'])
+    expect(ids('#1C1916FF')).toEqual(['hex'])
+  })
+
+  it('detects functional notations, including ones with no occurrences today', () => {
+    for (const text of [
+      'rgb(1,2,3)',
+      'rgba(1,2,3,0.5)',
+      'hsl(1 2% 3%)',
+      'hsla(1,2%,3%,0.5)',
+      'oklch(0.5 0.2 30)',
+      'lab(50% 40 59)',
+      'color-mix(in oklch, red, blue)',
+    ]) {
+      expect(ids(text), text).toContain('functional')
+    }
+  })
+
+  it('detects Tailwind colour utilities but not layout classes', () => {
+    expect(ids('bg-red-500')).toEqual(['twPalette'])
+    expect(ids('text-slate-200')).toEqual(['twPalette'])
+    expect(ids('bg-white')).toEqual(['twAchromatic'])
+    expect(ids('bg-[#1C1C1C]')).toEqual(['twArbitrary'])
+    expect(ids('flex flex-row gap-2 p-4 rounded-lg')).toEqual([])
+    // Semantic utilities are the desired output, not violations.
+    expect(ids('bg-surface-raised text-text-primary')).toEqual([])
+  })
+
+  it('treats a bare keyword as a colour only when it is the whole value', () => {
+    expect(ids('white')).toEqual(['named'])
+    expect(ids('  black  ')).toEqual(['named'])
+    // Prose and identifiers must not match, or every comment becomes a violation.
+    expect(ids('white text on a black plane')).toEqual([])
+    expect(ids('whiteboard')).toEqual([])
+  })
+
+  it('does not flag absence or inheritance', () => {
+    // `transparent` encodes absence and `currentColor` defers to the cascade;
+    // neither has a token equivalent.
+    expect(ids('transparent')).toEqual([])
+    expect(ids('currentColor')).toEqual([])
+  })
+
+  it('normalises case so #FFF and #fff are the same debt', () => {
+    expect(values('#ABCDEF')).toEqual(['#abcdef'])
+  })
+
+  it('extracts every colour in a multi-colour literal', () => {
+    // The baseline funds each one, so both have to come back.
+    expect(values('linear-gradient(#111111, #222222)')).toEqual(['#111111', '#222222'])
+  })
+})