solid-tom-ui 1.0.8 → 1.0.10

package/dist/skill/context-menu.skill.md.txt

@@ -0,0 +1,233 @@
+## COMPONENT IDENTITY
+- **Import**: `import { ContextMenu, createContextMenuHandle } from 'solid-tom-ui';`
+- **Exports**: `ContextMenu` (renderer), `createContextMenuHandle` (factory)
+- **Framework**: SolidJS
+- **Purpose**: Context-aware right-click menu with a registry pattern. Each UI zone registers its own items independently; the menu builds the visible list from the current context at trigger time. No coupling between zones — each feature owns its items.
+
+## TYPE SIGNATURES
+
+### createContextMenuHandle
+```typescript
+import { createContextMenuHandle } from 'solid-tom-ui';
+
+function createContextMenuHandle<TContext extends Record<string, unknown>>(): ContextMenuHandle<TContext>;
+
+type ContextMenuHandle<TContext> = {
+  register:   (item: RegistryItem<TContext>) => void;
+  unregister: (key: string) => void;
+  trigger:    (e: MouseEvent, ctx: TContext) => void;
+};
+```
+
+### ContextMenu
+```typescript
+import { ContextMenu } from 'solid-tom-ui';
+
+type ContextMenuProps<TContext> = {
+  handle: ContextMenuHandle<TContext>;             // REQUIRED: handle from createContextMenuHandle()
+  class?: Partial<Record<
+    'content' | 'item' | 'separator' | 'submenu',
+    string
+  >>;                                             // CSS slot overrides
+};
+```
+
+### RegistryItem (discriminated union)
+```typescript
+// Shared base fields
+type BaseRegistryItem<TContext> = {
+  key:         string;                           // REQUIRED: unique ID for dedup / unregister
+  label:       string;                           // REQUIRED: display text
+  when?:       (ctx: TContext) => boolean;       // visibility predicate — omit = always visible
+  disabled?:   (ctx: TContext) => boolean;       // disable predicate — omit = always enabled
+  shortcut?:   string;                           // display-only hint (e.g. "Ctrl+C"), not bound
+  prefixIcon?: JSXElement;                       // icon element rendered to the left of label
+  order?:      number;                           // sort order, lower = higher up (default: 100)
+  group?:      string;                           // items in the same group are visually grouped;
+                                                 // separators are auto-inserted between groups
+};
+
+// Action item
+type ActionRegistryItem<TContext> = BaseRegistryItem<TContext> & {
+  type:    'item';
+  onClick: (ctx: TContext) => void;              // REQUIRED for 'item'
+};
+
+// Submenu item
+type SubmenuRegistryItem<TContext> = BaseRegistryItem<TContext> & {
+  type:  'submenu';
+  items: RegistryItem<TContext>[];               // REQUIRED for 'submenu'; one level deep
+};
+
+type RegistryItem<TContext> = ActionRegistryItem<TContext> | SubmenuRegistryItem<TContext>;
+```
+
+## KEY RULES
+- `createContextMenuHandle<TContext>()` is generic — define your own context type that describes UI state at the moment of right-click
+- Only **one** context menu may be open at a time (shared singleton open/close state) — multiple handles still share this state
+- `<ContextMenu>` **must** be rendered in the JSX tree, typically near the app root to avoid z-index conflicts
+- `prefixIcon` accepts a `JSXElement` (rendered JSX), not a function component
+- Submenus are **one level deep** only — nested `items` arrays inside a submenu are not supported
+- `shortcut` is display-only and does **not** bind keyboard events — wire those separately
+
+## MINIMAL SETUP
+
+```tsx
+import { createContextMenuHandle, ContextMenu } from 'solid-tom-ui';
+
+// 1. Define context shape
+type MyCtx = { zone: 'editor' | 'sidebar'; hasSelection: boolean };
+
+// 2. Create handle (component level or module scope)
+const handle = createContextMenuHandle<MyCtx>();
+
+// 3. Register items
+handle.register({
+  key: 'copy',
+  type: 'item',
+  label: 'Copy',
+  when: ctx => ctx.hasSelection,
+  onClick: ctx => console.log('copy in', ctx.zone),
+});
+
+// 4. Render once near app root
+<ContextMenu handle={handle} />
+
+// 5. Trigger on right-click
+<div onContextMenu={e => handle.trigger(e, { zone: 'editor', hasSelection: true })}>
+  Right-click here
+</div>
+```
+
+## USAGE PATTERNS
+
+### Module-scoped handle (shared across components)
+```ts
+// context-menu.handle.ts
+export type AppCtx = { zone: string; isFile: boolean };
+export const appMenuHandle = createContextMenuHandle<AppCtx>();
+
+// FileExplorer.tsx — registers its own items
+appMenuHandle.register({ key: 'rename', type: 'item', label: 'Rename', when: ctx => ctx.isFile, onClick: ctx => rename(ctx) });
+
+// Editor.tsx — registers independent items
+appMenuHandle.register({ key: 'copy', type: 'item', label: 'Copy', when: ctx => ctx.zone === 'editor', onClick: () => copy() });
+
+// App.tsx — render once
+<ContextMenu handle={appMenuHandle} />
+```
+
+### Dynamic registration / unregistration
+```ts
+handle.register({ key: 'admin-delete', type: 'item', label: 'Delete', onClick: () => deleteItem() });
+
+// Later (e.g. user logs out):
+handle.unregister('admin-delete');
+```
+
+### Grouped items with separators
+```ts
+handle.register({ key: 'cut',    type: 'item', label: 'Cut',    group: 'clipboard', order: 10, onClick: () => cut() });
+handle.register({ key: 'copy',   type: 'item', label: 'Copy',   group: 'clipboard', order: 11, onClick: () => copy() });
+handle.register({ key: 'paste',  type: 'item', label: 'Paste',  group: 'clipboard', order: 12, onClick: () => paste() });
+handle.register({ key: 'delete', type: 'item', label: 'Delete', group: 'danger',    order: 20, onClick: () => del() });
+// Separator is auto-inserted between 'clipboard' and 'danger' groups
+```
+
+### Submenu
+```ts
+handle.register({
+  key: 'export',
+  type: 'submenu',
+  label: 'Export as',
+  items: [
+    { key: 'export-png', type: 'item', label: 'PNG',  onClick: () => exportPng() },
+    { key: 'export-svg', type: 'item', label: 'SVG',  onClick: () => exportSvg() },
+    { key: 'export-pdf', type: 'item', label: 'PDF',  onClick: () => exportPdf() },
+  ],
+});
+```
+
+### Icon and keyboard shortcut hints
+```ts
+import Copy from 'lucide-solid/icons/copy';
+
+handle.register({
+  key: 'copy',
+  type: 'item',
+  label: 'Copy',
+  prefixIcon: <Copy size={14} />,
+  shortcut: 'Ctrl+C',
+  onClick: () => copy(),
+});
+```
+
+### Multiple independent menus (separate context types)
+```ts
+const editorMenu = createContextMenuHandle<EditorCtx>();
+const tableMenu  = createContextMenuHandle<TableCtx>();
+
+<ContextMenu handle={editorMenu} />
+<ContextMenu handle={tableMenu} />
+```
+
+### CSS slot override
+```tsx
+<ContextMenu
+  handle={handle}
+  class={{
+    content:   'rounded-xl shadow-2xl',
+    item:      'text-sm',
+    separator: 'my-1 opacity-30',
+    submenu:   'font-medium',
+  }}
+/>
+```
+
+## DECISION RULES
+
+**Single handle vs multiple handles:**
+- One shared context type across the entire app → single module-scoped handle
+- Completely separate feature areas with different context shapes → separate handles per area
+
+**`when` vs `disabled`:**
+- Item doesn't belong to this context at all → use `when` (hides the item)
+- Item belongs but action is not available right now → use `disabled` (shows grayed-out)
+
+**`order` and `group`:**
+- Use `group` to visually separate categories (separators are automatic)
+- Use `order` to control position within a group (lower number = higher position)
+- If order is not specified, items are rendered in registration order (default: 100)
+
+**`prefixIcon`:**
+- Pass a rendered JSX element: `prefixIcon={<Copy size={14} />}`
+- Import icons by direct path to avoid bundling the entire lucide library
+
+## ANTI-PATTERNS
+```tsx
+// ❌ Rendering ContextMenu deep in a child component — may cause z-index issues
+<Modal>
+  <ContextMenu handle={handle} />   // wrong — render near app root instead
+</Modal>
+
+// ❌ Passing a function component as prefixIcon (it won't render)
+prefixIcon={Copy}                    // wrong
+prefixIcon={<Copy size={14} />}     // ✅ pass JSX element
+
+// ❌ Nesting submenus more than one level deep (not supported)
+{
+  type: 'submenu',
+  items: [{ type: 'submenu', items: [...] }]   // second level ignored
+}
+
+// ❌ Expecting shortcut to bind a keyboard event
+shortcut: 'Ctrl+Z'   // display only — wire onKeyDown separately
+```
+
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `cm01`, `cm02`) 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/diff.skill.md.txt

@@ -0,0 +1,244 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Diff } from 'solid-tom-ui';`
+- **Export**: `Diff` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Interactive image/content comparison slider — user drags a resizer to reveal left vs right panels; NOT a `ParentComponent`, content passed via `images` prop array
+
+---
+
+## TYPE SIGNATURE
+
+```ts
+type DiffProps = {
+  images: SolidComponent[]; // REQUIRED — must be exactly 2 elements
+  class?: string; // extra classes on root <figure>
+};
+```
+
+## CLASS SLOTS
+
+`Diff` is a single-element component — the `class` prop targets the root `<figure>` only. There are no named slots.
+
+> **CSS encoding**: internal CSS classes follow the project convention using short encoded names (e.g. `df01`, `df02`). Do not reference DaisyUI's `diff-item-1` / `diff-item-2` class names directly in your own styles — use the `class` prop or wrap with your own container.
+
+---
+
+## PROP REFERENCE
+
+| Prop     | Type               | Required | Description                                                                           |
+| -------- | ------------------ | -------- | ------------------------------------------------------------------------------------- |
+| `images` | `SolidComponent[]` | ✅ YES   | Array of **exactly 2** JSX elements — index `0` = left panel, index `1` = right panel |
+| `class`  | `string`           | ❌ NO    | Extra Tailwind classes appended to the root `<figure>` element                        |
+
+---
+
+## HARD CONSTRAINT: `images` must have exactly 2 elements
+
+- Passing fewer or more than 2 elements → component returns `<></>` (renders nothing) and fires `console.warn('You need to provide exactly 2 images')`
+- There is no partial rendering fallback — the entire component is suppressed
+
+```ts
+// ✅ Valid
+images={[<img src="a.webp" />, <img src="b.webp" />]}
+
+// ❌ Invalid — renders nothing
+images={[<img src="a.webp" />]}
+images={[<img src="a.webp" />, <img src="b.webp" />, <img src="c.webp" />]}
+```
+
+---
+
+## INTERNAL DOM STRUCTURE
+
+```
+<figure class="diff aspect-video [class]" tabindex="0">
+  │
+  ├── <div class="diff-item-1" role="img" tabindex="0">
+  │     {images[0]}   ← LEFT panel (revealed by dragging resizer right)
+  │   </div>
+  │
+  ├── <div class="diff-item-2" role="img">
+  │     {images[1]}   ← RIGHT panel (base/background layer)
+  │   </div>
+  │
+  └── <div class="diff-resizer"></div>   ← invisible drag handle
+```
+
+### Layer rendering order
+
+- `diff-item-2` (right/background) renders behind — visible in full by default
+- `diff-item-1` (left/foreground) renders on top with `z-index: 1`, clipped by the resizer position
+- Dragging resizer RIGHT → reveals more of `images[0]` (left panel)
+- Dragging resizer LEFT → reveals more of `images[1]` (right panel)
+
+---
+
+## INTERACTION MECHANISM — CSS-only, no JS state
+
+The slider is driven entirely by CSS using a native `resize: horizontal` invisible div (`.diff-resizer`):
+
+- Default resizer position: `width: 50cqi` → panels shown 50/50
+- Resizer `min-width: 1rem`, `max-width: calc(100cqi - 1rem)` — cannot be dragged beyond edges
+- **Keyboard accessible**: `<figure tabindex="0">` and `<div class="diff-item-1" tabindex="0">` both focusable
+  - Focus on `<figure>` → resizer snaps to `min-width: 95cqi` (left panel nearly full)
+  - Focus on `diff-item-1` → resizer snaps to `min-width: 5cqi` (right panel nearly full)
+  - Snap transitions animated with `transition: min-width 0.3s ease-out`
+
+Agents do NOT manage any open/close or drag state — it is fully CSS-driven.
+
+---
+
+## CONTENT RULES FOR `images[0]` AND `images[1]`
+
+Both slots accept **any JSX element**, not just `<img>`. Internal CSS applies to all direct children:
+
+```css
+/* Applied to direct children of both diff-item-1 and diff-item-2 */
+position: absolute;
+top: 0;
+bottom: 0;
+left: 0;
+height: 100%;
+width: 100cqi;
+object-fit: cover;
+object-position: center;
+pointer-events: none;
+```
+
+### What this means for agents:
+
+- **`<img>`**: works perfectly — `object-fit: cover` is applied automatically
+- **`<div>`**: also works — div fills the full panel area. Use `grid place-content-center` or flex for internal layout
+- **Interactive elements inside panels**: will NOT work — `pointer-events: none` is applied to all children. Do NOT put buttons, links, or inputs inside `images`
+- **Do NOT add layout wrappers** around the img/div — children are positioned absolutely with `width: 100cqi`
+
+---
+
+## ASPECT RATIO
+
+- Root `<figure>` always has class `aspect-video` (16:9 ratio) applied by default
+- To change aspect ratio, override via `class` prop:
+
+```tsx
+// Square
+<Diff images={[...]} class="aspect-square" />
+
+// Custom ratio
+<Diff images={[...]} class="aspect-4/3" />
+
+// Fixed height
+<Diff images={[...]} class="h-100" />
+```
+
+---
+
+## USAGE PATTERNS
+
+### Pattern 1 — Image vs image (most common)
+
+```tsx
+<Diff
+  images={[
+    <img alt="before" src="/images/before.webp" />,
+    <img alt="after" src="/images/after.webp" />,
+  ]}
+/>
+```
+
+### Pattern 2 — Image vs custom div content
+
+```tsx
+<Diff
+  images={[
+    <img alt="photo" src="/images/photo.webp" />,
+    <div class="bg-base-200 text-base-content grid place-content-center text-6xl font-black">
+      BEFORE
+    </div>,
+  ]}
+/>
+```
+
+### Pattern 3 — Custom aspect ratio
+
+```tsx
+<Diff
+  class="aspect-square w-100"
+  images={[
+    <img alt="original" src="/images/original.webp" />,
+    <img alt="filtered" src="/images/filtered.webp" />,
+  ]}
+/>
+```
+
+### Pattern 4 — Two styled div panels
+
+```tsx
+<Diff
+  images={[
+    <div class="bg-primary text-primary-content grid place-content-center text-4xl font-bold">
+      Dark Mode
+    </div>,
+    <div class="bg-base-100 text-base-content grid place-content-center text-4xl font-bold">
+      Light Mode
+    </div>,
+  ]}
+/>
+```
+
+---
+
+## BEHAVIOR NOTES FOR AGENTS
+
+1. **`images[0]` = left (foreground), `images[1]` = right (background)** — the order determines which panel is clipped by the drag handle. Left panel sits on top and is revealed by dragging right.
+
+2. **Component is a `<figure>` element** — semantically appropriate for media comparison. Root is not a `<div>`.
+
+3. **`pointer-events: none` on all panel children** — nothing inside `images[0]` or `images[1]` can be clicked, hovered, or interacted with. Only the resizer handle is interactive.
+
+4. **No JS drag state** — the drag interaction is entirely driven by the native browser `resize: horizontal` CSS property on `.diff-resizer`. No SolidJS signals or event handlers involved.
+
+5. **`class` prop targets the root `<figure>` only** — cannot target internal `.diff-item-1`, `.diff-item-2`, or `.diff-resizer` via this prop.
+
+6. **Width fills container** — root `<figure>` has `width: 100%`. Wrap in a sized container or use `class="w-[500px]"` to constrain.
+
+---
+
+## COMMON MISTAKES TO AVOID
+
+| Mistake                                                       | Correct approach                                                                     |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Passing 1 or 3+ items in `images`                             | Always pass exactly 2 elements — no more, no less                                    |
+| Putting interactive elements (buttons, links) inside `images` | `pointer-events: none` blocks all interactions inside panels                         |
+| Wrapping `<img>` in an extra `<div>`                          | Pass `<img>` directly — children are already positioned absolutely to fill the panel |
+| Expecting `class` to style inner panels                       | `class` only applies to the root `<figure>`                                          |
+| Assuming left panel is `images[1]`                            | `images[0]` = left/foreground (clipped), `images[1]` = right/background              |
+| Using without a sized container                               | Add `w-full`, `w-[Npx]` or similar to control width                                  |
+
+---
+
+## FULL EXAMPLE
+
+```tsx
+import { Diff } from 'solid-tom-ui';
+
+// Image comparison
+<Diff
+  images={[
+    <img alt="sharp" src="/images/sharp.webp" />,
+    <img alt="blurred" src="/images/blurred.webp" />,
+  ]}
+/>
+
+// Image vs label panel, square aspect
+<Diff
+  class="aspect-square w-full max-w-lg"
+  images={[
+    <img alt="photo" src="/images/photo.webp" />,
+    <div class="bg-neutral text-neutral-content grid place-content-center text-5xl font-black">
+      Solid UI
+    </div>,
+  ]}
+/>
+```
+
+> **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/divider.skill.md.txt

@@ -0,0 +1,151 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Divider } from 'solid-tom-ui';`
+- **Export**: `Divider` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Flexible visual separator — renders a plain line or a line with centered content (text, icons, badges); supports horizontal and vertical orientations
+
+## Props
+
+| Prop          | Type                                          | Default        | Description                                                                 |
+| ------------- | --------------------------------------------- | -------------- | --------------------------------------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'`                 | `'horizontal'` | Direction of the dividing line                                              |
+| `variant`     | `'solid' \| 'dashed' \| 'dotted'`            | `'solid'`      | Border style of the line                                                    |
+| `align`       | `'start' \| 'center' \| 'end'`               | `'center'`     | Position of children content along the line (only applies when children is present) |
+| `thickness`   | `1 \| 2 \| 3 \| 4`                          | `1`            | Line thickness in pixels                                                    |
+| `color`       | `BaseColorProps`                              | —              | Màu hệ thống cho đường kẻ và text content — dùng `--color` CSS variable    |
+| `class`       | `Partial<Record<'root' \| 'line' \| 'content', string>>` | — | Override classes for individual slots (see Class Slots below)   |
+| `children`    | `JSX.Element`                                 | —              | Content rendered between the two line segments                              |
+
+## Class Slots
+
+`Divider` exposes a unified `class` prop with three named slots:
+
+| Slot      | Element                                      | When available     |
+| --------- | -------------------------------------------- | ------------------ |
+| `root`    | `<hr>` (plain) or `<div>` (with children)   | Always             |
+| `line`    | Both leading and trailing line segments      | Only with children |
+| `content` | `<span>` wrapping children content          | Only with children |
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `dv01`, `dv02`) per project convention.
+
+## Render Behavior
+
+The component has two distinct render paths:
+
+- **No children** → renders a single `<hr>` element (plain line, zero markup overhead).
+- **With children** → renders a `<div>` containing a leading line, a content `<span>`, and a trailing line. The `align` prop controls how flex space is distributed between the two segments.
+
+## Basic Usage
+
+```tsx
+// Plain horizontal line
+<Divider />
+
+// Dashed / dotted
+<Divider variant="dashed" />
+<Divider variant="dotted" />
+
+// With label
+<Divider>OR</Divider>
+<Divider>Section Title</Divider>
+```
+
+## Alignment
+
+```tsx
+<Divider align="start">Left-aligned label</Divider>
+<Divider align="center">Center (default)</Divider>
+<Divider align="end">Right-aligned label</Divider>
+```
+
+## Thickness
+
+```tsx
+<Divider thickness={1}>1px (default)</Divider>
+<Divider thickness={2}>2px</Divider>
+<Divider thickness={3}>3px</Divider>
+<Divider thickness={4}>4px</Divider>
+```
+
+## Custom Line Color
+
+Use `class={{ line: '...' }}` to override the line color. This class is applied to **both** line segments.
+
+```tsx
+<Divider class={{ line: 'border-primary/50' }}>Primary</Divider>
+<Divider class={{ line: 'border-error/60' }} variant="dotted">Error</Divider>
+<Divider class={{ line: 'border-amber-400/60' }} thickness={2}>Amber</Divider>
+```
+
+## Custom Children (Icons, Badges)
+
+Any JSX can be passed as children:
+
+```tsx
+// Badge
+<Divider class={{ line: 'border-primary/40' }}>
+  <span class="bg-primary/10 text-primary rounded-full px-3 py-0.5 text-xs font-semibold">
+    New Section
+  </span>
+</Divider>
+
+// Icon + text
+<Divider class={{ line: 'border-success/40' }} variant="dashed">
+  <span class="text-success flex items-center gap-1.5 text-sm font-medium">
+    <CheckIcon class="h-3.5 w-3.5" />
+    Completed
+  </span>
+</Divider>
+```
+
+## Vertical Divider
+
+Use `orientation="vertical"` to create a vertical separator inside a flex row. The parent **must** use `items-stretch` (or set an explicit height) for the line to fill the available space.
+
+```tsx
+// Plain vertical line between items
+<div class="flex items-stretch gap-4">
+  <span>Left</span>
+  <Divider orientation="vertical" />
+  <span>Right</span>
+</div>
+
+// Vertical with label (parent needs an explicit height)
+<div class="flex h-32 items-stretch gap-4">
+  <span class="flex items-center">Panel A</span>
+  <Divider orientation="vertical" variant="dashed">OR</Divider>
+  <span class="flex items-center">Panel B</span>
+</div>
+
+// Colored vertical line
+<Divider orientation="vertical" class={{ line: 'border-primary/40' }} />
+```
+
+## Real-world Example — Login Form
+
+```tsx
+<div class="space-y-4">
+  <button class="btn btn-primary w-full">Continue with Google</button>
+  <button class="btn btn-neutral btn-outline w-full">Continue with GitHub</button>
+  <Divider>OR</Divider>
+  <input class="input input-bordered w-full" placeholder="Email address" />
+  <button class="btn btn-primary w-full">Sign in</button>
+</div>
+```
+
+## Accessibility
+
+- Both render paths emit `role="separator"` and `aria-orientation` matching the `orientation` prop.
+- Content inside `children` is wrapped in a `<span>` with `select-none` to prevent accidental text selection of decorative labels.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Using `class="border-primary"` as string | `class` is now a slot object — use `class={{ root: '...' }}` |
+| Coloring lines without effect | Use `class={{ line: 'border-primary/50' }}`, not `class={{ root: '...' }}` |
+| Vertical divider not visible | Ensure parent has `items-stretch` or a fixed height |
+| `align` has no effect | `align` only works when `children` is provided |
+| `line` / `content` slots not applying | These slots only apply when `children` is present |
+
+> **Unique IDs**: if this component needs to generate HTML `id` attributes, always use `createUniqueId()` from `solid-js` — never `Math.random()` or `Date.now()`.