@oztix/roadie-components 1.2.0 → 2.0.0

package/src/components/SpotIllustration/README.md

@@ -1,280 +0,0 @@
-# SpotIllustration System
-
-A fully automated system for creating themed SVG illustrations that adapt to the design system's color palette.
-
-## Quick Start
-
-### Adding a New Illustration
-
-1. **Export from Figma**: Save your SVG to `svgs/your-name.svg`
-2. **Run the script**: `pnpm build:spotillustration`
-3. **Done!** Your component is ready to use
-
-The script automatically generates:
-
-- Optimized JSON data file
-- React TypeScript component
-- Updated exports in `index.tsx`
-
-### Development Workflow
-
-During development, the script runs in watch mode:
-
-```bash
-pnpm dev
-```
-
-Any SVG files added or modified in the `svgs/` directory will automatically trigger:
-
-1. SVG optimization
-2. Component generation
-3. Export updates
-
-No manual intervention required.
-
-## Design Requirements
-
-### Frame Size
-
-Use a **48x48** frame in Figma (or maintain the same aspect ratio).
-
-### Color Palette
-
-Use these exact hex colors in your Figma design. The script categorizes paths by color:
-
-| Color       | Hex       | Layer       | Purpose                                  |
-| ----------- | --------- | ----------- | ---------------------------------------- |
-| White       | `#ffffff` | `outline`   | White stroke outline (hidden by default) |
-| Purple tint | `#E1D1FB` | `face`      | Main fills, primary shapes               |
-| Orange tint | `#FFC3A8` | `detail`    | Accent details, highlights               |
-| Blue        | `#0091EB` | `shadow`    | Shadow layers, depth                     |
-| Light blue  | `#C2DFFB` | `highlight` | Light highlights, shine                  |
-| Near black  | `#1A1F2B` | `stroke`    | Outlines, strokes                        |
-
-### Layer Ordering
-
-SVG renders paths in order, so arrange layers intentionally:
-
-1. Outline (if needed)
-2. Shadows (background)
-3. Face/main shapes
-4. Details
-5. Highlights (foreground)
-6. Strokes (top layer)
-
-The script preserves your exact path order from Figma.
-
-## How the Script Works
-
-### Build Script: `svg-to-spot-illustration.cjs`
-
-Location: `packages/components/scripts/svg-to-spot-illustration.cjs`
-
-#### Process Flow
-
-1. **SVG Optimization** (SVGO)
-   - Removes unnecessary attributes
-   - Cleans up paths
-   - Removes dimensions (preserves viewBox)
-   - Skip with `--no-optimize` flag if needed
-
-2. **Path Categorization**
-   - Reads semantic illustration tokens from `@oztix/roadie-core`
-   - Matches each path's fill/stroke color to closest token color
-   - Assigns semantic layer name (face, detail, shadow, etc.)
-   - Preserves exact path order from source SVG
-
-3. **JSON Generation**
-   - Creates optimized JSON in `json/` directory
-   - Structure:
-     ```json
-     {
-       "$comment": "Generated file - do not edit directly",
-       "viewBox": "0 0 48 48",
-       "paths": [{ "d": "M26.179...", "layer": "face" }]
-     }
-     ```
-
-4. **Component Generation**
-   - Converts `kebab-case.svg` → `PascalCase.tsx`
-   - Uses `createSpotIllustration` factory
-   - Adds TypeScript types
-   - Example output:
-
-     ```tsx
-     // Generated file - do not edit directly
-     import { createSpotIllustration } from './createSpotIllustration'
-     import heartData from './json/heart.json'
-
-     export const Heart = createSpotIllustration('Heart', heartData)
-     export type HeartProps = React.ComponentPropsWithRef<typeof Heart>
-     ```
-
-5. **Export Updates**
-   - Scans directory for all component files
-   - Updates `index.tsx` with alphabetically sorted exports
-   - Preserves base component exports (SpotIllustration, createSpotIllustration)
-
-### Usage Modes
-
-**Build all SVGs:**
-
-```bash
-pnpm build:spotillustration
-```
-
-**Build specific SVG:**
-
-```bash
-pnpm build:spotillustration src/components/SpotIllustration/svgs/heart.svg
-```
-
-**Watch mode (auto-rebuild on changes):**
-
-```bash
-pnpm build:spotillustration --watch
-```
-
-**Skip optimization:**
-
-```bash
-pnpm build:spotillustration --no-optimize
-```
-
-### Color Matching Algorithm
-
-The script uses Euclidean distance in RGB color space to match fills/strokes to semantic tokens:
-
-1. Normalize colors (expand short hex, lowercase)
-2. Calculate RGB distance to each token color
-3. Assign to closest matching layer
-4. Default to 'face' if distance > 100 (no close match)
-5. Strokes (paths with stroke but no fill) → 'stroke' layer
-
-## Component Architecture
-
-### Base Component: `SpotIllustration`
-
-Accepts illustration data and renders themed SVG:
-
-```tsx
-<SpotIllustration
-  illustration={illustrationData}
-  boxSize='600'
-  outline={false}
-/>
-```
-
-### Factory: `createSpotIllustration`
-
-Creates pre-configured components from JSON data:
-
-```tsx
-export const Heart = createSpotIllustration('Heart', heartData)
-```
-
-This returns a component with:
-
-- Pre-loaded illustration data
-- Forward ref support
-- All SpotIllustration props except `illustration`
-- TypeScript types
-
-### Styling System
-
-Components use PandaCSS with semantic tokens:
-
-- `colorPalette` system for theming
-- Data attributes for layer targeting: `data-part="face"`, `data-part="shadow"`, etc.
-- `outline` variant to show/hide white outline
-- All PandaCSS style props supported
-
-## File Structure
-
-```
-SpotIllustration/
-├── README.md                          # This file
-├── SpotIllustration.tsx              # Base component
-├── createSpotIllustration.tsx        # Factory function
-├── index.tsx                         # Exports (auto-updated)
-├── svgs/                             # Source SVG files
-│   ├── heart.svg
-│   ├── high-five.svg
-│   └── note-music.svg
-├── json/                             # Generated JSON (do not edit)
-│   ├── heart.json
-│   ├── high-five.json
-│   └── note-music.json
-├── Heart.tsx                         # Generated component (do not edit)
-├── HighFive.tsx                      # Generated component (do not edit)
-└── NoteMusic.tsx                     # Generated component (do not edit)
-```
-
-## Troubleshooting
-
-### Colors Not Matching Correctly
-
-- Verify you're using exact hex colors from the table above
-- Check that fills/strokes are applied directly to paths (not groups)
-- Try `--no-optimize` if SVGO is changing colors
-
-### Wrong Layer Order
-
-- Check layer order in Figma (bottom to top)
-- SVG renders paths sequentially
-- Reorder in Figma and re-export
-
-### Component Not Exported
-
-- Check that `index.tsx` was updated (should happen automatically)
-- Run `pnpm build:spotillustration` again
-- Verify component file was created in SpotIllustration directory
-
-### Watch Mode Not Detecting Changes
-
-- Ensure file is saved in `svgs/` directory with `.svg` extension
-- Check terminal for error messages
-- Restart watch mode if needed
-
-## Advanced Usage
-
-### Custom Illustrations at Runtime
-
-Use the base component with custom JSON data:
-
-```tsx
-import { SpotIllustration } from '@oztix/roadie-components'
-
-const customData = {
-  viewBox: "0 0 48 48",
-  paths: [
-    { d: "M10,10 L30,30", layer: "stroke" }
-  ]
-}
-
-<SpotIllustration illustration={customData} />
-```
-
-### Importing from Dedicated Export Path
-
-```tsx
-import { Heart, NoteMusic } from '@oztix/roadie-components/spot-illustrations'
-```
-
-This import path only includes SpotIllustration components, useful for tree-shaking.
-
-## Contributing
-
-When adding new illustrations:
-
-1. Follow the design requirements above
-2. Use descriptive, kebab-case filenames (e.g., `music-note.svg`, not `icon-1.svg`)
-3. Test in both light and dark themes
-4. Verify outline variant works if applicable
-5. Run the build script and commit all generated files
-
-## Related Files
-
-- Script: `packages/components/scripts/svg-to-spot-illustration.cjs`
-- Tokens: `packages/core/src/tokens/semantic-tokens.json`
-- Documentation: `docs/src/app/components/spot-illustration/page.mdx`

package/src/components/SpotIllustration/SpotIllustration.test.tsx

@@ -1,179 +0,0 @@
-import { render } from '@testing-library/react'
-import { describe, expect, it } from 'vitest'
-
-import { Hand } from './Hand'
-import { Heart } from './Heart'
-import { Ticket } from './Ticket'
-
-describe('SpotIllustration', () => {
-  describe('rendering', () => {
-    it('should render an illustration', () => {
-      const { container } = render(<Heart />)
-      const svg = container.querySelector('svg')
-      expect(svg).toBeInTheDocument()
-    })
-
-    it('should render with default viewBox', () => {
-      const { container } = render(<Heart />)
-      const svg = container.querySelector('svg')
-      expect(svg).toHaveAttribute('viewBox', '0 0 48 48')
-    })
-
-    it('should render all path layers', () => {
-      const { container } = render(<Heart />)
-      const paths = container.querySelectorAll('path')
-      expect(paths.length).toBeGreaterThan(0)
-    })
-  })
-
-  describe('boxSize prop', () => {
-    it('should apply default boxSize of 600', () => {
-      const { container } = render(<Heart />)
-      const svg = container.querySelector('svg')
-      // Check for class name base (PandaCSS uses different format)
-      expect(svg?.classList.length).toBeGreaterThan(0)
-    })
-
-    it('should apply custom boxSize', () => {
-      const { container } = render(<Heart boxSize='800' />)
-      const svg = container.querySelector('svg')
-      expect(svg?.classList.length).toBeGreaterThan(0)
-    })
-
-    it('should support numeric boxSize values', () => {
-      const { container } = render(<Heart boxSize='1200' />)
-      const svg = container.querySelector('svg')
-      expect(svg?.classList.length).toBeGreaterThan(0)
-    })
-  })
-
-  describe('outline prop', () => {
-    it('should render outline layer by default (outline=false)', () => {
-      const { container } = render(<Ticket />)
-      const paths = container.querySelectorAll('path')
-      const outlinePaths = Array.from(paths).filter(
-        (path) => (path as Element).getAttribute('data-part') === 'outline'
-      )
-      expect(outlinePaths.length).toBeGreaterThan(0)
-    })
-
-    it('should hide outline when outline=false (default)', () => {
-      const { container } = render(<Ticket outline={false} />)
-      const svg = container.querySelector('svg')
-      // The outline should have opacity: 0 via CSS
-      expect(svg).toBeInTheDocument()
-    })
-
-    it('should show outline when outline=true', () => {
-      const { container } = render(<Ticket outline={true} />)
-      const svg = container.querySelector('svg')
-      // The outline should be visible via CSS
-      expect(svg).toBeInTheDocument()
-    })
-  })
-
-  describe('className prop', () => {
-    it('should accept custom className', () => {
-      const { container } = render(<Heart className='custom-class' />)
-      const svg = container.querySelector('svg')
-      // PandaCSS merges classes differently - just check element exists
-      expect(svg).toBeInTheDocument()
-      expect(svg?.classList.length).toBeGreaterThan(0)
-    })
-
-    it('should merge custom className with default classes', () => {
-      const { container } = render(
-        <Heart className='custom-class' boxSize='400' />
-      )
-      const svg = container.querySelector('svg')
-      expect(svg).toBeInTheDocument()
-      expect(svg?.classList.length).toBeGreaterThan(0)
-    })
-  })
-
-  describe('ref forwarding', () => {
-    it('should forward ref to svg element', () => {
-      let svgRef: SVGSVGElement | null = null
-      render(
-        <Heart
-          ref={(el) => {
-            svgRef = el
-          }}
-        />
-      )
-      expect(svgRef).toBeInstanceOf(SVGSVGElement)
-    })
-
-    it('should allow accessing svg properties via ref', () => {
-      let svgRef: SVGSVGElement | null = null
-      render(
-        <Heart
-          ref={(el) => {
-            svgRef = el
-          }}
-        />
-      )
-      expect(svgRef).not.toBeNull()
-      expect(svgRef!.getAttribute('viewBox')).toBeDefined()
-    })
-  })
-
-  describe('different illustrations', () => {
-    it('should render Heart illustration', () => {
-      const { container } = render(<Heart />)
-      const svg = container.querySelector('svg')
-      expect(svg).toBeInTheDocument()
-    })
-
-    it('should render Ticket illustration', () => {
-      const { container } = render(<Ticket />)
-      const svg = container.querySelector('svg')
-      expect(svg).toBeInTheDocument()
-    })
-
-    it('should render Hand illustration', () => {
-      const { container } = render(<Hand />)
-      const svg = container.querySelector('svg')
-      expect(svg).toBeInTheDocument()
-    })
-
-    it('should render different number of paths for different illustrations', () => {
-      const { container: heartContainer } = render(<Heart />)
-      const { container: handContainer } = render(<Hand />)
-
-      const heartPaths = heartContainer.querySelectorAll('path').length
-      const handPaths = handContainer.querySelectorAll('path').length
-
-      // Heart and Hand have different numbers of paths
-      expect(heartPaths).not.toBe(handPaths)
-    })
-  })
-
-  describe('layer colors', () => {
-    it('should use semantic token colors via data-part attributes', () => {
-      const { container } = render(<Heart />)
-      const paths = container.querySelectorAll('path')
-
-      // Check that paths have data-part attributes for styling
-      const dataParts = Array.from(paths)
-        .map((path) => (path as Element).getAttribute('data-part'))
-        .filter(Boolean)
-
-      expect(dataParts.length).toBeGreaterThan(0)
-    })
-  })
-
-  describe('accessibility', () => {
-    it('should be decorative by default (no role)', () => {
-      const { container } = render(<Heart />)
-      const svg = container.querySelector('svg')
-      expect(svg).not.toHaveAttribute('role')
-    })
-
-    it('should accept aria attributes', () => {
-      const { container } = render(<Heart aria-label='Heart icon' />)
-      const svg = container.querySelector('svg')
-      expect(svg).toHaveAttribute('aria-label', 'Heart icon')
-    })
-  })
-})

package/src/components/SpotIllustration/SpotIllustration.tsx

@@ -1,96 +0,0 @@
-import { forwardRef } from 'react'
-
-import { styled } from '@oztix/roadie-core/jsx'
-import type { HTMLStyledProps } from '@oztix/roadie-core/jsx'
-
-interface PathData {
-  d: string
-  layer: 'outline' | 'face' | 'detail' | 'shadow' | 'highlight' | 'stroke'
-}
-
-interface IllustrationData {
-  viewBox: string
-  paths: PathData[]
-}
-
-const StyledSvg = styled('svg', {
-  base: {
-    boxSize: '600',
-    fill: 'none',
-    '& [data-part="outline"]': {
-      fill: 'illustrations.outline'
-    },
-    '& [data-part="face"]': {
-      fill: 'illustrations.face'
-    },
-    '& [data-part="detail"]': {
-      fill: 'illustrations.detail'
-    },
-    '& [data-part="shadow"]': {
-      fill: 'illustrations.shadow'
-    },
-    '& [data-part="highlight"]': {
-      fill: 'illustrations.highlight'
-    },
-    '& [data-part="stroke"]': {
-      stroke: 'illustrations.stroke',
-      strokeWidth: '0.5',
-      strokeLinecap: 'round',
-      strokeLinejoin: 'round',
-      fill: 'none'
-    }
-  },
-  variants: {
-    outline: {
-      true: {
-        '& [data-part="outline"]': {
-          opacity: 1
-        }
-      },
-      false: {
-        '& [data-part="outline"]': {
-          opacity: 0
-        }
-      }
-    }
-  },
-  defaultVariants: {
-    outline: false
-  }
-})
-
-export interface SpotIllustrationProps
-  extends Omit<HTMLStyledProps<'svg'>, 'outline'> {
-  /**
-   * Illustration definition containing viewBox and paths
-   */
-  illustration: IllustrationData
-  /**
-   * Whether to show the outline layer
-   * @default false
-   */
-  outline?: boolean
-}
-
-export const SpotIllustration = forwardRef<
-  SVGSVGElement,
-  SpotIllustrationProps
->(({ illustration, ...props }, ref) => {
-  // Fallback to default viewBox if not provided
-  const { viewBox = '0 0 48 48', paths } = illustration
-
-  return (
-    <StyledSvg
-      ref={ref}
-      xmlns='http://www.w3.org/2000/svg'
-      viewBox={viewBox}
-      {...props}
-    >
-      {paths.map((path: PathData, index: number) => (
-        <path key={index} d={path.d} data-part={path.layer} />
-      ))}
-    </StyledSvg>
-  )
-})
-
-SpotIllustration.displayName = 'SpotIllustration'

package/src/components/SpotIllustration/Ticket.tsx

@@ -1,6 +0,0 @@
-// Generated file - do not edit directly
-import { createSpotIllustration } from './createSpotIllustration'
-import ticketData from './json/ticket.json'
-
-export const Ticket = createSpotIllustration('Ticket', ticketData)
-export type TicketProps = React.ComponentPropsWithRef<typeof Ticket>

package/src/components/SpotIllustration/WineGlass.tsx

@@ -1,6 +0,0 @@
-// Generated file - do not edit directly
-import { createSpotIllustration } from './createSpotIllustration'
-import wineglassData from './json/wine-glass.json'
-
-export const WineGlass = createSpotIllustration('WineGlass', wineglassData)
-export type WineGlassProps = React.ComponentPropsWithRef<typeof WineGlass>

package/src/components/SpotIllustration/createSpotIllustration.tsx

@@ -1,46 +0,0 @@
-import { forwardRef } from 'react'
-
-import {
-  SpotIllustration,
-  type SpotIllustrationProps
-} from './SpotIllustration'
-
-type IllustrationJson = SpotIllustrationProps['illustration']
-
-export type SpotIllustrationComponentProps = Omit<
-  SpotIllustrationProps,
-  'illustration'
->
-
-/**
- * Factory function to create a SpotIllustration component from JSON data
- *
- * @param name - Display name for the component
- * @param data - JSON data imported from the json folder
- * @returns A React component that renders the spot illustration
- *
- * @example
- * ```tsx
- * import { createSpotIllustration } from './createSpotIllustration'
- * import noteMusicData from './json/note-music.json'
- *
- * export const NoteMusic = createSpotIllustration('NoteMusic', noteMusicData)
- * ```
- */
-export function createSpotIllustration(name: string, data: unknown) {
-  const Component = forwardRef<SVGSVGElement, SpotIllustrationComponentProps>(
-    (props, ref) => {
-      return (
-        <SpotIllustration
-          ref={ref}
-          illustration={data as IllustrationJson}
-          {...props}
-        />
-      )
-    }
-  )
-
-  Component.displayName = name
-
-  return Component
-}

package/src/components/SpotIllustration/index.tsx

@@ -1,42 +0,0 @@
-export { SpotIllustration } from './SpotIllustration'
-export type { SpotIllustrationProps } from './SpotIllustration'
-
-export { createSpotIllustration } from './createSpotIllustration'
-export type { SpotIllustrationComponentProps } from './createSpotIllustration'
-
-// Generated exports - do not edit manually
-export { ArrowUpRight } from './ArrowUpRight'
-export type { ArrowUpRightProps } from './ArrowUpRight'
-
-export { CowboyHat } from './CowboyHat'
-export type { CowboyHatProps } from './CowboyHat'
-
-export { Cursor } from './Cursor'
-export type { CursorProps } from './Cursor'
-
-export { FlowerSpiral } from './FlowerSpiral'
-export type { FlowerSpiralProps } from './FlowerSpiral'
-
-export { Football } from './Football'
-export type { FootballProps } from './Football'
-
-export { Hand } from './Hand'
-export type { HandProps } from './Hand'
-
-export { Heart } from './Heart'
-export type { HeartProps } from './Heart'
-
-export { HighFive } from './HighFive'
-export type { HighFiveProps } from './HighFive'
-
-export { MapPin } from './MapPin'
-export type { MapPinProps } from './MapPin'
-
-export { NoteMusic } from './NoteMusic'
-export type { NoteMusicProps } from './NoteMusic'
-
-export { Ticket } from './Ticket'
-export type { TicketProps } from './Ticket'
-
-export { WineGlass } from './WineGlass'
-export type { WineGlassProps } from './WineGlass'

package/src/components/SpotIllustration/json/arrow-up-right.json

@@ -1,34 +0,0 @@
-{
-  "$comment": "Generated file - do not edit directly",
-  "viewBox": "0 0 48 48",
-  "paths": [
-    {
-      "d": "m40.531.849 6.605 4.69c.574.396.906 1.083.857 1.782L46.694 25.9c-.117 1.677-2.22 2.462-3.409 1.275l-3.032-3.031-8.035 8.033-.413 4.054a2 2 0 0 1-.575 1.211l-8.488 8.485a2.026 2.026 0 0 1-2.695.2l-6.541-4.64a2 2 0 0 1-.703-.897l-2.287-5.8-2.626-1.035a2 2 0 0 1-.424-.23l-6.624-4.7c-.995-.707-1.12-2.183-.257-3.046l8.657-8.646a2 2 0 0 1 1.084-.46l4.051-.413 8.527-8.529-3.267-2.319a2.001 2.001 0 0 1 1.018-3.626l18.578-1.3c.466-.014.913.09 1.298.364",
-      "layer": "outline"
-    },
-    {
-      "d": "m17.153 23.364-8.53 8.53-6.624-4.702 8.53-8.53 3.312 2.351z",
-      "layer": "detail"
-    },
-    {
-      "d": "m27.417 8.481 4.446 4.446-9.95 9.949.001.001h-.002l-4.759.487-6.624-4.702 4.76-.486L25.993 7.47z",
-      "layer": "detail"
-    },
-    {
-      "d": "M45.998 7.183 27.42 8.479 20.795 3.78l18.578-1.3z",
-      "layer": "detail"
-    },
-    {
-      "d": "M45.998 7.182 27.419 8.48l4.446 4.447-9.95 9.95-4.762.487-8.53 8.53 9.082 3.58 3.58 9.083 8.53-8.53.487-4.762 9.951-9.95 4.446 4.445z",
-      "layer": "face"
-    },
-    {
-      "d": "m12.058 33.247 5.65 2.227 3.58 9.082-6.625-4.701z",
-      "layer": "shadow"
-    },
-    {
-      "d": "M45.998 7.182 27.419 8.48m18.579-1.298L44.699 25.76l-4.446-4.445-9.951 9.95-.487 4.762-8.53 8.53-3.58-9.083-9.082-3.58 8.53-8.53M45.998 7.182 39.373 2.48l-18.578 1.3 6.624 4.7m0 0 4.446 4.447-9.95 9.95m0 0-4.762.487m4.762-.487-6.626-4.701-4.76.487 6.624 4.701m-5.095 9.883 5.65 2.227 3.58 9.082-6.625-4.701zm-3.434-1.351 8.53-8.53-6.624-4.702L2 27.194zm23.239-18.969-4.446-4.446-1.424-1.01-10.705 10.706 6.624 4.701 9.951-9.95z",
-      "layer": "stroke"
-    }
-  ]
-}