solid-tom-ui 1.0.7 → 1.0.10

package/dist/skill/code-preview.skill.md.txt

@@ -0,0 +1,240 @@
+## COMPONENT IDENTITY
+- **Import**: `import { CodePreview } from '@/components/doc/CodePreview';`
+- **Export**: `CodePreview` (named), `CODE_PREVIEW_THEMES`, `CodePreviewTheme` (type export)
+- **Framework**: SolidJS
+- **Purpose**: Internal documentation component — renders a tabbed panel with a live component preview and syntax-highlighted source code; used in Storybook stories and docs pages; NOT exported from `solid-tom-ui`
+- **Dependencies**: Shiki (syntax highlighting) · Prettier standalone (auto-format)
+
+---
+
+## TYPE SIGNATURE
+
+```ts
+interface CodePreviewProps {
+  code: string;                   // Source code string hiển thị trong tab Code
+  preview: Component<any>;        // SolidJS component render trong tab Preview
+  title?: string;                 // Tiêu đề (hiện chưa render, dành cho tương lai)
+  language?: string;              // Ngôn ngữ highlight; default: 'tsx'
+  theme?: CodePreviewTheme;       // Shiki theme; default: 'dracula'
+  classNames?: {
+    previewBlock?: string;        // Class bổ sung cho vùng preview
+  };
+}
+```
+
+---
+
+## BASIC USAGE
+
+```tsx
+const myCode = `<Button variant="solid" color="primary">Click me</Button>`;
+
+<CodePreview
+  code={myCode}
+  preview={() => <Button variant="solid" color="primary">Click me</Button>}
+/>
+```
+
+---
+
+## USAGE WITH THEME
+
+```tsx
+<CodePreview
+  code={myCode}
+  preview={() => <MyComponent />}
+  theme="tokyo-night"
+/>
+```
+
+---
+
+## USAGE WITH CUSTOM LANGUAGE
+
+```tsx
+<CodePreview
+  code={`const x: number = 42;`}
+  preview={() => <div>42</div>}
+  language="typescript"
+/>
+```
+
+Các giá trị `language` được hỗ trợ: `'tsx'` · `'typescript'` · `'jsx'` · `'javascript'`
+
+---
+
+## USAGE WITH PREVIEW CLASSNAMES
+
+```tsx
+<CodePreview
+  code={myCode}
+  preview={() => <MyComponent />}
+  classNames={{ previewBlock: 'bg-base-200 min-h-[300px]' }}
+/>
+```
+
+---
+
+## CODE FORMATTING
+
+Code truyền vào `code` prop **không cần format thủ công** — Prettier tự động:
+- Căn chỉnh indentation (2 spaces)
+- Thêm trailing comma
+- Wrap dòng dài (printWidth: 80)
+- Semi-colon ở cuối statement
+
+**Lưu ý**: Prettier dùng `babel` parser, nhận JSX fragment bare (không cần wrapper function):
+
+```tsx
+// ✅ Đúng — JSX fragment bare
+const code = `<Button color="primary">Click</Button>`;
+
+// ✅ Đúng — JSX multi-line
+const code = `
+<FloatButton
+  type="flower"
+  color="orange"
+  actions={[<Button />, <Button />]}
+/>
+`;
+
+// ✅ Đúng — TypeScript expression
+const code = `const x: Record<string, number> = { a: 1 };`;
+```
+
+---
+
+## AVAILABLE THEMES
+
+Export `CODE_PREVIEW_THEMES` chứa toàn bộ danh sách, dùng để build UI chọn theme:
+
+```tsx
+import { CODE_PREVIEW_THEMES } from '@/components/doc/CodePreview';
+
+// Render dropdown chọn theme
+<select>
+  {CODE_PREVIEW_THEMES.map(t => <option value={t}>{t}</option>)}
+</select>
+```
+
+### Danh sách themes
+
+| Theme | Phong cách |
+|---|---|
+| `dracula` *(default)* | Dark purple — Dracula official |
+| `dracula-soft` | Dracula nhạt màu hơn |
+| `github-dark` | GitHub dark |
+| `github-dark-default` | GitHub dark default |
+| `github-dark-dimmed` | GitHub dark dimmed |
+| `github-dark-high-contrast` | GitHub dark high contrast |
+| `github-light` | GitHub light |
+| `github-light-default` | GitHub light default |
+| `github-light-high-contrast` | GitHub light high contrast |
+| `tokyo-night` | Tokyo Night (blue/purple) |
+| `one-dark-pro` | Atom One Dark Pro |
+| `nord` | Nord (arctic blue tones) |
+| `monokai` | Monokai classic |
+| `night-owl` | Night Owl (Sarah Drasner) |
+| `catppuccin-mocha` | Catppuccin Mocha (warm dark) |
+| `catppuccin-macchiato` | Catppuccin Macchiato |
+| `catppuccin-frappe` | Catppuccin Frappé |
+| `catppuccin-latte` | Catppuccin Latte (light) |
+| `rose-pine` | Rosé Pine (dark) |
+| `rose-pine-dawn` | Rosé Pine Dawn (light) |
+| `rose-pine-moon` | Rosé Pine Moon |
+| `material-theme` | Material Theme |
+| `material-theme-darker` | Material Theme Darker |
+| `material-theme-ocean` | Material Theme Ocean |
+| `material-theme-palenight` | Material Theme Palenight |
+| `material-theme-lighter` | Material Theme Lighter |
+| `vitesse-dark` | Vitesse Dark (Anthony Fu) |
+| `vitesse-light` | Vitesse Light |
+| `vitesse-black` | Vitesse Black |
+| `solarized-dark` | Solarized Dark |
+| `solarized-light` | Solarized Light |
+| `everforest-dark` | Everforest Dark |
+| `everforest-light` | Everforest Light |
+| `synthwave-84` | SynthWave '84 (neon) |
+| `poimandres` | Poimandres (deep space) |
+| `ayu-dark` | Ayu Dark |
+| `aurora-x` | Aurora X |
+| `andromeeda` | Andromeeda |
+| `dark-plus` | Dark+ (VS Code default dark) |
+| `light-plus` | Light+ (VS Code default light) |
+| `min-dark` | Min Dark (minimal) |
+| `min-light` | Min Light (minimal) |
+| `plastic` | Plastic |
+| `red` | Red |
+| `slack-dark` | Slack Dark |
+| `slack-ochin` | Slack Ochin |
+| `snazzy-light` | Snazzy Light |
+| `vesper` | Vesper |
+
+---
+
+## PATTERN: DÙNG TRONG STORYBOOK STORY
+
+```tsx
+import { CodePreview } from '@/components/doc/CodePreview';
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+
+const myCode = `<MyComponent
+  prop="value"
+  onAction={() => {}}
+/>`;
+
+export const Example: StoryObj = {
+  render: () => (
+    <CodePreview
+      code={myCode}
+      preview={() => (
+        <MyComponent
+          prop="value"
+          onAction={() => {}}
+        />
+      )}
+    />
+  ),
+};
+```
+
+---
+
+## PATTERN: DÙNG TRONG IFRAME (component cần isolated CSS)
+
+```tsx
+import { CodePreview } from '@/components/doc/CodePreview';
+import { Iframe } from '@/components/iframe';
+
+<CodePreview
+  code={myCode}
+  preview={() => (
+    <Iframe
+      element={() => <MyComponent />}
+    />
+  )}
+/>
+```
+
+Dùng `<Iframe>` khi component có CSS toàn cục (animation, fixed position, z-index cao) có thể xung đột với trang docs.
+
+---
+
+## INTERNALS (cho maintainer)
+
+| Layer | Implementation |
+|---|---|
+| **Formatter** | Prettier 3.x standalone, parser `babel` |
+| **Highlighter** | Shiki 4.x, `createHighlighter` singleton |
+| **Theme loading** | Lazy per theme, cache qua `Set<string>` |
+| **Async state** | SolidJS `createResource` + `Suspense` |
+| **Default theme** | `dracula` (load khi init) |
+| **Default language** | `tsx` |
+| **Supported langs** | `tsx`, `typescript`, `jsx`, `javascript` |
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `cp01`, `cp02`) 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/collapse.skill.md.txt

@@ -0,0 +1,329 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Collapse } from 'solid-tom-ui';`
+- **Export**: `Collapse` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Collapsible panel — NOT a `ParentComponent`; content passed via `content` prop
+
+---
+
+## TYPE SIGNATURE
+
+```ts
+interface CollapseProps {
+  title: string;                    // REQUIRED — header text
+  content: SolidComponent;          // REQUIRED — body content (JSX, string, or function component)
+  icon?: {
+    type?: 'arrow' | 'plus';        // icon style; default: 'arrow'
+    postion?: 'start' | 'end';      // icon position; default: 'end'
+  };
+  force?: 'open' | 'close';         // controlled visibility — omit for uncontrolled
+  onOpen?: () => void;              // callback when panel opens (uncontrolled only)
+  onClose?: () => void;             // callback when panel closes (uncontrolled only)
+  id?: string;                      // id applied to the internal checkbox input
+  color?: BaseColorProps | 'transparent'; // semantic color theme; default: 'transparent'
+  class?: Partial<Record<'root' | 'title' | 'content', string>>;
+}
+```
+
+---
+
+## DEFAULT VALUES (via `mergeProps`)
+
+| Prop            | Default         |
+|-----------------|-----------------|
+| `icon.type`     | `'arrow'`       |
+| `icon.postion`  | `'end'`         |
+| `color`         | `'transparent'` |
+
+---
+
+## PROP REFERENCE
+
+| Prop            | Type                              | Required | Description                                                                              |
+|-----------------|-----------------------------------|----------|------------------------------------------------------------------------------------------|
+| `title`         | `string`                          | ✅ YES   | Text shown in the collapse header bar                                                    |
+| `content`       | `SolidComponent`                  | ✅ YES   | Content rendered in the collapsible body panel                                           |
+| `icon.type`     | `'arrow' \| 'plus'`              | ❌ NO    | `'arrow'` → chevron icon; `'plus'` → plus/minus icon                                    |
+| `icon.postion`  | `'start' \| 'end'`               | ❌ NO    | `'end'` → icon on right side (default); `'start'` → icon on left side                  |
+| `force`         | `'open' \| 'close'`              | ❌ NO    | Forces panel open or closed. When set, checkbox is removed and callbacks are ignored     |
+| `onOpen`        | `() => void`                      | ❌ NO    | Fired when user opens the panel (uncontrolled only — ignored when `force` is set)        |
+| `onClose`       | `() => void`                      | ❌ NO    | Fired when user closes the panel (uncontrolled only — ignored when `force` is set)       |
+| `id`            | `string`                          | ❌ NO    | `id` attribute on the internal `<input type="checkbox">` — enables external label links  |
+| `color`         | `BaseColorProps \| 'transparent'` | ❌ NO    | Semantic color theme — sets border, background tint, and title/icon color via `--color`  |
+| `class.root`    | `string`                          | ❌ NO    | Extra classes on the root `<div class="collapse">`                                       |
+| `class.title`   | `string`                          | ❌ NO    | Extra classes on `<div class="collapse-title">`                                          |
+| `class.content` | `string`                          | ❌ NO    | Extra classes on `<div class="collapse-content">`                                        |
+
+> ⚠️ NOTE: `icon.postion` has a typo in source — it is `postion` (missing 'i'), not `position`. Use exactly `postion` when passing the prop.
+
+---
+
+## OPEN/CLOSE MODES
+
+### Mode 1 — Uncontrolled (default, no `force` prop)
+- An `<input type="checkbox">` is rendered inside the root div
+- DaisyUI uses the checkbox checked state to show/hide the panel via CSS
+- `onOpen` fires when checkbox becomes checked; `onClose` fires when unchecked
+- `id` prop sets the checkbox's `id` — allows external `<label for="id">` to toggle the collapse
+
+```tsx
+<Collapse
+  title="What is SolidJS?"
+  content={<p>SolidJS is a declarative UI library.</p>}
+  onOpen={() => console.log('opened')}
+  onClose={() => console.log('closed')}
+/>
+```
+
+### Mode 2 — Controlled (`force` prop)
+- `force="open"` → adds `collapse-open` class, checkbox is **removed from DOM**
+- `force="close"` → adds `collapse-close` class, checkbox is **removed from DOM**
+- `onOpen` and `onClose` are **completely ignored** when `force` is set
+- Toggling is the consumer's responsibility via a reactive signal
+
+```tsx
+const [status, setStatus] = createSignal<'open' | 'close'>('close');
+
+<Button onClick={() => setStatus(s => s === 'open' ? 'close' : 'open')}>
+  Toggle
+</Button>
+
+<Collapse
+  title="Controlled Collapse"
+  content={<p>Controlled by external signal.</p>}
+  force={status()}
+/>
+```
+
+### Mode 3 — Mixed: `force={undefined}` restores uncontrolled
+- Passing `force={undefined}` (or not passing `force`) keeps the checkbox in the DOM
+- Useful when signal can return `undefined` as a "no override" state
+
+```tsx
+// signal can be 'open' | 'close' | undefined
+const [force, setForce] = createSignal<'open' | 'close' | undefined>(undefined);
+
+<Collapse title="..." content="..." force={force()} />
+```
+
+---
+
+## ICON VARIANTS
+
+### `icon.type`
+| Value     | DaisyUI class      | Visual                     |
+|-----------|--------------------|----------------------------|
+| `'arrow'` | `collapse-arrow`   | Chevron (▼) rotates on open |
+| `'plus'`  | `collapse-plus`    | Plus (+) changes to minus (−) on open |
+
+### `icon.postion`
+| Value     | CSS effect                                              |
+|-----------|---------------------------------------------------------|
+| `'end'`   | Icon on the right side (default DaisyUI behavior)       |
+| `'start'` | Icon on the left side — applies `after:start-5 after:end-auto pe-4 ps-12` |
+
+---
+
+## `content` PROP — Accepts multiple forms
+
+`SolidComponent` means the prop accepts:
+
+```tsx
+// 1. String literal
+content="Plain text content"
+
+// 2. JSX element
+content={<p class="text-sm">Some <strong>HTML</strong> content</p>}
+
+// 3. Function component (with own reactive state)
+content={() => {
+  const [count, setCount] = createSignal(0);
+  return (
+    <Button onClick={() => setCount(c => c + 1)}>
+      Count = {count()}
+    </Button>
+  );
+}}
+```
+
+> ℹ️ Function form is useful when the content needs its own SolidJS reactive state. The function is called as a component, preserving signal reactivity.
+
+---
+
+## INTERNAL DOM STRUCTURE
+
+```
+<div class="bg-base-100 border-base-300 collapse border collapse-arrow|plus [collapse-open|collapse-close] [class.root]">
+  │
+  ├── <input type="checkbox" id="?" onChange={...} />   ← only when force is undefined
+  │
+  ├── <div class="collapse-title font-semibold [iconPosition classes] [class.title]">
+  │     {title}
+  │   </div>
+  │
+  └── <div class="collapse-content text-sm [class.content]">
+        {content}
+      </div>
+```
+
+---
+
+## `id` PROP — External trigger via `<label>`
+
+The `id` is applied to the internal `<input type="checkbox">`, enabling an external `<label>` element to toggle the collapse without clicking the title bar directly:
+
+```tsx
+<label for="my-collapse" class="btn">Toggle from outside</label>
+
+<Collapse
+  id="my-collapse"
+  title="Externally triggered"
+  content="Toggled by the label above"
+/>
+```
+
+> ⚠️ `id` only works in uncontrolled mode — when `force` is set, the checkbox is removed from the DOM and the `id` has no effect.
+
+---
+
+## BEHAVIOR NOTES FOR AGENTS
+
+1. **`force` removes the checkbox entirely** — when `force` is set, `<Show when={!p.force}>` evaluates to false and the `<input>` is unmounted. The DaisyUI `collapse-open`/`collapse-close` classes on the root div take over visibility control.
+
+2. **`onOpen`/`onClose` are checkbox-based** — they fire on `onChange` of the checkbox, which only exists in uncontrolled mode. Setting `force` silently disables these callbacks with no error.
+
+3. **`content` renders inside `collapse-content` with `text-sm`** — the wrapper always has `text-sm`. Override with `class.content` if larger text is needed.
+
+4. **`title` is `string` only** — no JSX allowed in the title. For rich title content, use `class.title` to style and keep the text in `title`.
+
+5. **`icon.postion` typo is intentional** — the source code has `postion` (not `position`). Always use `postion` in the prop object or TypeScript will error.
+
+6. **Root div always has `bg-base-100 border-base-300 border`** — there is no prop to remove the border or background. Use `class.root` to override with Tailwind.
+
+7. **Accordion pattern** — to build an accordion (only one item open at a time), use the native HTML behavior: give all checkboxes the same `name` attribute. However, this component does not expose a `name` prop — implement accordion via controlled `force` signals instead.
+
+8. **`color` prop adds `sui-collapse` class** — when `color` is set to any value other than `'transparent'`, the class `sui-collapse` is added to the root div. This class uses `var(--color)` (set by `.color-primary` etc.) to apply border tint, background tint, title color, and icon color.
+
+---
+
+## COLOR SYSTEM
+
+The `color` prop accepts any `BaseColorProps` value (`'primary' | 'neutral' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error'`) or `'transparent'` (default — no color applied).
+
+### How it works
+1. `getColor(p.color)` maps the value to a CSS class (e.g. `color-primary`) that sets `--color: var(--color-primary)`.
+2. When color is not `'transparent'`, the class `sui-collapse` is also added — this class consumes `var(--color)` to style the collapse:
+   - **Border**: `color-mix(in oklch, var(--color) 30%, var(--color-base-300))`
+   - **Background**: `color-mix(in oklch, var(--color) 5%, var(--color-base-100))` — a subtle tint
+   - **Title text**: `var(--color)`
+   - **Icon (arrow/plus)**: `var(--color)` via `::after` pseudo-element
+
+```tsx
+// All 8 color variants
+<Collapse color="primary" title="Primary" content="..." />
+<Collapse color="secondary" title="Secondary" content="..." />
+<Collapse color="accent" title="Accent" content="..." />
+<Collapse color="neutral" title="Neutral" content="..." />
+<Collapse color="info" title="Info" content="..." />
+<Collapse color="success" title="Success" content="..." />
+<Collapse color="warning" title="Warning" content="..." />
+<Collapse color="error" title="Error" content="..." />
+
+// Default — no color styling
+<Collapse title="No color" content="..." />
+// Explicit transparent — same as default
+<Collapse color="transparent" title="Transparent" content="..." />
+```
+
+> ℹ️ The `color` prop and the `class` prop are independent — you can combine `color="primary"` with `class.content` to further customize the content area without affecting the color theme.
+
+---
+
+## COMMON MISTAKES TO AVOID
+
+| Mistake | Correct approach |
+|---|---|
+| Using `icon.position` (with 'i') | Use `icon.postion` — the prop has a typo in source |
+| Expecting `onOpen`/`onClose` to fire when `force` is set | These callbacks only fire in uncontrolled mode |
+| Passing JSX to `title` | `title` is `string` only; style text with `class.title` |
+| Setting `id` when `force` is also set | `id` targets the checkbox which is removed in controlled mode |
+| Overriding `text-sm` inside content without `class.content` | Use `class.content` to override content text styles |
+| Using `force={false}` expecting uncontrolled | `force` accepts `'open' \| 'close' \| undefined` — use `undefined` or omit prop for uncontrolled |
+| Using `class.root` for semantic color when `color` prop exists | Prefer `color="primary"` over `class={{ root: 'border-primary bg-primary/5' }}` |
+
+---
+
+## FULL EXAMPLE — All features
+
+```tsx
+import { Collapse } from 'solid-tom-ui';
+import { createSignal } from 'solid-js';
+import { Button } from 'solid-tom-ui';
+
+// 1. Uncontrolled with arrow icon (default)
+<Collapse
+  title="What is SolidJS?"
+  content={<p>SolidJS is a fine-grained reactive UI library.</p>}
+  onOpen={() => console.log('opened')}
+  onClose={() => console.log('closed')}
+/>
+
+// 2. Plus icon, icon on start (left)
+<Collapse
+  title="How does reactivity work?"
+  content="Signals track dependencies automatically at runtime."
+  icon={{ type: 'plus', postion: 'start' }}
+/>
+
+// 3. Controlled mode
+const [force, setForce] = createSignal<'open' | 'close' | undefined>(undefined);
+
+<Button onClick={() => setForce(f => f === 'open' ? 'close' : 'open')}>
+  Toggle
+</Button>
+<Collapse
+  title="Controlled Collapse"
+  content={<p>Opened and closed externally.</p>}
+  force={force()}
+/>
+
+// 4. Content with own reactive state
+<Collapse
+  title="Interactive Content"
+  content={() => {
+    const [count, setCount] = createSignal(0);
+    return (
+      <Button variant="solid" onClick={() => setCount(c => c + 1)}>
+        Clicked {count()} times
+      </Button>
+    );
+  }}
+/>
+
+// 5. External label trigger via id
+<label for="faq-1" class="btn btn-sm">Open FAQ</label>
+<Collapse
+  id="faq-1"
+  title="Frequently Asked Question"
+  content="This is the answer to the FAQ."
+  class={{ root: 'mt-2' }}
+/>
+
+// 6. Custom styling
+<Collapse
+  title="Styled Collapse"
+  content="Custom styled content area."
+  class={{
+    root: 'border-primary bg-primary/5',
+    title: 'text-primary text-lg',
+    content: 'text-base text-base-content/70',
+  }}
+/>
+```
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `co01`, `co02`) 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()`.