@titan-design/react-ui 0.12.1 → 0.14.0

package/src/components/ui/trigger/TriggerSurface.tsx

@@ -0,0 +1,81 @@
+import React, { isValidElement, cloneElement } from 'react'
+import { Pressable, type AccessibilityState } from 'react-native'
+
+type Handler = (...args: never[]) => void
+type Handlers = Record<string, Handler | undefined>
+
+export interface TriggerSurfaceProps {
+  /** Pressable handlers (onPress, onHoverIn, …) for whichever element owns the interaction. */
+  handlers: Handlers
+  /** Role for the wrapper when it is the one handling the interaction. */
+  accessibilityRole?: 'button'
+  /** Merged onto whichever element ends up owning the interaction. */
+  accessibilityState?: AccessibilityState
+  className?: string
+  children: React.ReactNode
+}
+
+type ComposableChildProps = Handlers & { accessibilityState?: AccessibilityState }
+
+function chain(childHandler: Handler | undefined, ownHandler: Handler | undefined): Handler {
+  return (...args: never[]) => {
+    childHandler?.(...args)
+    ownHandler?.(...args)
+  }
+}
+
+/**
+ * Give interaction handling to a composed child instead of wrapping it in a second Pressable.
+ *
+ * React Native Web lets only the innermost pressable in a chain handle a gesture:
+ * PressResponder calls `stopPropagation()` on the click that drives `onPress`,
+ * and `useHover` contains hover the same way. A trigger that wraps a `Pressable`
+ * child (a `Button`, say) in its own `Pressable` therefore never sees the
+ * interaction — in a browser the trigger looks completely dead.
+ *
+ * A component child may be a Pressable, so the handlers are cloned onto it and
+ * the wrapper drops the button role — that also leaves one `[role=button]`
+ * rather than an invalid button-inside-button pair. The wrapper stays a
+ * Pressable, out of the tab order, to still catch children that turn out not to
+ * be pressable. Host elements (`<button>`, `<span>`) cannot take these handlers
+ * and do not swallow the gesture, so for those the wrapper handles it.
+ */
+export function TriggerSurface({
+  handlers,
+  accessibilityRole,
+  accessibilityState,
+  className,
+  children,
+}: TriggerSurfaceProps) {
+  const child = isValidElement(children) ? children : null
+  const childCanCompose = child !== null && typeof child.type !== 'string'
+
+  if (!childCanCompose) {
+    return (
+      <Pressable
+        accessibilityRole={accessibilityRole}
+        accessibilityState={accessibilityState}
+        className={className}
+        {...handlers}
+      >
+        {children}
+      </Pressable>
+    )
+  }
+
+  const childElement = child as React.ReactElement<ComposableChildProps>
+  const composed: ComposableChildProps = {}
+  for (const [name, handler] of Object.entries(handlers)) {
+    composed[name] = chain(childElement.props[name], handler)
+  }
+  composed.accessibilityState = {
+    ...childElement.props.accessibilityState,
+    ...accessibilityState,
+  }
+
+  return (
+    <Pressable focusable={false} tabIndex={-1} className={className} {...handlers}>
+      {cloneElement(childElement, composed)}
+    </Pressable>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { TriggerSurface } from './TriggerSurface'
+export type { TriggerSurfaceProps } from './TriggerSurface'

package/src/stories/PresetShowcase.stories.tsx

@@ -70,9 +70,7 @@ function SideBySideShowcase() {
   return (
     <View className="gap-6 p-6 bg-background-default min-h-screen">
       <View className="gap-2">
-        <Text className="text-3xl font-bold text-text-primary font-heading">
-          Preset Showcase
-        </Text>
+        <Text className="text-3xl font-bold text-text-primary font-heading">Preset Showcase</Text>
         <Text className="text-text-secondary text-base">
           Toggle between presets to see how the entire design system adapts.
         </Text>
@@ -89,14 +87,14 @@ function SideBySideShowcase() {
           Subheading (font-heading)
         </Text>
         <Text className="text-base text-text-primary font-body">
-          Body text using font-body. The quick brown fox jumps over the lazy dog. This
-          demonstrates how paragraph text renders under the current preset.
+          Body text using font-body. The quick brown fox jumps over the lazy dog. This demonstrates
+          how paragraph text renders under the current preset.
         </Text>
         <Text className="text-sm text-text-secondary font-body">
           Secondary body text for captions and supporting content.
         </Text>
         <Text className="text-sm text-text-primary font-mono">
-          {'const monospace = \'font-mono rendering\''}
+          {"const monospace = 'font-mono rendering'"}
         </Text>
       </Section>
 
@@ -195,20 +193,40 @@ function SideBySideShowcase() {
       {/* Toasts */}
       <Section title="Toasts">
         <View className="gap-3">
-          <Toast title="Operation successful" description="Your changes have been saved." status="success" />
-          <Toast title="Something went wrong" description="Please try again later." status="error" />
+          <Toast
+            title="Operation successful"
+            description="Your changes have been saved."
+            status="success"
+          />
+          <Toast
+            title="Something went wrong"
+            description="Please try again later."
+            status="error"
+          />
           <Toast title="Heads up" description="This action cannot be undone." status="warning" />
-          <Toast title="New update available" description="Version 2.0 is ready to install." status="info" />
+          <Toast
+            title="New update available"
+            description="Version 2.0 is ready to install."
+            status="info"
+          />
         </View>
       </Section>
 
       {/* Status Colors */}
       <Section title="Status Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <Badge color="success" size="lg">Success</Badge>
-          <Badge color="error" size="lg">Error</Badge>
-          <Badge color="warning" size="lg">Warning</Badge>
-          <Badge color="info" size="lg">Info</Badge>
+          <Badge color="success" size="lg">
+            Success
+          </Badge>
+          <Badge color="error" size="lg">
+            Error
+          </Badge>
+          <Badge color="warning" size="lg">
+            Warning
+          </Badge>
+          <Badge color="info" size="lg">
+            Info
+          </Badge>
         </View>
       </Section>
     </View>
@@ -225,9 +243,7 @@ function TypographyShowcase() {
   return (
     <View className="gap-6 p-6 bg-background-default min-h-screen">
       <View className="gap-2">
-        <Text className="text-3xl font-bold text-text-primary font-heading">
-          Typography
-        </Text>
+        <Text className="text-3xl font-bold text-text-primary font-heading">Typography</Text>
         <Text className="text-text-secondary text-base">
           How fonts and text styles change across presets.
         </Text>
@@ -252,9 +268,9 @@ function TypographyShowcase() {
 
       <Section title="Body Font (font-body)">
         <Text className="text-base text-text-primary font-body">
-          Regular body text. Design systems provide a shared language for product teams.
-          By codifying decisions into reusable components and tokens, teams move faster
-          while maintaining visual consistency across every surface.
+          Regular body text. Design systems provide a shared language for product teams. By
+          codifying decisions into reusable components and tokens, teams move faster while
+          maintaining visual consistency across every surface.
         </Text>
         <Text className="text-base font-semibold text-text-primary font-body">
           Bold body text. Emphasis and hierarchy within paragraph content.
@@ -263,8 +279,8 @@ function TypographyShowcase() {
           Italic body text. Used for quotations, citations, and emphasis.
         </Text>
         <Text className="text-sm text-text-secondary font-body">
-          Small / secondary text. Captions, labels, and supporting information
-          that supplements the main content without competing for attention.
+          Small / secondary text. Captions, labels, and supporting information that supplements the
+          main content without competing for attention.
         </Text>
         <Text className="text-xs text-text-tertiary font-body">
           Extra-small / tertiary text. Timestamps, metadata, fine print.
@@ -287,19 +303,14 @@ function TypographyShowcase() {
 
       <Section title="Mixed Typography">
         <Card className="p-5 gap-3">
-          <Text className="text-2xl font-bold text-text-primary font-heading">
-            Chapter One
-          </Text>
+          <Text className="text-2xl font-bold text-text-primary font-heading">Chapter One</Text>
           <Text className="text-base text-text-secondary font-body">
-            It was a bright cold day in April, and the clocks were striking thirteen.
-            Winston Smith, his chin nuzzled into his breast in an effort to escape the
-            vile wind, slipped quickly through the glass doors of Victory Mansions,
-            though not quickly enough to prevent a swirl of gritty dust from entering
-            along with him.
-          </Text>
-          <Text className="text-xs text-text-tertiary font-mono">
-            George Orwell, 1984
+            It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith,
+            his chin nuzzled into his breast in an effort to escape the vile wind, slipped quickly
+            through the glass doors of Victory Mansions, though not quickly enough to prevent a
+            swirl of gritty dust from entering along with him.
           </Text>
+          <Text className="text-xs text-text-tertiary font-mono">George Orwell, 1984</Text>
         </Card>
       </Section>
     </View>
@@ -313,7 +324,7 @@ function TypographyShowcase() {
 function ColorSwatch({
   label,
   className,
-  textClass = 'text-white',
+  textClass = 'text-on-brand-primary',
 }: {
   label: string
   className: string
@@ -332,9 +343,7 @@ function ColorPaletteShowcase() {
   return (
     <View className="gap-6 p-6 bg-background-default min-h-screen">
       <View className="gap-2">
-        <Text className="text-3xl font-bold text-text-primary font-heading">
-          Color Palette
-        </Text>
+        <Text className="text-3xl font-bold text-text-primary font-heading">Color Palette</Text>
         <Text className="text-text-secondary text-base">
           Semantic color tokens rendered as swatches. Toggle presets to compare palettes.
         </Text>
@@ -347,13 +356,21 @@ function ColorPaletteShowcase() {
           <ColorSwatch label="brand-primary" className="bg-brand-primary" />
           <ColorSwatch label="brand-primary-light" className="bg-brand-primary-light" />
           <ColorSwatch label="brand-primary-dark" className="bg-brand-primary-dark" />
-          <ColorSwatch label="brand-primary-subtle" className="bg-brand-primary-subtle" textClass="text-text-primary" />
+          <ColorSwatch
+            label="brand-primary-subtle"
+            className="bg-brand-primary-subtle"
+            textClass="text-text-primary"
+          />
         </View>
         <View className="flex-row gap-3 flex-wrap mt-2">
           <ColorSwatch label="brand-secondary" className="bg-brand-secondary" />
           <ColorSwatch label="brand-secondary-light" className="bg-brand-secondary-light" />
           <ColorSwatch label="brand-secondary-dark" className="bg-brand-secondary-dark" />
-          <ColorSwatch label="brand-secondary-subtle" className="bg-brand-secondary-subtle" textClass="text-text-primary" />
+          <ColorSwatch
+            label="brand-secondary-subtle"
+            className="bg-brand-secondary-subtle"
+            textClass="text-text-primary"
+          />
         </View>
       </Section>
 
@@ -372,7 +389,9 @@ function ColorPaletteShowcase() {
             <Text className="text-xs font-mono font-medium text-text-primary">text-primary</Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-hairline">
-            <Text className="text-xs font-mono font-medium text-text-secondary">text-secondary</Text>
+            <Text className="text-xs font-mono font-medium text-text-secondary">
+              text-secondary
+            </Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-hairline">
             <Text className="text-xs font-mono font-medium text-text-tertiary">text-tertiary</Text>
@@ -382,26 +401,60 @@ function ColorPaletteShowcase() {
 
       <Section title="Surface Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <ColorSwatch label="surface-base" className="bg-surface-base border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-elevated" className="bg-surface-elevated border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-raised" className="bg-surface-raised border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-overlay" className="bg-surface-overlay border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-input" className="bg-surface-input border border-hairline" textClass="text-text-primary" />
+          <ColorSwatch
+            label="surface-base"
+            className="bg-surface-base border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-elevated"
+            className="bg-surface-elevated border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-raised"
+            className="bg-surface-raised border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-overlay"
+            className="bg-surface-overlay border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-input"
+            className="bg-surface-input border border-hairline"
+            textClass="text-text-primary"
+          />
         </View>
       </Section>
 
       <Section title="Background Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <ColorSwatch label="background-base" className="bg-background-base border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="background-default" className="bg-background-default border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="background-subtle" className="bg-background-subtle border border-hairline" textClass="text-text-primary" />
+          <ColorSwatch
+            label="background-base"
+            className="bg-background-base border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="background-default"
+            className="bg-background-default border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="background-subtle"
+            className="bg-background-subtle border border-hairline"
+            textClass="text-text-primary"
+          />
         </View>
       </Section>
 
       <Section title="Border Colors">
         <View className="flex-row gap-3 flex-wrap">
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-hairline-default">
-            <Text className="text-xs font-mono font-medium text-text-primary">hairline-default</Text>
+            <Text className="text-xs font-mono font-medium text-text-primary">
+              hairline-default
+            </Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-hairline-subtle">
             <Text className="text-xs font-mono font-medium text-text-primary">hairline-subtle</Text>

package/src/test/no-device-internals.test.ts

@@ -21,13 +21,13 @@ describe('no-device-internals', () => {
         // Dimension and ratio strings: the `\b` guard before `0x` means a digit
         // followed by `x` never reads as a hex literal. These exact strings
         // tripped an earlier, looser sweep.
-        { code: "// icons render at 20x20" },
-        { code: "// 200x400 intrinsic -> ~160x320 px" },
+        { code: '// icons render at 20x20' },
+        { code: '// 200x400 intrinsic -> ~160x320 px' },
         // SVG path coordinates — digit-only runs are not byte frames.
         { code: 'const d = "M12 2 22 12 12 22 2 12Z"' },
         { code: 'const d = "M7 7 17 17 12 22 12 2 17 7 7 17"' },
         // Timestamps — `-` and `:` are not byte separators.
-        { code: "// datetime // 2024-01-15 14:30" },
+        { code: '// datetime // 2024-01-15 14:30' },
         // "cascade" in its CSS sense is ordinary styling vocabulary.
         { code: "// RN doesn't cascade text color, so hand-color the text" },
         // Plain numbers and durations.

package/src/test/no-raw-color.test.ts

@@ -0,0 +1,39 @@
+import { RuleTester } from 'eslint'
+import rule from '../../eslint-rules/no-raw-color'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    parserOptions: { ecmaFeatures: { jsx: true } },
+  },
+})
+
+describe('no-raw-color', () => {
+  it('skips false positives while still flagging real raw colour', () => {
+    ruleTester.run('no-raw-color', rule as never, {
+      valid: [
+        // (a) enum-typed prop value: a bare colour word passed as color/variant/tone.
+        { code: '<Spinner color="white" />' },
+        // (a) the same enum's members listed in a Storybook argTypes options array.
+        {
+          code: "const meta = { argTypes: { color: { control: 'select', options: ['primary', 'white'] } } }",
+        },
+        // (b) { value, label } demo data reusing colour words as IDs.
+        { code: "const colorOptions = [{ value: 'red', label: 'Red' }]" },
+        // (c) documentation text in a <Text> element's children.
+        { code: '<Text>{`background-color: #3C3C3C;`}</Text>' },
+      ],
+      invalid: [
+        // Positive control: a real raw hex in a style prop must still be flagged,
+        // including on a <Text> element — only its *children* are exempt.
+        {
+          code: "<Text style={{ backgroundColor: '#123456' }} />",
+          errors: [{ messageId: 'hex' }],
+        },
+        // Positive control: a bare colour word outside any exempt shape is still named.
+        { code: "const bg = 'white'", errors: [{ messageId: 'named' }] },
+      ],
+    })
+  })
+})

package/src/theme/Alpha.stories.tsx

@@ -0,0 +1,103 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { alpha } from '../utils/colors'
+import { getSemanticColors } from './tokens/semantic'
+import { primitiveColors } from './tokens/primitives'
+import { SectionIntro, SectionTitle, SWATCH_BORDER } from './color-story-kit'
+
+const t = getSemanticColors('dark')
+
+/**
+ * Foundations/Color/Alpha — deriving a translucent colour from a token instead
+ * of hardcoding an `rgba(...)` triple.
+ *
+ * `alpha(color, opacity)` (`packages/ui/src/utils/colors.ts`) takes a RESOLVED
+ * colour — a hex string or an `rgb()`/`rgba()` string, e.g. a semantic token's
+ * value or a primitive — and returns it as `rgba(r, g, b, opacity)`. It does
+ * NOT take a token name: `alpha('brand-primary', 0.1)` would try to parse the
+ * literal string `'brand-primary'` as a colour and fail. Resolve the token
+ * first (`t['brand-primary']`, `primitiveColors.white`, …), then wrap it.
+ *
+ * The payoff over a hand-picked `rgba(255, 121, 0, 0.1)`: when a ramp gets
+ * re-spaced or a semantic mapping moves, every `alpha()` call built on that
+ * token moves with it. A literal triple silently drifts from the token it was
+ * copied from and stays wrong until someone notices — the failure mode VW-78
+ * was opened to burn down (see `eslint-rules/raw-color-baseline.json`,
+ * enforced by `no-raw-color`'s `functional` rule).
+ */
+const meta: Meta = {
+  title: 'Foundations/Color/Alpha',
+  tags: ['autodocs'],
+}
+
+export default meta
+
+const EXAMPLES = [
+  { name: 'brand-primary @ 0.12', value: alpha(t['brand-primary'], 0.12) },
+  { name: 'status-success @ 0.15', value: alpha(t['status-success'], 0.15) },
+  { name: 'status-warning @ 0.25', value: alpha(t['status-warning'], 0.25) },
+  { name: 'status-error @ 0.3', value: alpha(t['status-error'], 0.3) },
+  { name: 'primitiveColors.white @ 0.08', value: alpha(primitiveColors.white, 0.08) },
+] as const
+
+function AlphaSwatch({ name, value }: { name: string; value: string }) {
+  return (
+    <View style={{ alignItems: 'center', width: 96 }}>
+      <View
+        style={{
+          width: 96,
+          height: 64,
+          borderRadius: 8,
+          backgroundColor: t['surface-elevated'],
+          borderWidth: 1,
+          borderColor: SWATCH_BORDER,
+          overflow: 'hidden',
+        }}
+      >
+        <View style={{ flex: 1, backgroundColor: value }} />
+      </View>
+      <Text className="text-text-secondary text-xs mt-1" style={{ textAlign: 'center' }}>
+        {name}
+      </Text>
+      <Text className="text-text-tertiary" style={{ fontSize: 9, marginTop: 1 }}>
+        {value}
+      </Text>
+    </View>
+  )
+}
+
+export const Default: StoryObj = {
+  render: () => (
+    <View style={{ padding: 24 }}>
+      <Text className="text-2xl font-bold text-text-primary mb-2">Alpha</Text>
+      <SectionIntro>
+        `alpha(color, opacity)` derives a translucent colour from a RESOLVED token or primitive
+        instead of a hand-picked `rgba(...)` triple, so the wash tracks the token it came from. Each
+        swatch below is rendered over the elevated surface plane so the translucency is visible.
+      </SectionIntro>
+
+      <SectionTitle>Usage</SectionTitle>
+      <View
+        style={{
+          backgroundColor: t['surface-raised'],
+          borderRadius: 8,
+          padding: 12,
+          marginBottom: 20,
+        }}
+      >
+        <Text className="text-text-secondary" style={{ fontFamily: 'monospace', fontSize: 12 }}>
+          {"import { alpha } from '@/utils/colors'\n\n"}
+          {"const t = getSemanticColors('dark')\n"}
+          {"const wash = alpha(t['brand-primary'], 0.12)"}
+        </Text>
+      </View>
+
+      <SectionTitle>Examples</SectionTitle>
+      <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 16 }}>
+        {EXAMPLES.map((example) => (
+          <AlphaSwatch key={example.name} {...example} />
+        ))}
+      </View>
+    </View>
+  ),
+}

package/src/theme/ChoosingTokens.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import tokensDoc from '../../TOKENS.md?raw'
+import { Typography } from '../components/custom/Typography'
+
+/**
+ * Rendered straight from `packages/ui/TOKENS.md` via Vite's `?raw`, deliberately
+ * as its markdown source rather than a hand-built React page. A prettier page
+ * would be a second copy of the rules that can drift from the file — and a token
+ * guide that disagrees with itself is worse than a plain one. The content is
+ * mostly aligned tables, which read fine in mono.
+ */
+function ChoosingTokens() {
+  return (
+    <View className="gap-4 p-6">
+      <Typography variant="h3" className="text-text-primary">
+        Choosing tokens
+      </Typography>
+      <Typography variant="body2" className="text-text-secondary">
+        The decision table to read before writing a component. Source of truth:{' '}
+        <Text className="font-mono text-text-primary">packages/ui/TOKENS.md</Text> — this page
+        renders that file, so the two cannot disagree.
+      </Typography>
+      <View className="rounded-lg bg-surface-raised p-4">
+        <Text className="font-mono text-xs leading-5 text-text-secondary">{tokensDoc}</Text>
+      </View>
+    </View>
+  )
+}
+
+const meta: Meta<typeof ChoosingTokens> = {
+  title: 'Foundations/Choosing Tokens',
+  component: ChoosingTokens,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Which palette for which meaning, how to resolve a colour in code, and the type/spacing ' +
+          'scales. Rendered from `packages/ui/TOKENS.md`.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof ChoosingTokens>
+
+export const Default: Story = {}