solid-tom-ui 1.0.8 → 1.0.11

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

@@ -0,0 +1,136 @@
+## COMPONENT IDENTITY
+- **Import**: `import { QrCode } from 'solid-tom-ui';`
+- **Export**: `QrCode` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Renders a QR code onto an HTML `<canvas>` using the `qrcode` library; supports custom colors, logo overlay, and four status overlays (active, loading, expired, scanned)
+
+## When to use
+
+- Sharing URLs or text as a scannable QR code
+- Payment or authentication flows that need status feedback (loading, expired, scanned)
+- Branded QR codes with a center logo
+
+---
+
+## Prop Reference
+
+| Prop          | Type                                    | Default        | Description                                              |
+|---------------|-----------------------------------------|----------------|----------------------------------------------------------|
+| `value`       | `string`                                | —              | **Required.** Text / URL to encode.                      |
+| `size`        | `number`                                | `160`          | Canvas size in px (square).                              |
+| `color`       | `string` (hex)                          | `'#000000'`    | Foreground dot color.                                    |
+| `bgColor`     | `string` (hex)                          | `'#ffffff'`    | Background fill color.                                   |
+| `errorLevel`  | `'L' \| 'M' \| 'Q' \| 'H'`            | `'M'`          | Error correction level. Use `'H'` when adding a logo.   |
+| `logo`        | `QrCodeLogo`                            | —              | Optional center logo config (see below).                 |
+| `status`      | `'active' \| 'loading' \| 'expired' \| 'scanned'` | `'active'` | Controls overlay state.                     |
+| `expiredText` | `string`                                | `'QR code expired'` | Text shown in the expired overlay.               |
+| `onRefresh`   | `() => void`                            | —              | Called when user clicks the refresh button (expired).    |
+| `accentColor` | `BaseColorProps`                        | `'primary'`    | Color of the loading / expired overlay icon + text.      |
+| `class`       | `Partial<Record<SlotName, string>>`     | —              | Per-slot class overrides (see Slots below).              |
+
+### QrCodeLogo
+
+```ts
+interface QrCodeLogo {
+  src: string;         // Image URL
+  width?: number;      // Logo width in px (default: 20% of size)
+  height?: number;     // Logo height in px (default: same as width)
+  padding?: number;    // Background padding (default: 4)
+  background?: string; // Background color (default: '#ffffff')
+  borderRadius?: number; // Corner radius (default: 4)
+}
+```
+
+### Slots (`class` prop)
+
+| Slot           | Element                          |
+|----------------|----------------------------------|
+| `root`         | Outer wrapper `<div>`            |
+| `canvas`       | `<canvas>` element               |
+| `overlay`      | Status overlay `<div>`           |
+| `overlayIcon`  | Icon / button inside overlay     |
+| `overlayText`  | Text label inside expired overlay|
+
+---
+
+## Usage Patterns
+
+### Basic
+
+```tsx
+<QrCode value="https://solidjs.com" />
+```
+
+### Custom size and colors
+
+```tsx
+<QrCode
+  value="https://example.com"
+  size={200}
+  color="#7c3aed"
+  bgColor="#ede9fe"
+/>
+```
+
+### With logo (always use errorLevel="H")
+
+```tsx
+<QrCode
+  value="https://example.com"
+  size={180}
+  errorLevel="H"
+  logo={{
+    src: '/logo.svg',
+    width: 36,
+    height: 36,
+    padding: 6,
+    borderRadius: 8,
+  }}
+/>
+```
+
+### Status: loading
+
+```tsx
+<QrCode value="https://example.com" status="loading" accentColor="info" />
+```
+
+### Status: expired with refresh handler
+
+```tsx
+const [status, setStatus] = createSignal<QrCodeStatus>('expired');
+
+<QrCode
+  value="https://example.com"
+  status={status()}
+  expiredText="Scan timed out"
+  onRefresh={() => {
+    setStatus('loading');
+    fetchNewQrValue().then(() => setStatus('active'));
+  }}
+/>
+```
+
+### Status: scanned
+
+```tsx
+<QrCode value="https://example.com" status="scanned" />
+```
+
+### Reactive value (re-renders automatically)
+
+```tsx
+const [url, setUrl] = createSignal('https://solidjs.com');
+
+<QrCode value={url()} size={160} />
+<input value={url()} onInput={e => setUrl(e.currentTarget.value)} />
+```
+
+---
+
+## Known Gotchas
+
+- **Logo requires `errorLevel="H"`** — lower levels don't have enough redundancy to recover from the obscured center modules.
+- **Cross-origin logos** — ensure the logo image server sends `Access-Control-Allow-Origin` headers; otherwise the canvas `drawImage` call will taint the canvas and throw a security error.
+- **Empty value** — pass `' '` (a space) instead of `''` to avoid a qrcode library error when the value is empty.
+- **Canvas pixel density** — the canvas renders at 1× DPR by default. For retina displays you can scale `size` up and use CSS to constrain the rendered size.

package/dist/skill/rating.skill.md.txt

@@ -0,0 +1,167 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Rating } from 'solid-tom-ui';`
+- **Export**: `Rating` (named export), `RatingProps`, `RatingSize`, `RatingMask` (type exports)
+- **Framework**: SolidJS
+- **Purpose**: Star/heart rating component built on DaisyUI's `mask` utility; supports controlled and uncontrolled modes, half-star steps, multiple shapes, and read-only display
+
+## Props
+
+| Prop           | Type                              | Default      | Description                                                              |
+| -------------- | --------------------------------- | ------------ | ------------------------------------------------------------------------ |
+| `value`        | `number`                          | —            | Controlled value. When set, component is in controlled mode              |
+| `defaultValue` | `number`                          | —            | Initial value for uncontrolled mode                                      |
+| `count`        | `number`                          | `5`          | Total number of items                                                    |
+| `color`        | `BaseColorProps \| string`        | *(per mask)* | Item color. Accepts a `BaseColorProps` token or a Tailwind `bg-*` class  |
+| `size`         | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of each item                                               |
+| `mask`         | `'star' \| 'star-2' \| 'heart'`  | `'star-2'`   | Shape of each item                                                       |
+| `readOnly`     | `boolean`                         | `false`      | Disables interaction; renders `<div>` elements instead of `<input>`      |
+| `half`         | `boolean`                         | `false`      | Enables half-step increments (0.5, 1.0, 1.5 …)                          |
+| `allowClear`   | `boolean`                         | `true`       | Adds a hidden reset input; clicking the selected item resets to 0        |
+| `gap`          | `boolean`                         | *(per mask)* | Adds `gap-1` between items. Defaults to `true` for `heart`, `false` for stars |
+| `onChange`     | `(value: number) => void`         | —            | Called when the user selects a value                                     |
+| `class`        | `string`                          | —            | Extra class on the wrapper `<div>`                                       |
+| `ariaLabel`    | `string`                          | —            | Prefix for each item's `aria-label` (e.g. `"Product rating"` → `"Product rating 3 star"`) |
+
+All other `HTMLDivElement` attributes are forwarded to the wrapper (except `onChange`, which is intercepted).
+
+## Class Slots
+
+`Rating` is a single-element component — `class` appends to the root wrapper `<div>`. No named sub-element slots.
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `rt01`, `rt02`) per project convention.
+
+> **Unique IDs**: each `Rating` instance generates a unique `name` attribute for its radio inputs using `createUniqueId()` from `solid-js` — multiple instances on the same page won't interfere.
+
+## Controlled vs Uncontrolled
+
+```tsx
+// Uncontrolled — component manages its own state
+<Rating defaultValue={3} />
+
+// Controlled — you manage state
+const [value, setValue] = createSignal(3);
+<Rating value={value()} onChange={setValue} />
+```
+
+When `value` is provided, the internal signal syncs to it via `createEffect`. When `value` is `undefined`, the component is uncontrolled.
+
+## Default Colors per Mask
+
+When `color` is not specified, each mask has a built-in default color:
+
+| Mask      | Default color      |
+| --------- | ------------------ |
+| `star`    | `bg-yellow-400`    |
+| `star-2`  | `bg-orange-400`    |
+| `heart`   | `bg-red-400`       |
+
+## Examples
+
+### Basic (uncontrolled)
+
+```tsx
+<Rating defaultValue={3} />
+<Rating defaultValue={4} mask="star" />
+<Rating defaultValue={2} mask="heart" />
+```
+
+### Custom count
+
+```tsx
+<Rating count={3} defaultValue={2} />
+<Rating count={7} defaultValue={4} />
+<Rating count={10} defaultValue={6} />
+```
+
+### Sizes
+
+```tsx
+<Rating size="xs" defaultValue={3} />
+<Rating size="sm" defaultValue={3} />
+<Rating size="md" defaultValue={3} />   {/* default */}
+<Rating size="lg" defaultValue={3} />
+<Rating size="xl" defaultValue={3} />
+```
+
+### Custom color
+
+`color` accepts either a `BaseColorProps` token or a Tailwind `bg-*` class:
+
+```tsx
+{/* Tailwind color class */}
+<Rating color="bg-orange-400" defaultValue={4} />
+<Rating color="bg-blue-400" defaultValue={4} />
+
+{/* DaisyUI token */}
+<Rating color="primary" defaultValue={4} />
+<Rating color="success" defaultValue={4} />
+<Rating color="error" defaultValue={4} />
+```
+
+### Half-star mode
+
+When `half={true}`, values step by 0.5. Each item is split into two halves.
+
+```tsx
+<Rating half defaultValue={2.5} color="bg-orange-400" />
+<Rating half defaultValue={3.5} color="bg-yellow-400" size="lg" />
+```
+
+### Read-only
+
+Read-only renders `<div>` elements instead of `<input>` radio buttons — no interactivity, no tab stops.
+
+```tsx
+<Rating readOnly value={3} />
+<Rating readOnly value={4.5} half color="bg-orange-400" size="lg" />
+```
+
+### Allow clear (reset to 0)
+
+When `allowClear={true}` (default), a hidden radio at value 0 is inserted. Re-clicking the currently selected star resets the rating to 0.
+
+```tsx
+<Rating allowClear defaultValue={3} />       {/* can reset */}
+<Rating allowClear={false} defaultValue={3} /> {/* cannot reset */}
+```
+
+### Gap between items
+
+`gap` defaults to `true` for `heart`, `false` for `star`/`star-2`. Override explicitly:
+
+```tsx
+<Rating mask="heart" gap={false} defaultValue={3} />  {/* no gap */}
+<Rating mask="star-2" gap={true} defaultValue={3} />  {/* force gap */}
+```
+
+### Controlled with signal
+
+```tsx
+const [rating, setRating] = createSignal(3);
+
+<Rating value={rating()} onChange={setRating} color="bg-yellow-400" size="lg" />
+<p>Current: {rating()}</p>
+```
+
+## Render Behavior
+
+- **Interactive** (`readOnly=false`): renders `<input type="radio">` elements inside a `<div class="rating ...">`. Each input has `name` scoped to the instance via an auto-incrementing UID.
+- **Read-only** (`readOnly=true`): renders `<div class="mask ...">` elements. No form inputs, no keyboard interaction.
+- **`allowClear`**: inserts an extra hidden `<input class="rating-hidden">` as the first radio at value 0.
+
+## Accessibility
+
+- Each interactive input gets an `aria-label` like `"3 star"` or `"2.5 stars"`.
+- Provide `ariaLabel` to prefix all labels: `ariaLabel="Product rating"` → `"Product rating 3 star"`.
+- Read-only items use `aria-current="true"` on the active item.
+- The component renders as a radio group with a unique `name` per instance.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Passing a Tailwind color name like `"orange-400"` to `color` | Pass the full class: `color="bg-orange-400"` |
+| Expecting `onChange` to fire in read-only mode | `readOnly` silently blocks all changes — remove `readOnly` |
+| Setting `half` but passing an integer `defaultValue` | Valid — integers work in half mode (e.g., `defaultValue={3}`) |
+| Controlled component not responding to `onChange` | Ensure you update the signal: `onChange={val => setValue(val)}` |
+| `allowClear` not resetting | Works only when re-clicking the already-selected star; `allowClear={false}` disables it |

package/dist/skill/select-zone.skill.md.txt

@@ -0,0 +1,93 @@
+## COMPONENT IDENTITY
+- **Import**: `import { SelectZone, SelectZoneItem } from 'solid-tom-ui';`
+- **Exports**: `SelectZone` (container), `SelectZoneItem` (item wrapper)
+- **Framework**: SolidJS
+- **Purpose**: Rubber band selection — drag to select multiple items simultaneously, like Notion/File Explorer
+
+## Features
+
+- Selection rectangle appears on drag (≥ 4px), disappears on release
+- Supports all 4 drag directions (decreasing x/y included)
+- Auto-scroll when mouse reaches viewport edge; speed scales with distance
+- Hold Shift/Ctrl to add to existing selection without resetting
+- Single click on empty area → deselect all
+- Elements with `data-no-select` or `input/button/a` do not trigger drag
+
+## API
+
+### `<SelectZone>`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onSelect` | `(keys: Set<string>) => void` | — | Callback when selection changes |
+| `additive` | `boolean` | `true` | Support Shift/Ctrl to add to selection |
+| `scrollThreshold` | `number` | `40` | Distance from viewport edge (px) to activate auto-scroll |
+| `scrollSpeed` | `number` | `12` | Max scroll speed (px/frame) |
+| `disabled` | `boolean` | `false` | Disable SelectZone |
+| `class` | `{ root?, overlay? }` | — | Override classes per slot |
+
+### `<SelectZoneItem>`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `itemKey` | `string` | **Required** — unique key to track the item |
+| `children` | `(selected: () => boolean) => JSX.Element` | Render prop receiving `isSelected` accessor |
+| `class` | `string` | Extra classes on the wrapper div |
+
+## Basic usage
+
+```tsx
+import { SelectZone, SelectZoneItem } from 'solid-tom-ui';
+
+const items = ['a', 'b', 'c', 'd'];
+
+const MyComponent = () => {
+  const [selected, setSelected] = createSignal(new Set<string>());
+
+  return (
+    <SelectZone onSelect={setSelected}>
+      <div class="grid grid-cols-4 gap-2">
+        <For each={items}>
+          {item => (
+            <SelectZoneItem itemKey={item}>
+              {isSelected => (
+                <div class={isSelected() ? 'bg-primary/20' : 'bg-base-100'}>
+                  {item}
+                </div>
+              )}
+            </SelectZoneItem>
+          )}
+        </For>
+      </div>
+    </SelectZone>
+  );
+};
+```
+
+## Excluding elements from drag
+
+Add `data-no-select` to elements that should not trigger drag:
+
+```tsx
+<button data-no-select onClick={clearAll}>Deselect all</button>
+```
+
+## Override overlay style
+
+```tsx
+<SelectZone
+  class={{
+    root: 'p-4 border rounded-xl',
+    overlay: 'bg-blue-500/20 border-blue-500',
+  }}
+>
+  ...
+</SelectZone>
+```
+
+## Technical notes
+
+- Overlay uses `position: fixed` so it works correctly even when the container scrolls
+- AABB intersection detection: O(n) — suitable for up to a few thousand items
+- `startX/Y` is adjusted for scroll amount so the overlay stays accurate during auto-scroll
+- `SelectZoneItem` wrapper div has `data-select-key` to distinguish item clicks from empty-area clicks