@titan-design/react-ui 0.2.5 → 0.2.7

package/docs/WEB_SETUP.md

@@ -0,0 +1,217 @@
+# Web Consumer Setup
+
+How to use `@titan-design/react-ui` in a Vite-based web application.
+
+## Prerequisites
+
+- **Vite** 5+ with `@vitejs/plugin-react`
+- **Tailwind CSS** 3.4+
+- **react-native-web** 0.19+
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+npm install @titan-design/react-ui react-native-web
+npm install -D tailwindcss autoprefixer postcss nativewind
+```
+
+> `nativewind` is an **optional peer dependency** and only needed at build time — it
+> provides a Tailwind preset that adds React Native platform variants (`web:`,
+> `native:`) used by titan components. It is NOT needed at runtime on web.
+> Install it as a dev dependency so Tailwind can resolve the preset.
+
+### 2. Configure Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      'react-native': 'react-native-web',
+    },
+  },
+})
+```
+
+That's it. No `jsxImportSource`, no `optimizeDeps`, no `resolve.dedupe`.
+
+### 3. Configure Tailwind CSS
+
+```js
+// tailwind.config.js
+const titanConfig = require('@titan-design/react-ui/tailwind.config.js')
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@titan-design/react-ui/dist/**/*.{js,mjs}',
+  ],
+  presets: [titanConfig],
+  darkMode: 'class',
+}
+```
+
+The `titanConfig` preset includes `nativewind/preset` which registers the `web:` and
+`native:` Tailwind variants that titan components use (e.g., `web:hover:bg-gray-100`).
+
+### 4. Configure PostCSS
+
+```js
+// postcss.config.js
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
+```
+
+### 5. Import global CSS
+
+```tsx
+// main.tsx or App.tsx
+import '@titan-design/react-ui/theme/global.css'
+```
+
+This loads the design token CSS custom properties (colors, typography, spacing, etc.).
+
+### 6. Use components
+
+```tsx
+import { Button, ButtonText, Card, CardContent } from '@titan-design/react-ui'
+
+function App() {
+  return (
+    <Card>
+      <CardContent>
+        <Button color="primary">
+          <ButtonText>Hello</ButtonText>
+        </Button>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+---
+
+## How It Works
+
+Titan's web distribution (the `dist/` you import) uses a custom JSX runtime
+that converts `className` props to
+[`$$css` style objects](https://github.com/nicholasxjy/styleq#compiled-styles)
+at **build time**. react-native-web's `styleq` recognizes these objects and
+applies their values as CSS class names on DOM elements.
+
+This means:
+- No NativeWind runtime needed on web
+- No `interopComponents` Map lookup (which breaks under Vite module deduplication)
+- No `jsxImportSource: 'nativewind'` configuration needed
+- className and inline `style` work together correctly (inline style wins on conflicts)
+
+### Native React Native
+
+On native (iOS/Android), Metro resolves the `react-native` export condition in
+titan's `package.json`, which points to source files. NativeWind's Babel plugin
+(configured in your Metro/Expo setup) handles `className` natively.
+
+---
+
+## Migration from NativeWind-based Setup
+
+If you previously configured NativeWind's runtime interop, here's what to remove:
+
+### Remove from `vite.config.ts`
+
+```diff
+  plugins: [
+-   react({ jsxImportSource: 'nativewind' }),
++   react(),
+  ],
+  resolve: {
+    alias: { 'react-native': 'react-native-web' },
+-   dedupe: ['react-native-web'],
+  },
+- optimizeDeps: {
+-   esbuildOptions: {
+-     loader: { '.js': 'jsx' },
+-   },
+- },
+```
+
+### Remove `setup-interop.ts`
+
+Delete any file that re-registers `cssInterop` for View/Text/Pressable.
+This was a workaround for Vite's module deduplication breaking
+NativeWind's `interopComponents` Map. It is no longer needed.
+
+```diff
+  // main.tsx
+- import './setup-interop'
+  import '@titan-design/react-ui/theme/global.css'
+```
+
+### Remove runtime dependencies
+
+```bash
+npm uninstall nativewind react-native-css-interop
+npm install -D nativewind  # keep as dev dep for Tailwind preset only
+```
+
+### Remove `conditions` from Vite resolve
+
+If you were using `conditions: ['react-native']` to resolve titan's source
+files, remove it. The dist now handles className conversion internally.
+
+```diff
+  resolve: {
+-   conditions: ['react-native', 'import'],
+    alias: { 'react-native': 'react-native-web' },
+  },
+```
+
+---
+
+## Troubleshooting
+
+### Tailwind classes not appearing
+
+1. Verify your `tailwind.config.js` content array includes titan's dist:
+   ```js
+   content: [
+     './node_modules/@titan-design/react-ui/dist/**/*.{js,mjs}',
+   ]
+   ```
+2. Verify PostCSS is configured with the `tailwindcss` plugin
+3. Verify you imported `@titan-design/react-ui/theme/global.css`
+
+### Layout properties not applying (flexDirection, alignItems, etc.)
+
+This was the original NativeWind interop issue. If you see this after upgrading,
+ensure you've updated `@titan-design/react-ui` to a version with the custom
+JSX runtime (0.3.0+). Older versions require the NativeWind runtime setup.
+
+### Your own `<View className="...">` components don't get styles
+
+Titan's custom JSX runtime only applies to titan's pre-built dist. If your app
+code directly uses React Native primitives with className, you have two options:
+
+1. **Use standard CSS/Tailwind on web**: Write `<div className="flex-row">` for
+   your own web-only components
+2. **Set up NativeWind for your app's JSX**: Add `jsxImportSource: 'nativewind'`
+   to your Vite React plugin config. This only affects your app's source files
+   (titan's dist is already handled)
+
+### Using titan with Webpack instead of Vite
+
+The same principle applies. You need:
+1. `react-native` → `react-native-web` alias (via `resolve.alias` in webpack config)
+2. Tailwind CSS configured with titan's content paths
+3. No NativeWind runtime setup needed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titan-design/react-ui",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Cross-platform design system built on Gluestack UI",
   "author": "Henry Jewkes",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/generate-tokens-css.mjs",
     "dev": "tsup --watch",
     "lint": "eslint src/",
     "lint:borders": "bash scripts/check-border-classes.sh",
@@ -62,19 +62,27 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "react-native": ">=0.72.0",
+    "react-native-body-highlighter": ">=3.0.0",
+    "react-native-svg": ">=15.0.0",
     "react-native-web": ">=0.19.0"
   },
   "peerDependenciesMeta": {
+    "lucide-react-native": {
+      "optional": true
+    },
     "nativewind": {
       "optional": true
     },
     "react-native": {
       "optional": true
     },
-    "react-native-web": {
+    "react-native-body-highlighter": {
       "optional": true
     },
-    "lucide-react-native": {
+    "react-native-svg": {
+      "optional": true
+    },
+    "react-native-web": {
       "optional": true
     }
   },
@@ -85,7 +93,6 @@
     "tailwind-merge": "^2.6.0"
   },
   "devDependencies": {
-    "nativewind": "^4.2.1",
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.58.2",
     "@storybook/addon-a11y": "^10.2.0",
@@ -108,9 +115,13 @@
     "jest-axe": "^9.0.0",
     "jsdom": "^25.0.0",
     "lucide-react": "^0.469.0",
+    "nativewind": "^4.2.1",
     "prettier": "^3.8.1",
     "react": "^18.3.0",
     "react-dom": "^18.3.0",
+    "react-hook-form": "^7.54.2",
+    "react-native-body-highlighter": "^3.2.0",
+    "react-native-svg": "^15.15.5",
     "react-native-web": "^0.19.0",
     "storybook": "^10.2.0",
     "tailwindcss": "^3.4.0",
@@ -123,6 +134,7 @@
   "files": [
     "dist",
     "src",
+    "docs",
     "tailwind.config.js"
   ],
   "sideEffects": false,

package/src/components/custom/DateTime/DateTime.stories.tsx

@@ -169,7 +169,7 @@ export const UsageExample: Story = {
       <View className="gap-2 p-4 bg-surface-elevated rounded-lg max-w-md">
         <Text className="text-lg font-semibold text-text-primary mb-2">Upcoming Events</Text>
         {items.map((item, index) => (
-          <View key={index} className="flex-row justify-between items-center py-2 border-b border-border-default">
+          <View key={index} className="flex-row justify-between items-center py-2 border-b border-border">
             <Text className="text-text-primary">{item.title}</Text>
             <DateTime value={item.date} format="relative" color="secondary" className="text-sm" />
           </View>

package/src/components/custom/Gauge/Gauge.stories.tsx

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Gauge } from './Gauge'
+
+const meta: Meta<typeof Gauge> = {
+  title: 'Custom/Gauge',
+  component: Gauge,
+  tags: ['autodocs'],
+  argTypes: {
+    value: { control: { type: 'range', min: 0, max: 100, step: 1 } },
+    size: { control: { type: 'range', min: 100, max: 320, step: 10 } },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Gauge>
+
+export const Healthy: Story = {
+  args: { value: 88, unit: '%', label: 'Health', size: 180 },
+}
+
+export const Warning: Story = {
+  args: { value: 68, unit: '%', label: 'Health', size: 180 },
+}
+
+export const Critical: Story = {
+  args: { value: 34, unit: '%', label: 'Health', size: 180 },
+}
+
+/** A codewatch-style status readout — arbitrary domain, no unit. */
+export const ArbitraryDomain: Story = {
+  args: { value: 7.4, min: 0, max: 10, label: 'Maintainability', size: 200 },
+}
+
+/** Single-color override ignores the threshold bands. */
+export const OverrideColor: Story = {
+  args: { value: 55, unit: '%', label: 'Coverage', color: '#5B9BD5', size: 180 },
+}
+
+/** Value above max is clamped for the fill but shown verbatim. */
+export const OverMax: Story = {
+  args: { value: 120, unit: '%', label: 'Load', size: 180 },
+}
+
+export const Zero: Story = {
+  args: { value: 0, unit: '%', label: 'Health', size: 180 },
+}

package/src/components/custom/Gauge/Gauge.test.tsx

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { Gauge } from './Gauge'
+
+describe('Gauge', () => {
+  it('renders the arc as a fixed set of segments', () => {
+    render(<Gauge value={50} />)
+    expect(screen.getAllByTestId('gauge-segment')).toHaveLength(40)
+  })
+
+  it('renders the value, unit, and label', () => {
+    render(<Gauge value={82} unit="%" label="Health" />)
+    expect(screen.getByTestId('gauge-value')).toHaveTextContent('82')
+    expect(screen.getByTestId('gauge-label')).toHaveTextContent('Health')
+    expect(screen.getByText('%')).toBeInTheDocument()
+  })
+
+  it('colors the value by the active status band', () => {
+    const { rerender } = render(<Gauge value={30} />)
+    expect(screen.getByTestId('gauge-value')).toHaveStyle({ color: '#D14343' })
+    rerender(<Gauge value={70} />)
+    expect(screen.getByTestId('gauge-value')).toHaveStyle({ color: '#FFB020' })
+    rerender(<Gauge value={90} />)
+    expect(screen.getByTestId('gauge-value')).toHaveStyle({ color: '#14B8A6' })
+  })
+
+  it('honors a single-color override over thresholds', () => {
+    render(<Gauge value={10} color="#5B9BD5" />)
+    expect(screen.getByTestId('gauge-value')).toHaveStyle({ color: '#5B9BD5' })
+  })
+
+  it('clamps an out-of-range value without crashing', () => {
+    render(<Gauge value={150} unit="%" />)
+    // Displayed value is verbatim; only the fill is clamped.
+    expect(screen.getByTestId('gauge-value')).toHaveTextContent('150')
+    expect(screen.getAllByTestId('gauge-segment')).toHaveLength(40)
+  })
+
+  it('supports an arbitrary min/max domain', () => {
+    render(<Gauge value={5} min={0} max={10} label="Score" />)
+    expect(screen.getByTestId('gauge-value')).toHaveTextContent('5')
+  })
+
+  it('respects custom thresholds', () => {
+    render(
+      <Gauge
+        value={45}
+        thresholds={[
+          { value: 0, color: '#14B8A6' },
+          { value: 50, color: '#D14343' },
+        ]}
+      />,
+    )
+    expect(screen.getByTestId('gauge-value')).toHaveStyle({ color: '#14B8A6' })
+  })
+
+  describe('accessibility', () => {
+    it('exposes an image role with a descriptive label', () => {
+      render(<Gauge value={82} unit="%" label="Health" />)
+      const gauge = screen.getByTestId('gauge')
+      expect(gauge).toHaveAttribute('role', 'img')
+      expect(gauge.getAttribute('aria-label')).toContain('Health: 82% of 100')
+    })
+
+    it('has no accessibility violations', async () => {
+      const { container } = render(<Gauge value={82} unit="%" label="Health" />)
+      expect(await axe(container)).toHaveNoViolations()
+    })
+  })
+})

package/src/components/custom/Gauge/Gauge.tsx

@@ -0,0 +1,167 @@
+import { View, Text, type ViewProps } from 'react-native'
+import { cn } from '../../../utils/cn'
+
+export interface GaugeThreshold {
+  /** Band start, in the gauge's value units. */
+  value: number
+  /** Color applied to filled segments at or above this band. */
+  color: string
+}
+
+export interface GaugeProps extends Omit<ViewProps, 'children'> {
+  /** Current value. Clamped to [min, max]. */
+  value: number
+  min?: number
+  max?: number
+  /** Diameter in px. */
+  size?: number
+  /** Caption under the big number. */
+  label?: string
+  /** Unit suffix beside the big number (e.g. "%"). */
+  unit?: string
+  /**
+   * Band coloring, ascending by `value`. A filled segment takes the color of
+   * the highest band whose `value` it reaches. Defaults to Titan status tokens
+   * (red < 60, amber < 80, green ≥ 80 on a 0–100 scale).
+   */
+  thresholds?: GaugeThreshold[]
+  /** Single-color override for filled segments (ignores `thresholds`). */
+  color?: string
+  className?: string
+}
+
+const STATUS_SUCCESS = '#14B8A6'
+const STATUS_WARNING = '#FFB020'
+const STATUS_ERROR = '#D14343'
+const TRACK = 'rgba(255,255,255,0.08)'
+
+/** Titan status-token bands for a 0–100 score. */
+const DEFAULT_THRESHOLDS: GaugeThreshold[] = [
+  { value: 0, color: STATUS_ERROR },
+  { value: 60, color: STATUS_WARNING },
+  { value: 80, color: STATUS_SUCCESS },
+]
+
+const ARC_START = 135
+const ARC_SWEEP = 270
+const SEGMENTS = 40
+
+function clamp01(n: number): number {
+  if (Number.isNaN(n)) return 0
+  return Math.max(0, Math.min(1, n))
+}
+
+function formatValue(v: number): string {
+  return Number.isInteger(v) ? `${v}` : v.toFixed(1)
+}
+
+/** Color of the highest band whose start value the fraction reaches. */
+function bandColor(fraction: number, bands: GaugeThreshold[], min: number, max: number): string {
+  const value = min + fraction * (max - min)
+  const sorted = [...bands].sort((a, b) => a.value - b.value)
+  let color = sorted[0]?.color ?? STATUS_SUCCESS
+  for (const band of sorted) {
+    if (value >= band.value) color = band.color
+  }
+  return color
+}
+
+interface Tick {
+  key: number
+  left: number
+  top: number
+  rotate: string
+  color: string
+}
+
+/** Position + color each radial segment of the arc. */
+function buildTicks(fill: number, size: number, activeColor: (f: number) => string): Tick[] {
+  const center = size / 2
+  const radius = center - size * 0.08
+  return Array.from({ length: SEGMENTS }, (_, i) => {
+    const fraction = (i + 0.5) / SEGMENTS
+    const deg = ARC_START + fraction * ARC_SWEEP
+    const rad = (deg * Math.PI) / 180
+    return {
+      key: i,
+      left: center + radius * Math.cos(rad),
+      top: center + radius * Math.sin(rad),
+      rotate: `${deg - 90}deg`,
+      color: fraction <= fill ? activeColor(fraction) : TRACK,
+    }
+  })
+}
+
+/**
+ * SVG-free radial gauge (absolutely-positioned segment Views), matching the
+ * codebase's chart convention so it renders identically on web and native. The
+ * 270° arc fills with band colors as the value rises; the center reuses the
+ * Metric visual language (large bold value + unit + caption). Ideal for a 0–100
+ * health / quality score.
+ */
+export function Gauge({
+  value,
+  min = 0,
+  max = 100,
+  size = 160,
+  label,
+  unit,
+  thresholds = DEFAULT_THRESHOLDS,
+  color,
+  className,
+  ...props
+}: GaugeProps) {
+  const span = max - min || 1
+  const fill = clamp01((value - min) / span)
+  const activeColor = (f: number) => color ?? bandColor(f, thresholds, min, max)
+  const ticks = buildTicks(fill, size, activeColor)
+  const displayColor = color ?? bandColor(fill, thresholds, min, max)
+  const tickLength = size * 0.11
+  const tickThickness = Math.max(2, (size * 0.9) / SEGMENTS)
+
+  const ariaLabel = `${label ? `${label}: ` : ''}${formatValue(value)}${unit ?? ''} of ${formatValue(max)}`
+
+  return (
+    <View
+      className={cn('relative', className)}
+      style={{ width: size, height: size }}
+      accessibilityRole="image"
+      accessibilityLabel={ariaLabel}
+      testID="gauge"
+      {...props}
+    >
+      {ticks.map((t) => (
+        <View
+          key={t.key}
+          accessibilityElementsHidden
+          testID="gauge-segment"
+          style={{
+            position: 'absolute',
+            left: t.left - tickThickness / 2,
+            top: t.top - tickLength / 2,
+            width: tickThickness,
+            height: tickLength,
+            borderRadius: tickThickness / 2,
+            backgroundColor: t.color,
+            transform: [{ rotate: t.rotate }],
+          }}
+        />
+      ))}
+
+      {/* Center readout — Metric visual language. */}
+      <View style={{ position: 'absolute', top: 0, left: 0, width: size, height: size }} className="items-center justify-center">
+        <View className="flex-row items-baseline gap-0.5">
+          <Text testID="gauge-value" className="text-3xl font-bold" style={{ color: displayColor }}>
+            {formatValue(value)}
+          </Text>
+          {unit && <Text className="text-sm text-text-tertiary">{unit}</Text>}
+        </View>
+        {label && (
+          <Text testID="gauge-label" className="text-xs text-text-secondary mt-1">
+            {label}
+          </Text>
+        )}
+      </View>
+    </View>
+  )
+}

package/src/components/custom/Gauge/index.ts

@@ -0,0 +1,2 @@
+export { Gauge } from './Gauge'
+export type { GaugeProps, GaugeThreshold } from './Gauge'

package/src/components/custom/Scatter/Scatter.stories.tsx

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Scatter, type ScatterDatum } from './Scatter'
+
+const meta: Meta<typeof Scatter> = {
+  title: 'Custom/Scatter',
+  component: Scatter,
+  tags: ['autodocs'],
+  argTypes: {
+    width: { control: { type: 'range', min: 240, max: 800, step: 20 } },
+    height: { control: { type: 'range', min: 180, max: 600, step: 20 } },
+    diagonal: { control: 'boolean' },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Scatter>
+
+/** Modules on the instability × abstractness "main sequence". */
+const mainSequence: ScatterDatum[] = [
+  { id: 'core', x: 0.08, y: 0.85, r: 10, color: '#14B8A6', label: 'core' },
+  { id: 'domain', x: 0.22, y: 0.7, r: 8, color: '#14B8A6', label: 'domain' },
+  { id: 'services', x: 0.45, y: 0.4, r: 12, color: '#5B9BD5', label: 'services' },
+  { id: 'api', x: 0.6, y: 0.35, r: 7, color: '#5B9BD5', label: 'api' },
+  { id: 'cli', x: 0.9, y: 0.08, r: 9, color: '#F4A736', label: 'cli' },
+  { id: 'utils', x: 0.85, y: 0.75, r: 6, color: '#F83030', label: 'utils (pain?)' },
+]
+
+export const Default: Story = {
+  args: {
+    data: mainSequence,
+    width: 480,
+    height: 340,
+    diagonal: true,
+    axis: { xLabel: 'Instability (I)', yLabel: 'Abstractness (A)', xMin: 0, xMax: 1, yMin: 0, yMax: 1 },
+  },
+}
+
+export const NoDiagonal: Story = {
+  args: {
+    data: mainSequence,
+    width: 480,
+    height: 340,
+    axis: { xLabel: 'Instability (I)', yLabel: 'Abstractness (A)', xMin: 0, xMax: 1, yMin: 0, yMax: 1 },
+  },
+}
+
+export const Selected: Story = {
+  args: {
+    data: mainSequence,
+    width: 480,
+    height: 340,
+    diagonal: true,
+    selectedId: 'utils',
+    axis: { xLabel: 'Instability (I)', yLabel: 'Abstractness (A)', xMin: 0, xMax: 1, yMin: 0, yMax: 1 },
+  },
+}
+
+/** Auto-domain from a single point — the frame still renders cleanly. */
+export const SinglePoint: Story = {
+  args: {
+    data: [{ id: 'only', x: 0.5, y: 0.5, r: 10, label: 'only module' }],
+    width: 400,
+    height: 300,
+    axis: { xLabel: 'I', yLabel: 'A' },
+  },
+}
+
+/** An outlier far outside the main cluster, kept legible by an explicit domain. */
+export const Outlier: Story = {
+  args: {
+    data: [...mainSequence, { id: 'legacy', x: 0.98, y: 0.98, r: 16, color: '#F83030', label: 'legacy.ts' }],
+    width: 480,
+    height: 340,
+    diagonal: true,
+    axis: { xLabel: 'Instability (I)', yLabel: 'Abstractness (A)', xMin: 0, xMax: 1, yMin: 0, yMax: 1 },
+  },
+}
+
+export const Empty: Story = {
+  args: {
+    data: [],
+    width: 400,
+    height: 300,
+    axis: { xLabel: 'Instability (I)', yLabel: 'Abstractness (A)', xMin: 0, xMax: 1, yMin: 0, yMax: 1 },
+  },
+}