solid-tom-ui 1.0.8 → 1.0.11

package/dist/skill/swap.skill.md.txt

@@ -0,0 +1,139 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Swap } from 'solid-tom-ui';`
+- **Export**: `Swap` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Toggle component that alternates between two visual states (`item1` / `item2`) via a hidden checkbox; supports `rotate` and `flip` animation effects
+
+## TYPE SIGNATURE
+
+```typescript
+import { Swap, SolidComponent } from 'solid-tom-ui';
+
+<Swap
+  item1={SolidComponent}              // REQUIRED: shown when checkbox is CHECKED (swap-on)
+  item2={SolidComponent}              // REQUIRED: shown when checkbox is UNCHECKED (swap-off)
+  effect?="rotate" | "flip"           // animation effect; default: "rotate"
+  onChange?={(value: boolean) => void} // called when checkbox changes; value = checked state
+/>
+```
+
+### `SolidComponent` type
+```typescript
+type SolidComponent = Component<any> | (() => JSX.Element) | JSX.Element;
+```
+
+## STATE MODEL
+| Checkbox state | Visible item | CSS class on label |
+|---|---|---|
+| `checked = true` | `item1` | `swap-on` is active |
+| `checked = false` | `item2` | `swap-off` is active |
+
+- `item1` = the "ON" state content (e.g., close icon, "X")
+- `item2` = the "OFF" state content (e.g., hamburger menu, sun icon)
+- The component is **uncontrolled** — no external `checked` prop; checkbox state is managed by DaisyUI's CSS.
+
+## USAGE PATTERNS
+
+### Icon toggle with rotate effect (hamburger ↔ close)
+```tsx
+import { Swap, DynamicIcon } from 'solid-tom-ui';
+
+<Swap
+  item1={<DynamicIcon name="circle-x" size={40} />}
+  item2={<DynamicIcon name="menu" size={40} />}
+  effect="rotate"
+  onChange={value => console.log('isOpen:', value)}
+/>
+```
+
+### Flip effect (arrow up ↔ arrow down)
+```tsx
+<Swap
+  item1={<DynamicIcon name="arrow-up-to-line" size={40} stroke="black" />}
+  item2={<DynamicIcon name="arrow-down-to-line" size={40} stroke="black" />}
+  effect="flip"
+/>
+```
+
+### With Button content (any SolidJS component works)
+```tsx
+import { Button } from 'solid-tom-ui';
+
+<Swap
+  item1={<Button variant="solid" color="error">Cancel</Button>}
+  item2={<Button variant="solid" color="primary">Open</Button>}
+  onChange={value => setIsOpen(value)}
+/>
+```
+
+### Light/Dark theme toggle pattern
+```tsx
+<Swap
+  item1={<DynamicIcon name="moon" size={24} />}   // checked = dark mode
+  item2={<DynamicIcon name="sun" size={24} />}    // unchecked = light mode
+  effect="rotate"
+  onChange={isDark => applyTheme(isDark ? 'dark' : 'light')}
+/>
+```
+
+### Play/Pause media toggle
+```tsx
+<Swap
+  item1={<DynamicIcon name="pause" size={32} />}  // checked = playing
+  item2={<DynamicIcon name="play" size={32} />}   // unchecked = paused
+  effect="flip"
+  onChange={isPlaying => togglePlayback(isPlaying)}
+/>
+```
+
+## EFFECT REFERENCE
+| `effect` value | DaisyUI class | Animation |
+|---|---|---|
+| `"rotate"` | `swap-rotate` | Items rotate 45° during transition |
+| `"flip"` | `swap-flip` | Items flip on Y axis during transition |
+| *(omitted)* | `swap-rotate` | Defaults to rotate |
+
+## CONSTRAINTS
+- Both `item1` and `item2` are **REQUIRED**.
+- `item1` and `item2` are rendered via `<Dynamic component={...} />`, so they must be **component references** or **inline JSX** compatible with `SolidComponent`.
+- The component is **uncontrolled** — initial state is always `item2` (unchecked). There is no `defaultChecked` or `checked` prop.
+- The toggle is driven by a native `<input type="checkbox">` inside a `<label>`. Clicking anywhere on the rendered content toggles the state.
+- `onChange` receives `true` when switching to `item1` (checked), `false` when switching back to `item2`.
+
+## ANTI-PATTERNS
+```tsx
+// ❌ Forgetting that item1 is "ON" (checked) and item2 is "OFF" (unchecked)
+// If you want the hamburger visible first (default/off state), put it in item2
+<Swap
+  item1={<MenuIcon />}   // ❌ this shows when CHECKED (after click)
+  item2={<CloseIcon />}  // ❌ this shows by default (initial unchecked state)
+/>
+// ✅ Correct: item2 = default (off) state, item1 = toggled (on) state
+<Swap
+  item1={<CloseIcon />}  // shown after click
+  item2={<MenuIcon />}   // shown initially
+/>
+
+// ❌ Trying to control checked state externally (no prop for this)
+<Swap item1={A} item2={B} checked={isOpen()} />  // ❌ prop doesn't exist
+
+// ❌ Passing string/plain text directly (needs to be a component or JSX)
+<Swap item1="ON" item2="OFF" />  // may not render correctly with Dynamic
+// ✅ Wrap in a component
+<Swap item1={() => <span>ON</span>} item2={() => <span>OFF</span>} />
+```
+
+## DECISION RULES
+- Use `Swap` for **binary toggle icons** where animation is desired (theme toggle, menu open/close, play/pause).
+- Use `effect="rotate"` for rotating icons (typical hamburger → X transition).
+- Use `effect="flip"` for content that "flips" perspective (up/down arrows, front/back cards).
+- For text-only toggles or toggles requiring controlled state, use `Switch` instead.
+- `onChange` is optional; omit if you only need visual toggle without side effects.
+
+## CLASS SLOTS
+
+`Swap` is a single-element component — no `class` prop currently exposed. Style it by wrapping in a container or passing styled components as `item1`/`item2`.
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `sw01`, `sw02`) per project convention.
+
+> **Unique IDs**: if this component needs to generate HTML `id` attributes, always use `createUniqueId()` from `solid-js` — never `Math.random()` or `Date.now()`.

package/dist/skill/switch.skill.md.txt

@@ -0,0 +1,191 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Switch } from 'solid-tom-ui';`
+- **Export**: `Switch` (named export), `SwitchVariantProps` (type export)
+- **Framework**: SolidJS
+- **Purpose**: Toggle switch input — supports controlled and uncontrolled modes; styled with CVA variants + Tailwind
+
+## TYPE SIGNATURE
+
+```typescript
+import { Switch } from 'solid-tom-ui';
+
+// CONTROLLED mode: provide checked, do NOT provide defaultChecked
+<Switch
+  checked={boolean}                    // controlled value (required in controlled mode)
+  onChange?={(checked: boolean) => void}
+  // ...common props
+/>
+
+// UNCONTROLLED mode: provide defaultChecked, do NOT provide checked
+<Switch
+  defaultChecked={boolean}             // initial value (required in uncontrolled mode)
+  onChange?={(checked: boolean) => void}
+  // ...common props
+/>
+
+// MINIMAL mode: neither checked nor defaultChecked (defaults to false internally)
+<Switch onChange?={(checked: boolean) => void} />
+
+// Common props (applicable in all modes):
+//   size?    = 'xs' | 'sm' | 'md' | 'lg' | 'xl'    default: 'md'
+//   color?   = 'primary' | 'secondary' | 'accent' | 'neutral' | 'info' | 'success' | 'warning' | 'error'   default: 'primary'
+//   disabled?= boolean                               default: false
+//   loading? = boolean                               default: false
+//   onClick? = (checked: boolean) => void
+//   class?   = Partial<Record<'root' | 'content', string>>
+```
+
+## CONTROLLED vs UNCONTROLLED MUTEX RULE
+```
+checked      → controlled   → do NOT pass defaultChecked
+defaultChecked → uncontrolled → do NOT pass checked
+(neither)    → internal state starts at false
+```
+TypeScript enforces this: passing both `checked` and `defaultChecked` is a type error.
+
+## DEFAULTS
+| Prop | Default |
+|------|---------|
+| `size` | `'md'` |
+| `color` | `'primary'` |
+| `disabled` | `false` |
+| `loading` | `false` |
+| `defaultChecked` | `false` (when no controlled/uncontrolled prop given) |
+
+## SIZE REFERENCE
+| Value | Dimensions |
+|-------|-----------|
+| `xs` | `h-4 w-7` |
+| `sm` | `h-5 w-9` |
+| `md` | `h-6 w-11` (default) |
+| `lg` | `h-7 w-14` |
+| `xl` | `h-8 w-16` |
+
+## COLOR REFERENCE
+`primary` | `secondary` | `accent` | `neutral` | `info` | `success` | `warning` | `error`
+- When unchecked, the track color is always `bg-gray-300` regardless of `color`.
+- `color` applies only when the switch is checked.
+
+## USAGE PATTERNS
+
+### Uncontrolled (simplest)
+```tsx
+import { Switch } from 'solid-tom-ui';
+
+<Switch defaultChecked={false} onChange={checked => console.log(checked)} />
+```
+
+### Controlled
+```tsx
+import { createSignal } from 'solid-js';
+import { Switch } from 'solid-tom-ui';
+
+const [enabled, setEnabled] = createSignal(false);
+
+<Switch
+  checked={enabled()}
+  onChange={checked => setEnabled(checked)}
+/>
+
+// Toggle from outside
+<button onClick={() => setEnabled(v => !v)}>Toggle</button>
+```
+
+### With size and color
+```tsx
+<Switch size="lg" color="success" defaultChecked />
+<Switch size="xs" color="error" defaultChecked={false} />
+```
+
+### Disabled state
+```tsx
+<Switch size="md" color="primary" disabled defaultChecked={false} />
+<Switch size="md" color="primary" disabled={!hasPermission()} defaultChecked />
+```
+
+### Loading state (auto-disables the switch)
+```tsx
+const [saving, setSaving] = createSignal(false);
+
+<Switch
+  size="md"
+  color="primary"
+  loading={saving()}
+  defaultChecked
+/>
+// Note: loading=true automatically disables interaction
+```
+
+### Custom styling via class slot
+```tsx
+// Add shadow to the track
+<Switch size="md" color="primary" defaultChecked class={{ root: 'shadow-lg' }} />
+
+// Add ring/focus indicator
+<Switch size="xs" color="secondary" defaultChecked class={{ root: 'ring-2 ring-secondary ring-offset-2' }} />
+
+// Scale on hover
+<Switch size="lg" color="accent" defaultChecked class={{ root: 'hover:scale-110 transition-transform' }} />
+```
+
+### With onClick vs onChange
+```tsx
+// onChange fires with new value after toggle
+<Switch defaultChecked={false} onChange={newValue => applyChange(newValue)} />
+
+// onClick also fires with new value — use either; they receive the same value
+<Switch defaultChecked={false} onClick={newValue => console.log('clicked, new:', newValue)} />
+```
+
+## LOADING vs DISABLED BEHAVIOR
+| State | Interaction | Visual |
+|-------|-------------|--------|
+| `loading={true}` | Blocked (cursor-not-allowed, opacity-50) | Spinner shown inside thumb |
+| `disabled={true}` | Blocked (cursor-not-allowed, opacity-50) | No spinner |
+| `loading={true} disabled={true}` | Blocked (redundant, same as loading alone) | Spinner shown |
+
+> Prefer `loading` over `disabled` when an async operation is in progress.
+
+## ACCESSIBILITY
+- Renders as `<button role="switch" aria-checked={checked()}>`.
+- Keyboard focusable; click activates toggle.
+- `disabled` maps to the native `disabled` attribute on the button.
+
+## CLASS SLOTS
+| Slot | Targets |
+|------|---------|
+| `root` | The outer `<button>` element |
+| `content` | Declared in type but not currently wired in the implementation |
+
+> Use `class.root` for all custom styling of the switch track/wrapper.
+
+## ANTI-PATTERNS
+```tsx
+// ❌ Passing both checked and defaultChecked — TypeScript error
+<Switch checked={val()} defaultChecked={false} />
+
+// ❌ Expecting loading and disabled to behave differently — they both block interaction
+<Switch loading disabled />  // redundant
+
+// ❌ Using class.content — not wired in current implementation
+<Switch class={{ content: 'text-red-500' }} />
+// ✅ Use class.root for all styling
+<Switch class={{ root: 'shadow-xl' }} />
+
+// ❌ Forgetting that color only applies when checked
+// The unchecked track is always gray regardless of color prop
+```
+
+## DECISION RULES
+- **Controlled mode**: use when parent component needs to read or set the value programmatically.
+- **Uncontrolled mode**: use for simple local toggles where you only need `onChange` side effects.
+- **size**: match to surrounding UI density (`xs`/`sm` for dense tables, `lg`/`xl` for settings pages).
+- **color**: use semantic colors (`success` for enable, `error` for danger setting, `primary` for general).
+- **Swap vs Switch**: use `Switch` for boolean on/off settings; use `Swap` for icon-based visual toggles with animation.
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `sc01`, `sc02`) per project convention.
+
+> **Unique IDs**: if this component needs to generate HTML `id` attributes, always use `createUniqueId()` from `solid-js` — never `Math.random()` or `Date.now()`.