@titan-design/react-ui 0.1.1 → 0.2.6

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.1.1",
+  "version": "0.2.6",
   "description": "Cross-platform design system built on Gluestack UI",
   "author": "Henry Jewkes",
   "license": "MIT",
@@ -41,23 +41,33 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint src/",
+    "lint:borders": "bash scripts/check-border-classes.sh",
     "type-check": "tsc --noEmit",
     "format:check": "prettier --check \"src/**/*.{ts,tsx,css}\"",
     "test": "vitest",
     "test:coverage": "vitest --coverage",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
+    "test:visual": "playwright test",
+    "test:visual:update": "playwright test --update-snapshots",
+    "specimen": "vite --config specimen/vite.config.ts",
+    "specimen:compare": "vite --config specimen/vite.config.ts --open /comparison.html",
+    "test:visual:compare": "playwright test --config playwright.comparison.config.ts",
     "prepublishOnly": "tsup && vitest --run"
   },
   "peerDependencies": {
     "lucide-react": ">=0.400.0",
     "lucide-react-native": ">=0.400.0",
+    "nativewind": "^4.2.1",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "react-native": ">=0.72.0",
     "react-native-web": ">=0.19.0"
   },
   "peerDependenciesMeta": {
+    "nativewind": {
+      "optional": true
+    },
     "react-native": {
       "optional": true
     },
@@ -72,11 +82,12 @@
     "@gluestack-style/react": "^1.0.0",
     "@gluestack-ui/themed": "^1.1.0",
     "clsx": "^2.1.0",
-    "nativewind": "^4.1.0",
     "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",
     "@storybook/addon-docs": "^10.2.0",
     "@storybook/addon-react-native-web": "^0.0.29",
@@ -112,6 +123,7 @@
   "files": [
     "dist",
     "src",
+    "docs",
     "tailwind.config.js"
   ],
   "sideEffects": false,

package/src/components/custom/Workout/RestTimer.stories.tsx

@@ -0,0 +1,71 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { RestTimer } from './RestTimer'
+
+const meta: Meta<typeof RestTimer> = {
+  title: 'Custom/Workout/RestTimer',
+  component: RestTimer,
+  tags: ['autodocs'],
+  argTypes: {
+    totalSeconds: {
+      control: 'number',
+      description: 'Total rest duration in seconds',
+    },
+    elapsedMs: {
+      control: 'number',
+      description: 'Elapsed time in milliseconds',
+    },
+    visible: {
+      control: 'boolean',
+      description: 'Whether the timer is visible',
+    },
+    nextSetInfo: {
+      control: 'text',
+      description: 'Context about the next set',
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof RestTimer>
+
+export const Default: Story = {
+  args: {
+    totalSeconds: 150,
+    elapsedMs: 30000,
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+}
+
+export const NearlyComplete: Story = {
+  args: {
+    totalSeconds: 150,
+    elapsedMs: 145000,
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+}
+
+export const WithNextSetInfo: Story = {
+  args: {
+    totalSeconds: 150,
+    elapsedMs: 30000,
+    onSkip: () => {},
+    onAddTime: () => {},
+    nextSetInfo: 'Bench Press — Set 3 of 4',
+    visible: true,
+  },
+}
+
+export const JustStarted: Story = {
+  args: {
+    totalSeconds: 150,
+    elapsedMs: 0,
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+}

package/src/components/custom/Workout/RestTimer.test.tsx

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { RestTimer } from './RestTimer'
+
+const defaultProps = {
+  totalSeconds: 150,
+  elapsedMs: 30000,
+  onSkip: vi.fn(),
+  onAddTime: vi.fn(),
+  visible: true,
+}
+
+describe('RestTimer', () => {
+  describe('time display formatting', () => {
+    it('displays 2:30 for 150s total with 0 elapsed', () => {
+      render(<RestTimer {...defaultProps} elapsedMs={0} />)
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('2:30')
+    })
+
+    it('displays 2:00 for 150s total with 30s elapsed', () => {
+      render(<RestTimer {...defaultProps} elapsedMs={30000} />)
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('2:00')
+    })
+
+    it('displays 0:05 for 150s total with 145s elapsed', () => {
+      render(<RestTimer {...defaultProps} elapsedMs={145000} />)
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('0:05')
+    })
+
+    it('pads seconds with leading zero', () => {
+      render(<RestTimer {...defaultProps} totalSeconds={65} elapsedMs={0} />)
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('1:05')
+    })
+
+    it('displays 0:00 when elapsed equals total', () => {
+      render(<RestTimer {...defaultProps} elapsedMs={150000} />)
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('0:00')
+    })
+  })
+
+  describe('progress bar', () => {
+    it('sets width to 0% when elapsed is 0', () => {
+      render(<RestTimer {...defaultProps} elapsedMs={0} />)
+      const fill = screen.getByTestId('rest-timer-progress-fill')
+      expect(fill).toHaveStyle({ width: '0%' })
+    })
+
+    it('sets width to 50% when half elapsed', () => {
+      render(<RestTimer {...defaultProps} totalSeconds={100} elapsedMs={50000} />)
+      const fill = screen.getByTestId('rest-timer-progress-fill')
+      expect(fill).toHaveStyle({ width: '50%' })
+    })
+
+    it('clamps width to 100% when elapsed exceeds total', () => {
+      render(<RestTimer {...defaultProps} elapsedMs={200000} />)
+      const fill = screen.getByTestId('rest-timer-progress-fill')
+      expect(fill).toHaveStyle({ width: '100%' })
+    })
+  })
+
+  describe('button interactions', () => {
+    it('fires onSkip when skip button is pressed', () => {
+      const onSkip = vi.fn()
+      render(<RestTimer {...defaultProps} onSkip={onSkip} />)
+      fireEvent.click(screen.getByTestId('rest-timer-skip'))
+      expect(onSkip).toHaveBeenCalledOnce()
+    })
+
+    it('fires onAddTime when +30s button is pressed', () => {
+      const onAddTime = vi.fn()
+      render(<RestTimer {...defaultProps} onAddTime={onAddTime} />)
+      fireEvent.click(screen.getByTestId('rest-timer-add-time'))
+      expect(onAddTime).toHaveBeenCalledOnce()
+    })
+  })
+
+  describe('next set info', () => {
+    it('displays nextSetInfo when provided', () => {
+      render(
+        <RestTimer
+          {...defaultProps}
+          nextSetInfo="Bench Press — Set 3 of 4"
+        />,
+      )
+      expect(screen.getByTestId('rest-timer-next-set')).toHaveTextContent(
+        'Bench Press — Set 3 of 4',
+      )
+    })
+
+    it('does not render next set element when nextSetInfo is not provided', () => {
+      render(<RestTimer {...defaultProps} />)
+      expect(screen.queryByTestId('rest-timer-next-set')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('visibility', () => {
+    it('renders nothing when visible is false', () => {
+      render(<RestTimer {...defaultProps} visible={false} />)
+      expect(screen.queryByTestId('rest-timer')).not.toBeInTheDocument()
+    })
+
+    it('renders when visible is true', () => {
+      render(<RestTimer {...defaultProps} visible />)
+      expect(screen.getByTestId('rest-timer')).toBeInTheDocument()
+    })
+  })
+
+  describe('edge cases', () => {
+    it('clamps remaining to 0 when elapsed exceeds total', () => {
+      render(<RestTimer {...defaultProps} elapsedMs={200000} />)
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('0:00')
+    })
+
+    it('displays full time when elapsed is 0', () => {
+      render(<RestTimer {...defaultProps} totalSeconds={90} elapsedMs={0} />)
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('1:30')
+    })
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(<RestTimer {...defaultProps} />)
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it('has timer role with remaining seconds in label', () => {
+      render(<RestTimer {...defaultProps} totalSeconds={90} elapsedMs={30000} />)
+      expect(
+        screen.getByLabelText('Rest timer, 60 seconds remaining'),
+      ).toBeInTheDocument()
+    })
+
+    it('skip button has accessible label', () => {
+      render(<RestTimer {...defaultProps} />)
+      expect(screen.getByLabelText('Skip rest')).toBeInTheDocument()
+    })
+
+    it('add time button has accessible label', () => {
+      render(<RestTimer {...defaultProps} />)
+      expect(screen.getByLabelText('Add 30 seconds')).toBeInTheDocument()
+    })
+  })
+})

package/src/components/custom/Workout/RestTimer.tsx

@@ -0,0 +1,172 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import React from 'react'
+import { View, Text, Pressable } from 'react-native'
+
+export interface RestTimerProps {
+  totalSeconds: number
+  elapsedMs: number
+  onSkip: () => void
+  onAddTime: () => void
+  nextSetInfo?: string
+  visible: boolean
+}
+
+export function RestTimer({
+  totalSeconds,
+  elapsedMs,
+  onSkip,
+  onAddTime,
+  nextSetInfo,
+  visible,
+}: RestTimerProps) {
+  if (!visible) return null
+
+  const remainingMs = Math.max(0, totalSeconds * 1000 - elapsedMs)
+  const remainingSec = Math.ceil(remainingMs / 1000)
+  const minutes = Math.floor(remainingSec / 60)
+  const seconds = remainingSec % 60
+  const timeDisplay = `${minutes}:${String(seconds).padStart(2, '0')}`
+  const progressPct = Math.min(100, (elapsedMs / (totalSeconds * 1000)) * 100)
+
+  return (
+    <View
+      style={{
+        width: '100%',
+        backgroundColor: '#1C1C1C',
+        borderTopWidth: 1,
+        borderTopColor: '#1F1F1F',
+        paddingVertical: 12,
+        paddingHorizontal: 16,
+      }}
+      accessibilityRole="timer"
+      accessibilityLabel={`Rest timer, ${remainingSec} seconds remaining`}
+      testID="rest-timer"
+    >
+      {/* Top row */}
+      <View
+        style={{
+          flexDirection: 'row',
+          justifyContent: 'space-between',
+          alignItems: 'center',
+          marginBottom: 8,
+        }}
+      >
+        {/* Left side */}
+        <View style={{ flexDirection: 'column' }}>
+          <Text
+            style={{
+              fontSize: 11,
+              fontFamily: 'Inter, sans-serif',
+              fontWeight: '600',
+              textTransform: 'uppercase',
+              letterSpacing: 1,
+              color: '#9CA3AF',
+            }}
+            testID="rest-timer-label"
+          >
+            REST
+          </Text>
+          {nextSetInfo != null && (
+            <Text
+              style={{
+                fontSize: 11,
+                fontFamily: 'Inter, sans-serif',
+                color: '#6B7280',
+                marginTop: 2,
+              }}
+              testID="rest-timer-next-set"
+            >
+              {nextSetInfo}
+            </Text>
+          )}
+        </View>
+
+        {/* Right side - time display */}
+        <Text
+          style={{
+            fontSize: 28,
+            fontFamily: '"Space Grotesk", sans-serif',
+            fontWeight: '700',
+            color: '#F3F4F6',
+            fontVariant: ['tabular-nums'],
+            letterSpacing: -0.5,
+          }}
+          testID="rest-timer-time"
+        >
+          {timeDisplay}
+        </Text>
+      </View>
+
+      {/* Progress bar */}
+      <View
+        style={{
+          height: 3,
+          backgroundColor: '#1F1F1F',
+          borderRadius: 2,
+          marginBottom: 12,
+        }}
+        testID="rest-timer-progress-track"
+      >
+        <View
+          style={{
+            height: '100%',
+            backgroundColor: '#FF7900',
+            borderRadius: 2,
+            width: `${progressPct}%`,
+          }}
+          testID="rest-timer-progress-fill"
+        />
+      </View>
+
+      {/* Actions row */}
+      <View style={{ flexDirection: 'row', gap: 8 }}>
+        <Pressable
+          onPress={onAddTime}
+          style={{
+            backgroundColor: 'rgba(255,255,255,0.06)',
+            paddingVertical: 8,
+            paddingHorizontal: 20,
+            borderRadius: 8,
+          }}
+          accessibilityRole="button"
+          accessibilityLabel="Add 30 seconds"
+          testID="rest-timer-add-time"
+        >
+          <Text
+            style={{
+              fontSize: 11,
+              fontFamily: 'Inter, sans-serif',
+              fontWeight: '600',
+              color: '#9CA3AF',
+            }}
+          >
+            +30s
+          </Text>
+        </Pressable>
+        <Pressable
+          onPress={onSkip}
+          style={{
+            backgroundColor: 'rgba(255,121,0,0.12)',
+            paddingVertical: 8,
+            paddingHorizontal: 20,
+            borderRadius: 8,
+          }}
+          accessibilityRole="button"
+          accessibilityLabel="Skip rest"
+          testID="rest-timer-skip"
+        >
+          <Text
+            style={{
+              fontSize: 11,
+              fontFamily: 'Inter, sans-serif',
+              fontWeight: '600',
+              color: '#FF7900',
+            }}
+          >
+            Skip
+          </Text>
+        </Pressable>
+      </View>
+    </View>
+  )
+}