@1money/component-ui 0.0.23 → 0.0.25

package/.claude/skills/1money-component-dev/references/ComponentPatterns.md

@@ -1,478 +0,0 @@
-# Component Patterns Reference
-
-Annotated templates for all 8 files in a `@1money/components-ui` component directory. Based on the canonical `Button` component.
-
-Replace `{Name}` with PascalCase name (e.g., `Chip`) and `{kebab-name}` with kebab-case (e.g., `chip`).
-
----
-
-## 1. `{Name}.tsx` — Main Component
-
-```tsx
-// ---- Imports ----
-import { memo } from 'react';
-// Import the PrimeReact base component directly from primereact/*
-import { PrimeComponent as PrimeBase } from 'primereact/{component}';
-// Import internal components if needed (e.g., Spinner for loading states)
-import Spinner from '@/components/Spinner';
-// Import classnames utility — default export is pre-configured with 'om-react-ui' prefix
-import { default as classnames, joinCls } from '@/utils/classnames';
-// Import types separately using `import type`
-import type { FC, PropsWithChildren } from 'react';
-import type { {Name}Props } from './interface';
-
-// ---- Constants ----
-// Extract magic strings/numbers as named constants
-const SOME_CONSTANT = '5';
-
-// ---- Component ----
-// Named export with explicit FC typing
-// Use PropsWithChildren<> if the component accepts children, otherwise just {Name}Props
-export const {Name}: FC<PropsWithChildren<{Name}Props>> = props => {
-  // Destructure with defaults
-  // - prefixCls defaults to kebab-case component name
-  // - Variant props get sensible defaults
-  // - ref is destructured but aliased to _ref (forwarded via PrimeReact's own ref handling)
-  // - ...rest captures all remaining PrimeReact props
-  const {
-    children,
-    className = '',
-    prefixCls = '{kebab-name}',
-    color = 'primary',
-    size = 'medium',
-    ref: _ref,
-    ...rest
-  } = props;
-
-  // Create class generator — returns a function: (suffix?, className?) => string
-  const classes = classnames(prefixCls);
-
-  return (
-    <PrimeBase
-      // Spread remaining props FIRST so our overrides take precedence
-      {...rest}
-      // Build root className:
-      // - classes(void 0, ...) generates the root class: `.om-react-ui-{kebab-name}`
-      // - joinCls combines variant classes and external className
-      className={classes(
-        void 0,
-        joinCls(classes(color), classes(size), className),
-      )}
-    >
-      {children}
-    </PrimeBase>
-  );
-};
-
-// Default export MUST be wrapped in memo()
-export default memo({Name});
-```
-
-### `classnames` Utility Explained
-
-```ts
-import { default as classnames, joinCls } from '@/utils/classnames';
-
-// classnames is a curried function:
-// classnames(prefix) returns a class generator
-
-const classes = classnames('button');
-// classes is now: (suffix?, className?) => string
-
-classes(void 0)           // → 'om-react-ui-button'
-classes('primary')        // → 'om-react-ui-button-primary'
-classes('icon-start')     // → 'om-react-ui-button-icon-start'
-classes(void 0, 'extra')  // → 'om-react-ui-button extra'
-classes('sm', 'extra')    // → 'om-react-ui-button-sm extra'
-
-// joinCls concatenates non-falsy class strings
-joinCls(classes('primary'), classes('large'), className)
-// → 'om-react-ui-button-primary om-react-ui-button-large my-custom'
-```
-
----
-
-## 2. `interface.ts` — TypeScript Interfaces
-
-```ts
-import type { ReactNode, RefObject } from 'react';
-// Import PrimeReact component props
-import type { PrimeComponentProps } from 'primereact/{component}';
-
-// Use Omit<> to remove PrimeReact props that conflict with our custom API
-// Common removals: 'label', 'severity', 'size', 'icon', 'className'
-export interface {Name}Props extends Omit<PrimeComponentProps, 'label' | 'severity' | 'size'> {
-  // Ref prop with the correct HTML element type
-  ref?: RefObject<HTMLButtonElement | null>;
-
-  // Class name prefix — allows consumers to customize the BEM namespace
-  prefixCls?: string;
-
-  // Variant props as union types
-  color?: 'primary' | 'secondary' | 'grey' | 'black' | 'white' | 'danger' | 'warning';
-  size?: 'large' | 'medium' | 'small';
-
-  // Slot props for custom content
-  iconStart?: ReactNode;
-  iconEnd?: ReactNode;
-}
-```
-
-### Rules
-
-- Always use `interface` (not `type`) for object structures
-- Name: `{Name}Props`
-- Extend PrimeReact props with `Omit<>` to avoid conflicts
-- Use `ReactNode` for slot props, not `JSX.Element`
-- Use `RefObject<HTMLElement | null>` for ref props
-- Use literal union types for variant props (never `enum`)
-- If variant values are also used in stories, define them as `as const` arrays in the stories file, not here
-
----
-
-## 3. `index.ts` — Barrel Export
-
-```ts
-import {Name} from './{Name}';
-
-export { {Name} } from './{Name}';
-
-export default {Name};
-
-export * from './interface';
-```
-
-### Rules
-
-- Import default + re-export named + re-export default + re-export types
-- This pattern ensures both `import {Name}` and `import { {Name} }` work
-- `export *` from interface re-exports all type definitions
-
----
-
-## 4. `{Name}.stories.tsx` — Storybook Stories
-
-```tsx
-import React from 'react';
-import { fn } from '@storybook/test';
-
-import type { Meta, StoryObj } from '@storybook/react';
-import { {Name} } from './index';
-
-// Import styles for Storybook rendering
-import './style';
-
-// Define variant constants as `as const` for type safety and reuse
-const COLORS = ['primary', 'secondary', 'grey', 'black', 'white', 'danger', 'warning'] as const;
-const SIZES = ['large', 'medium', 'small'] as const;
-
-const meta: Meta<typeof {Name}> = {
-  title: 'Components/{Name}',
-  component: {Name},
-  argTypes: {
-    // Boolean controls
-    disabled: { control: 'boolean' },
-    loading: { control: 'boolean' },
-    // Radio controls for variant props — spread the const array
-    size: { control: 'radio', options: [...SIZES] },
-    color: { control: 'radio', options: [...COLORS] },
-  },
-  args: {
-    // Sensible defaults for the controls panel
-    disabled: false,
-    loading: false,
-    size: 'medium',
-    color: 'primary',
-    onClick: fn(),
-  },
-  tags: ['autodocs'],
-};
-
-export default meta;
-
-type Story = StoryObj<typeof {Name}>;
-
-// ---- AllVariants ----
-// Matrix of ALL size x color combinations for visual QA
-// Tagged '!autodocs' to exclude from auto-generated docs
-// Tagged 'dev' for developer-only visibility
-export const AllVariants: Story = {
-  render: (args) => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 32 }}>
-      {SIZES.map(size => (
-        <div key={size}>
-          <h3 style={{ marginBottom: 12 }}>{size}</h3>
-          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center' }}>
-            {COLORS.map(color => (
-              <{Name} {...args} key={`${size}-${color}`} size={size} color={color}>
-                {color}
-              </{Name}>
-            ))}
-          </div>
-          {/* Disabled row */}
-          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center', marginTop: 8 }}>
-            {COLORS.map(color => (
-              <{Name} {...args} key={`${size}-${color}-disabled`} size={size} color={color} disabled>
-                {color}
-              </{Name}>
-            ))}
-          </div>
-        </div>
-      ))}
-    </div>
-  ),
-  args: {
-    children: undefined,
-  },
-  tags: ['!autodocs', 'dev'],
-};
-
-// ---- Feature-specific stories ----
-export const Sizes: Story = {
-  render: (args) => (
-    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
-      {SIZES.map(size => (
-        <{Name} {...args} key={size} size={size}>
-          {size}
-        </{Name}>
-      ))}
-    </div>
-  ),
-};
-```
-
-### Rules
-
-- Import `fn` from `@storybook/test` for action callbacks (not `action` from `@storybook/addon-actions`)
-- Meta title follows `Components/{Name}` convention
-- Meta must include `tags: ['autodocs']`
-- Variant constants are `as const` arrays spread into options
-- `AllVariants` story always has `tags: ['!autodocs', 'dev']`
-- At minimum: `AllVariants` + one feature story
-
----
-
-## 5. `style/{Name}.scss` — Component Styles
-
-```scss
-@use '@/styles/api' as theme;
-@use '@/styles/recipes/variants' as variants;
-
-$component: '{kebab-name}';
-
-// ── Variant DSL ──
-// 1. Schema: auto-generate from component name + token key list
-// Expands to: (--om-{kebab-name}-text: text, --om-{kebab-name}-bg: bg, ...)
-$component-variant-schema: variants.om-variant-schema(
-  $component, text, bg, hover-bg, disabled-text, disabled-bg
-);
-
-// 2. Variants map: each variant defines all keys from the schema
-$component-variants: (
-  'primary': (
-    text: theme.palette(text, 'on-neutral'),
-    bg: theme.palette(bg, 'brand'),
-    hover-bg: theme.palette(bg, 'brand-hover'),
-    disabled-text: theme.palette(text, 'disabled-white'),
-    disabled-bg: theme.palette(bg, 'disabled-brand'),
-  ),
-  'secondary': (
-    text: theme.palette(text, 'brand'),
-    bg: theme.palette(bg, 'brand-secondary'),
-    hover-bg: theme.palette(bg, 'brand-secondary-hover'),
-    disabled-text: theme.palette(text, 'brand-secondary'),
-    disabled-bg: theme.palette(bg, 'brand-tertiary'),
-  ),
-  // ... more variants
-);
-
-// Root selector — generates: .om-react-ui-{kebab-name}
-.#{theme.$prefix}-#{$component} {
-  // 3. Apply default variant + validate all variants against schema
-  @include variants.om-variant-default($component-variants, 'primary', $component-variant-schema);
-
-  // ── Base styles — consume variant CSS custom properties ──
-  display: inline-flex;
-  gap: theme.spacing(gap, 200);
-  align-items: center;
-  justify-content: center;
-  padding: theme.spacing(component-padding, 400);
-  color: var(--om-{kebab-name}-text);
-  background-color: var(--om-{kebab-name}-bg);
-  border: none;
-  border-radius: theme.shape(300);
-  box-shadow: none;
-  cursor: pointer;
-
-  // Typography — emits font-family, font-size, line-height, etc.
-  @include theme.typography(label, lg);
-
-  // ── Disabled — reads variant custom properties ──
-  &.p-disabled {
-    color: var(--om-{kebab-name}-disabled-text);
-    background-color: var(--om-{kebab-name}-disabled-bg);
-    cursor: not-allowed;
-  }
-
-  // ── Hover — reads variant custom property ──
-  &:hover:not(.p-disabled) {
-    background-color: var(--om-{kebab-name}-hover-bg);
-  }
-
-  // ── Size variants ──
-  // Use &-{size} for variant classes
-  &-medium {
-    padding: theme.spacing(component-padding, 300);
-    border-radius: theme.shape(300);
-    @include theme.typography(label, md);
-  }
-
-  &-small {
-    padding: theme.spacing(component-padding, 200);
-    border-radius: theme.shape(200);
-    @include theme.typography(label, sm);
-  }
-
-  // ── Slot styles ──
-  &-icon-start,
-  &-icon-end {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-  }
-
-  // ── Color variants (Variant DSL) ──
-  // Generate all modifier classes, skipping the default 'primary' variant
-  @include variants.om-variant-classes($component-variants, $component-variant-schema, $default: 'primary');
-
-  // ── Responsive ──
-  // @include theme.down(md) { ... }
-}
-```
-
-### SCSS Rules
-
-- First lines: `@use '@/styles/api' as theme;` and `@use '@/styles/recipes/variants' as variants;` (if using variants)
-- `$component` is always kebab-case
-- Root: `.#{theme.$prefix}-#{$component}` (do NOT hardcode `om-react-ui`)
-- **Color variants**: Use the Variant DSL (`variants.om-variant-schema` + `variants.om-variant-default` + `variants.om-variant-classes`) with CSS custom properties instead of manual `&-{variant}` blocks for each color
-- **Size variants**: Use `&-{size}` nesting (these remain manual since they change structural properties, not just colors)
-- Disabled: target `.p-disabled` class (PrimeReact adds this)
-- Hover: `&:hover:not(.p-disabled)` to skip disabled elements
-- All values use token functions — no raw hex, px (for tokens), or font-family
-- Exception: `!important` overrides on third-party (PrimeReact) styles are acceptable when necessary
-- Variant names must be quoted strings (e.g., `'white'`, `'black'`) to avoid Sass color literal issues
-
----
-
-## 6. `style/index.ts` — Style Entry Point
-
-```ts
-import './{Name}.scss';
-```
-
-Single line. This file is imported in stories and by the build system.
-
----
-
-## 7. `__test__/index.test.tsx` — Snapshot Test
-
-```tsx
-import 'jsdom-global/register';
-import * as React from 'react';
-import { render, screen } from '@testing-library/react';
-import '@testing-library/jest-dom';
-import { {Name} } from '../index';
-
-// Suppress known console errors from PrimeReact/JSDOM incompatibility
-const originalConsoleError = console.error;
-console.error = (message, ...optionalParams) => {
-  const errorMessage = typeof message === 'string' ? message : String(message);
-  if (
-    errorMessage.includes('Could not parse CSS stylesheet') ||
-    errorMessage.includes('findDOMNode is deprecated and will be removed')
-  ) {
-    return;
-  }
-  originalConsoleError(message, ...optionalParams);
-};
-
-// Mock lottie-web if any component in the dependency chain uses Loading/Spinner
-jest.mock('lottie-web', () => ({
-  loadAnimation: jest.fn(() => ({
-    play: jest.fn(),
-    pause: jest.fn(),
-    destroy: jest.fn(),
-  })),
-}));
-
-describe('{Name}', () => {
-  it('renders correctly', () => {
-    const wrapper = render(
-      <{Name}>Test</{Name}>
-    );
-    expect(wrapper).toMatchSnapshot();
-  });
-});
-```
-
-### Rules
-
-- Always import `jsdom-global/register` first
-- Always suppress the two known console errors
-- Always mock `lottie-web` (safe even if not needed)
-- At minimum: one `renders correctly` snapshot test
-- Optionally add tests for variants, events, disabled state
-
----
-
-## 8. `README.md` — Component Documentation
-
-```md
-# {Name}
-
-Brief description of what the component does and when to use it.
-
-## Import
-
-\```tsx
-import { {Name} } from '@1money/components-ui';
-// or
-import { {Name} } from '@1money/components-ui/{Name}';
-\```
-
-## Usage
-
-\```tsx
-<{Name} color="primary" size="medium">
-  Click me
-</{Name}>
-\```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `color` | `'primary' \| 'secondary' \| ...` | `'primary'` | Visual color variant |
-| `size` | `'large' \| 'medium' \| 'small'` | `'medium'` | Size variant |
-| `disabled` | `boolean` | `false` | Disables the component |
-| `loading` | `boolean` | `false` | Shows loading spinner |
-| `prefixCls` | `string` | `'{kebab-name}'` | CSS class prefix |
-| `className` | `string` | `''` | Additional CSS classes |
-```
-
----
-
-## Library Registration (`src/index.ts`)
-
-After creating all component files, update the barrel export:
-
-```ts
-// Add re-export for the component (alphabetical order)
-export { {Name} } from './components/{Name}';
-
-// Add type re-export
-export type { {Name}Props } from './components/{Name}';
-```
-
-Note: The current `src/index.ts` uses only re-export statements — there is no import block and no default export object.

package/.claude/skills/1money-component-dev/references/FigmaExtractionChecklist.md

@@ -1,144 +0,0 @@
-# Figma Extraction Checklist
-
-Checklist for extracting design data from Figma when building new `@1money/components-ui` library components. Adapted for library-internal development where Figma tokens must map to the internal style system (not consumer-facing Foundation tokens).
-
----
-
-## Pre-flight
-
-- [ ] Figma URL is a design or node link (not a prototype or FigJam board)
-- [ ] Node ID is known, or top-level frames have been listed and the user has selected one
-- [ ] Component name confirmed (PascalCase)
-
-## Extraction Steps
-
-### Step 1 — Get Design Context
-
-```
-mcp__figma__get_design_context(nodeId, fileKey)
-```
-
-- [ ] Call returned valid data (code + screenshot)
-- [ ] If MCP returned empty or errors, retried once before reporting failure
-- [ ] Noted the reference code structure (React+Tailwind hints) for mapping guidance
-
-### Step 2 — Get Screenshot
-
-```
-mcp__figma__get_screenshot(nodeId, fileKey)
-```
-
-- [ ] Called for any frame where layout, spacing, or alignment is ambiguous
-- [ ] Screenshot reviewed for: padding, gap, border-radius, shadow, alignment
-- [ ] Visual hierarchy and nesting structure understood
-
-### Step 3 — Get Variable Definitions
-
-```
-mcp__figma__get_variable_defs(nodeId, fileKey)
-```
-
-- [ ] Design tokens retrieved (colors, spacing, radii, typography)
-- [ ] Figma variable names noted for mapping to internal style system
-
-### Step 4 — Get Metadata (if no Node ID)
-
-```
-mcp__figma__get_metadata(nodeId, fileKey)
-```
-
-- [ ] Top-level frames listed
-- [ ] User selected the target frame
-- [ ] Re-run Steps 1-3 with the selected Node ID
-
-## Token Mapping Phase
-
-Map every Figma design value to the internal style system. Consult `StyleSystemAPI.md` and `SemanticColors.md`.
-
-### Colors
-
-- [ ] Background fills mapped to `theme.palette(bg, ...)` keys
-- [ ] Text colors mapped to `theme.palette(text, ...)` keys
-- [ ] Icon colors mapped to `theme.palette(icon, ...)` keys
-- [ ] Border colors mapped to `theme.palette(border, ...)` keys
-- [ ] No raw hex values remain unmapped
-
-### Spacing
-
-- [ ] Padding values mapped to `theme.spacing(component-padding, key)` or `theme.spacing(scale, key)`
-- [ ] Gap values mapped to `theme.spacing(gap, key)`
-- [ ] Margin values mapped to `theme.spacing(scale, key)`
-- [ ] No raw pixel values for spacing remain unmapped
-
-### Typography
-
-- [ ] Font family, size, weight, line-height identified per text layer
-- [ ] Mapped to `@include theme.typography(category, size)` — find the closest match from:
-  - `display`: xl/lg/md/sm/xs (Aeonik)
-  - `headline`: lg/md/sm/xs (Aeonik)
-  - `title`: lg/md/sm (Inter, strong=700)
-  - `body`: lg/md/sm (Inter, strong=500)
-  - `link`: md/sm (Inter)
-  - `label`: xl/lg/md/sm/xs (Inter, strong=600-700)
-- [ ] Any `$strong: true` variants identified
-
-### Visual Properties
-
-- [ ] Border-radius mapped to `theme.shape(key)` keys (0/100/200/300/400/600/full)
-- [ ] Box-shadow mapped to `theme.shadows(key)` keys (0/100/200)
-- [ ] Opacity mapped to `theme.opacity(key)` keys
-- [ ] Component heights mapped to `theme.sizing(component-height, key)` keys (xs/sm/md/lg/xl/2xl/3xl)
-
-## Variant Identification
-
-- [ ] All visual variants listed (e.g., color variants: primary, secondary, danger, etc.)
-- [ ] All size variants listed (e.g., large, medium, small)
-- [ ] Variant naming aligned with existing library conventions (check Button for reference)
-- [ ] Each variant's token mapping documented
-
-## Slot Identification
-
-- [ ] Content slots identified (e.g., `children`, `label`, `description`)
-- [ ] Icon slots identified (e.g., `iconStart`, `iconEnd`, `icon`)
-- [ ] Custom render slots identified (e.g., `header`, `footer`, `prefix`, `suffix`)
-- [ ] Each slot typed as `ReactNode` in the interface
-
-## State Coverage Assessment
-
-### Required States (implement even if not in Figma)
-
-- [ ] **Default**: Normal resting state
-- [ ] **Hover**: `:hover:not(.p-disabled)` interaction
-- [ ] **Focus**: `:focus-visible` interaction (if applicable)
-- [ ] **Active**: `:active` interaction (if applicable)
-- [ ] **Disabled**: `.p-disabled` class with `cursor: not-allowed` and muted colors
-- [ ] **Loading**: Spinner integration (if applicable)
-
-### Conditional States (implement if component type requires)
-
-- [ ] **Error/Danger**: Validation error state with danger colors
-- [ ] **Warning**: Warning state with warning colors
-- [ ] **Success/Positive**: Success state with positive colors
-- [ ] **Selected/Active**: Toggle or selection state
-- [ ] **Empty**: Empty/placeholder state
-
-## Unmapped Items
-
-- [ ] All Figma nodes that could not be mapped are listed explicitly
-- [ ] Blocking ambiguities escalated to the user before implementation
-- [ ] Asset placeholders documented for images/icons without a component match
-
-## Summary Table Template
-
-Use this table format to document the mapping:
-
-```markdown
-| Figma Element | Figma Value | Style System Function | Key |
-|---------------|-------------|----------------------|-----|
-| Background | #1D4ED8 | `theme.palette(bg, ...)` | `brand` |
-| Text | #FFFFFF | `theme.palette(text, ...)` | `on-neutral` |
-| Padding | 16px | `theme.spacing(component-padding, ...)` | `400` |
-| Border radius | 12px | `theme.shape(...)` | `300` |
-| Height | 52px | `theme.sizing(component-height, ...)` | `2xl` |
-| Typography | Inter 14/500 | `theme.typography(...)` | `label, md` |
-```