solid-tom-ui 1.0.8 → 1.0.10

package/dist/skill/doc.skill.md.txt

@@ -0,0 +1,191 @@
+## COMPONENT IDENTITY
+- **Import**: `import { CodePreview } from '@/components/doc/CodePreview';`
+- **Export**: `CodePreview` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Internal documentation UI — the `doc` folder builds the library's documentation pages; NOT general-purpose UI components; NOT exported from `solid-tom-ui`
+
+## PURPOSE
+Renders a tabbed panel with two views:
+1. **Preview tab**: renders the given SolidJS component visually.
+2. **Code tab**: shows syntax-highlighted TypeScript/TSX source code with a copy button.
+
+## TYPE SIGNATURE
+```typescript
+import { CodePreview } from 'solid-tom-ui';
+import { Component } from 'solid-js';
+
+<CodePreview
+  preview={Component<any>}      // REQUIRED: SolidJS component to render as preview
+  code={string}                 // REQUIRED: source code string to display (raw TSX/TS)
+  title?={string}               // optional title (currently not rendered in UI)
+  language?={string}            // highlight.js language ID; default: 'typescript'
+  classNames?={{
+    previewBlock?: string;      // extra class on the preview container div
+  }}
+/>
+```
+
+## USAGE PATTERN
+```tsx
+import { CodePreview } from '@/components/doc/CodePreview';
+import { MyExampleComponent } from './my-component.example';
+
+const exampleCode = `
+import { MyComponent } from '@/components/my-component';
+
+const Example = () => (
+  <MyComponent color="primary" size="md">
+    Hello
+  </MyComponent>
+);
+`.trim();
+
+<CodePreview
+  preview={MyExampleComponent}
+  code={exampleCode}
+/>
+```
+
+## With custom preview container class
+```tsx
+<CodePreview
+  preview={DarkBgExample}
+  code={darkCode}
+  classNames={{ previewBlock: 'bg-gray-900 min-h-48' }}
+/>
+```
+
+## CONSTRAINTS
+- `preview` must be a **component reference** (not rendered JSX). It is rendered via `<Dynamic component={props.preview} />`.
+- `code` is formatted with a simple indentation normalizer (not a full prettier formatter). Pass clean, consistently-indented code strings.
+- The copy button uses `navigator.clipboard.writeText` — only works in HTTPS or localhost contexts.
+- `title` prop exists in the type but is not rendered in the current implementation.
+- Syntax highlighting only works for languages registered with `hljs`. Currently only `typescript` is registered.
+
+### ANTI-PATTERNS
+```tsx
+// ❌ Passing rendered JSX as preview
+<CodePreview preview={<MyComponent />} code={...} />  // Wrong
+// ✅ Pass component reference
+<CodePreview preview={MyComponent} code={...} />
+
+// ❌ Passing a different language without registering it with hljs
+<CodePreview preview={CssExample} code={cssCode} language="css" />
+// Only "typescript" is registered; other languages fall back to plain text
+```
+
+---
+
+## DocsNav
+
+### IDENTITY
+- **Import**: `@/components/doc/DocsNav`
+- **Export**: `DocsNav` (named export)
+- **Framework**: SolidJS + `@solidjs/router`
+
+### PURPOSE
+Sidebar navigation component for the documentation site. Groups doc entries by category and renders active-state links using `@solidjs/router`'s `<A>` component.
+
+### CURRENT STATUS
+> **⚠️ DocsNav currently renders an empty fragment (`<></>`)**. The component body is disabled (unreachable code after the early `return <></>`). It is a work-in-progress and not functional.
+
+## TYPE SIGNATURE
+```typescript
+import { DocsNav } from '@/components/doc/DocsNav';
+
+interface DocsNavProps {
+  docs?: DocInfo[];   // list of doc entries; falls back to global DOCS_TSX if omitted
+}
+
+<DocsNav docs?={DocInfo[]} />
+```
+
+---
+
+## TableOfContents
+
+### IDENTITY
+- **Import**: `@/components/doc/TableOfContents`
+- **Export**: `TableOfContents` (named export), `Heading` (exported interface)
+- **Framework**: SolidJS
+
+### PURPOSE
+Sticky right-side table of contents. Renders a list of heading anchors. Clicking a heading scrolls the nearest `<main>` container to that heading smoothly.
+
+## TYPE SIGNATURE
+```typescript
+import { TableOfContents, Heading } from '@/components/doc/TableOfContents';
+
+interface Heading {
+  id: string;      // DOM element ID to scroll to
+  text: string;    // display text
+  level: number;   // heading level (2 = h2, 3 = h3, etc.)
+}
+
+<TableOfContents
+  headings={Heading[]}   // REQUIRED: array of heading descriptors
+/>
+```
+
+### BEHAVIOR
+- Renders nothing when `headings` is empty (wrapped in `<Show when={props.headings.length > 0}>`).
+- Scroll target is found via `document.getElementById(heading.id)`.
+- Scrolls the closest `<main>` ancestor (with 80px top offset). Falls back to `scrollIntoView` if no `<main>` found.
+- `level === 2` → `font-medium text-gray-700` (h2-level, bold)
+- `level >= 3` → `ml-4 text-gray-600` (h3+, indented)
+
+## USAGE PATTERN
+```tsx
+import { TableOfContents, Heading } from '@/components/doc/TableOfContents';
+
+const headings: Heading[] = [
+  { id: 'installation', text: 'Installation', level: 2 },
+  { id: 'basic-usage', text: 'Basic Usage', level: 2 },
+  { id: 'variants', text: 'Variants', level: 3 },
+  { id: 'api', text: 'API Reference', level: 2 },
+];
+
+// Typically placed in a sticky right sidebar
+<aside class="w-64 shrink-0">
+  <TableOfContents headings={headings} />
+</aside>
+```
+
+### GENERATING HEADINGS FROM MARKDOWN
+When parsing markdown for headings, produce objects matching the `Heading` interface:
+```typescript
+// Example: parse h2 and h3 headings from markdown text
+const parseHeadings = (markdown: string): Heading[] => {
+  const lines = markdown.split('\n');
+  return lines
+    .filter(line => line.startsWith('## ') || line.startsWith('### '))
+    .map(line => {
+      const level = line.startsWith('### ') ? 3 : 2;
+      const text = line.replace(/^#{2,3}\s/, '');
+      const id = text.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '');
+      return { id, text, level };
+    });
+};
+```
+
+## CONSTRAINTS
+- Each heading's `id` must match an actual DOM element's `id` attribute in the page.
+- The scroll offset is hardcoded at 80px (to account for sticky headers).
+- Only works when rendered inside or near a `<main>` element ancestor.
+
+---
+
+## DECISION RULES — Which doc component to use?
+
+| Need | Component |
+|------|-----------|
+| Show a live preview + source code for a component example | `CodePreview` |
+| Sidebar navigation list of doc pages | `DocsNav` (currently disabled/WIP) |
+| Right-side table of contents for a doc page | `TableOfContents` |
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `dc01`, `dc02`) 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/drawer.skill.md.txt

@@ -0,0 +1,157 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Drawer } from 'solid-tom-ui';`
+- **Exports**: `Drawer` (named export), `DrawerType`, `DrawerPlacement` (type exports)
+- **Framework**: SolidJS
+- **Purpose**: Slide-in panel (drawer) from any edge (left/right/top/bottom) with backdrop overlay, optional blur, close button, and header/footer slots
+
+---
+
+## PROP REFERENCE (`DrawerType`)
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | Controls visibility. Required. |
+| `onClose` | `() => void` | `() => {}` | Callback fired on close (overlay click, X button). Must set `open` to `false`. |
+| `placement` | `DrawerPlacement` | `'left'` | Which side the panel slides in from. |
+| `width` | `string` | — | Panel width for `left`/`right` placements. Any CSS value (`'320px'`, `'40vw'`). |
+| `height` | `string` | — | Panel height for `top`/`bottom` placements. Any CSS value (`'300px'`, `'50vh'`). |
+| `mask` | `boolean` | `true` | Show backdrop overlay. |
+| `maskBlur` | `boolean` | `false` | Add `backdrop-blur` to overlay. |
+| `closable` | `boolean` | `true` | Show the X close button in the top-right corner. |
+| `closeOnOutsideClick` | `boolean` | `true` | Click overlay to close. |
+| `header` | `SolidComponent` | — | JSX rendered in the header slot (with bottom border). |
+| `body` | `SolidComponent` | — | JSX rendered in the scrollable body slot. |
+| `footer` | `SolidComponent` | — | JSX rendered in the footer slot (with top border). |
+| `preRender` | `boolean` | `false` | Always mount in DOM; hide with `display:none` when closed. |
+| `class` | `Partial<Record<'wrapper'\|'panel'\|'header'\|'body'\|'footer'\|'closeButton', string>>` | — | Override classes on specific elements. |
+
+### `DrawerPlacement` values
+
+```ts
+'left' | 'right' | 'top' | 'bottom'
+```
+
+---
+
+## USAGE PATTERNS
+
+### 1. Minimal
+
+```tsx
+const [open, setOpen] = createSignal(false);
+
+<Button onClick={() => setOpen(true)}>Open</Button>
+<Drawer
+  open={open()}
+  onClose={() => setOpen(false)}
+  body={() => <p>Drawer content</p>}
+/>
+```
+
+### 2. With header, body, footer
+
+```tsx
+<Drawer
+  open={open()}
+  onClose={() => setOpen(false)}
+  placement="right"
+  header={() => <span class="text-base font-semibold">Settings</span>}
+  body={() => <p>Body content here.</p>}
+  footer={() => (
+    <div class="flex justify-end gap-2">
+      <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button variant="solid" color="primary" onClick={handleSave}>Save</Button>
+    </div>
+  )}
+/>
+```
+
+### 3. Custom size
+
+```tsx
+// Horizontal drawer
+<Drawer open={open()} onClose={() => setOpen(false)} placement="left" width="480px" ... />
+
+// Vertical drawer
+<Drawer open={open()} onClose={() => setOpen(false)} placement="bottom" height="360px" ... />
+```
+
+### 4. No overlay
+
+```tsx
+<Drawer
+  open={open()}
+  onClose={() => setOpen(false)}
+  mask={false}
+  closeOnOutsideClick={false}
+  body={() => <p>Only closable via X button.</p>}
+/>
+```
+
+### 5. Blur overlay
+
+```tsx
+<Drawer
+  open={open()}
+  onClose={() => setOpen(false)}
+  maskBlur
+  body={() => <p>Background is blurred.</p>}
+/>
+```
+
+### 6. preRender — preserve state between open/close
+
+```tsx
+<Drawer
+  open={open()}
+  onClose={() => setOpen(false)}
+  preRender={true}
+  body={() => <ExpensiveForm />}
+/>
+```
+
+### 7. Custom class overrides
+
+```tsx
+<Drawer
+  open={open()}
+  onClose={() => setOpen(false)}
+  class={{ panel: 'rounded-r-2xl', header: 'bg-primary/5' }}
+  body={() => <div />}
+/>
+```
+
+---
+
+## BEHAVIORAL RULES
+
+- **Fully controlled**: parent must hold the `open` signal and update it in `onClose`.
+- **Portal rendering**: panel renders in `document.body` via `ZIndex` → unaffected by ancestor `overflow:hidden`.
+- **Scroll lock**: body scroll is blocked while drawer is open (via `ZIndex blockScroll`).
+- **Z-index**: uses `ZIndexType.MODAL` (base 1000) — same stacking group as Modal.
+- **Animation**: CSS `@keyframes` slide-in on mount. No close animation (panel unmounts on `open=false` when `preRender=false`).
+- **`preRender=false`** (default): component unmounts when closed → state resets on next open.
+- **`preRender=true`**: component stays mounted → state preserved; hidden via `display:none`.
+
+---
+
+## DO / DON'T
+
+**DO**
+- Always pair `open={signal()}` with `onClose={() => setSignal(false)}`.
+- Pass `body`, `header`, `footer` as functions `() => <JSX>` to defer evaluation.
+- Use `width` for left/right drawers and `height` for top/bottom drawers.
+- Import from barrel: `import { Drawer } from 'solid-tom-ui'`.
+
+**DON'T**
+- Don't leave `onClose` as a no-op — the drawer won't close reactively.
+- Don't use `ComponentDrawer` directly unless you need the raw unguarded component.
+- Don't set both `width` and `height` — only one applies based on `placement`.
+- Don't import `DrawerExample` in production — it's a demo-only component.
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `dr01`, `dr02`) 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/dropdown.skill.md.txt

@@ -0,0 +1,198 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Dropdown } from 'solid-tom-ui';`
+- **Export**: `Dropdown` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Dropdown that renders content into `document.body` via Portal; always visible above overflow-hidden containers; singleton behavior (only one open at a time)
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `triggerElement` | `SolidComponent` | — | Element rendered as the clickable trigger |
+| `open` | `boolean` | `undefined` | Controlled mode: pass `true`/`false` to manage state externally |
+| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Which side the content appears on |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Alignment along the cross axis |
+| `blockScroll` | `boolean` | `false` | Lock page scroll while dropdown is open |
+| `zIndex` | `number` | — | Override the automatic z-index |
+| `class.anchor` | `string` | — | Class on the content anchor wrapper |
+| `class.trigger` | `string` | — | Class on the trigger wrapper div |
+| `class.content` | `string` | — | Class on the content wrapper div |
+| `ref` | `HTMLDivElement \| ((el) => void)` | — | Ref to the trigger div |
+
+## Basic Usage
+
+```tsx
+<Dropdown triggerElement={<button class="btn btn-sm">Open</button>}>
+  <div class="bg-base-100 rounded-lg shadow-lg px-4 py-3 min-w-40">
+    <p>Dropdown content</p>
+  </div>
+</Dropdown>
+```
+
+### With position and alignment
+
+```tsx
+<Dropdown
+  position="top"
+  align="end"
+  triggerElement={<button class="btn btn-sm">Open ↑</button>}
+>
+  <div class="bg-base-100 rounded-lg shadow-lg px-4 py-3">
+    Top-end positioned
+  </div>
+</Dropdown>
+```
+
+### Controlled mode
+
+```tsx
+const [open, setOpen] = createSignal(false);
+
+<button class="btn btn-sm" onClick={() => setOpen(v => !v)}>Toggle</button>
+<Dropdown
+  open={open()}
+  triggerElement={<div class="border rounded px-3 py-1">Trigger</div>}
+>
+  <div class="bg-base-100 rounded-lg shadow-lg px-4 py-3">
+    <button class="btn btn-xs btn-ghost" onClick={() => setOpen(false)}>Close</button>
+  </div>
+</Dropdown>
+```
+
+### Inside `overflow-hidden` container
+
+```tsx
+// Portal mode escapes overflow-hidden — content is always visible
+<div class="overflow-hidden h-16 w-48 border rounded flex items-center justify-center">
+  <Dropdown triggerElement={<button class="btn btn-sm">Open</button>}>
+    <div class="bg-base-100 shadow-lg px-4 py-3">Visible!</div>
+  </Dropdown>
+</div>
+```
+
+### Scroll lock
+
+```tsx
+<Dropdown
+  blockScroll
+  triggerElement={<button class="btn btn-sm btn-warning">Open (scroll locked)</button>}
+>
+  <div class="bg-base-100 rounded-lg shadow-lg px-6 py-4">
+    Page scroll is locked while this is open.
+  </div>
+</Dropdown>
+```
+
+## Behavior Details
+
+### Singleton
+
+Only one dropdown can be open at a time. Opening a second dropdown automatically closes the first. This is enforced by the global `dropdownStore`.
+
+### Click outside to close
+
+A full-screen invisible backdrop (`nd-backdrop`) catches clicks outside the content.
+
+### Controlled vs uncontrolled
+
+- **Uncontrolled** (no `open` prop): the component manages its own open/close state.
+- **Controlled** (`open` prop provided): the component delegates state to the parent. The trigger click has no effect — the parent must update `open` manually. Controlled state is synced with `dropdownStore`.
+
+### Position tracking (`blockScroll={false}`)
+
+When open and `blockScroll` is false, the portal content anchor tracks the trigger element's position continuously via `element-tracker`. This ensures the dropdown stays aligned even when the page scrolls.
+
+When `blockScroll={true}`, tracking stops (the page cannot scroll anyway, so the position is stable).
+
+## Positioning System
+
+Content position is computed from `getBoundingClientRect()` of the trigger, stored in CSS variables on the anchor element:
+
+| Variable | Value |
+|----------|-------|
+| `--nd-t` | `trigger.top` |
+| `--nd-l` | `trigger.left` |
+| `--nd-w` | `trigger.width` |
+| `--nd-h` | `trigger.height` |
+
+`data-pos` and `data-align` attributes on `.nd-content-anchor` drive all position/alignment combinations via pure CSS. Gap between trigger and content is controlled by `--nd-gap` (default: `6px`).
+
+## Common Patterns
+
+### Menu list inside dropdown
+
+```tsx
+<Dropdown triggerElement={<button class="btn btn-sm">Menu</button>}>
+  <ul class="bg-base-100 rounded-lg shadow-lg overflow-hidden min-w-40">
+    <li>
+      <button class="w-full px-4 py-2 text-left text-sm hover:bg-base-200 transition-colors">
+        Edit
+      </button>
+    </li>
+    <li>
+      <button class="w-full px-4 py-2 text-left text-sm text-error hover:bg-error/10 transition-colors">
+        Delete
+      </button>
+    </li>
+  </ul>
+</Dropdown>
+```
+
+### Icon trigger (three-dot menu)
+
+```tsx
+import { MoreHorizontal } from 'lucide-solid';
+
+<Dropdown
+  align="end"
+  triggerElement={
+    <button class="btn btn-ghost btn-xs btn-square">
+      <MoreHorizontal size={16} />
+    </button>
+  }
+>
+  <ul class="bg-base-100 rounded-lg shadow-lg overflow-hidden min-w-36">
+    <li><button class="w-full px-4 py-2 text-left text-sm hover:bg-base-200">Rename</button></li>
+    <li><button class="w-full px-4 py-2 text-left text-sm hover:bg-base-200">Duplicate</button></li>
+    <li><button class="w-full px-4 py-2 text-left text-sm text-error hover:bg-error/10">Delete</button></li>
+  </ul>
+</Dropdown>
+```
+
+### Programmatic close from content
+
+Use controlled mode to close the dropdown from inside:
+
+```tsx
+const [open, setOpen] = createSignal(false);
+
+<Dropdown
+  open={open()}
+  triggerElement={
+    <button class="btn btn-sm" onClick={() => setOpen(true)}>Open</button>
+  }
+>
+  <div class="bg-base-100 rounded-lg shadow-lg px-4 py-3">
+    <button class="btn btn-xs" onClick={() => setOpen(false)}>Close me</button>
+  </div>
+</Dropdown>
+```
+
+## Styling Tips
+
+- **Content width**: Portal content has `min-width: max-content` by default. Use `min-w-*` Tailwind classes on the content div to enforce a minimum width.
+- **Custom gap**: Override `--nd-gap` on `.nd-content-anchor` via inline style or a custom CSS class.
+- **Animation origin**: Animation scale origin (`transform-origin`) is automatically set per position/alignment via `--nd-origin` CSS variable — no manual adjustment needed.
+
+## Gotchas
+
+1. **Singleton**: Only one dropdown can be open at a time — enforced by `dropdownStore`.
+2. **`class.content` vs content children**: `class.content` targets the `.nd-content` wrapper, not the children directly. Apply `rounded`, `shadow`, `bg-*` to the direct child element inside `<Dropdown>` for full visual control.
+
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `dp01`, `dp02`) 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()`.