solid-tom-ui 1.0.8 → 1.0.10

package/dist/skill/text-rotate.skill.md.txt

@@ -0,0 +1,186 @@
+## COMPONENT IDENTITY
+- **Import**: `import { TextRotate } from 'solid-tom-ui';`
+- **Export**: `TextRotate` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Pure-CSS animated text rotator — cycles through words/JSX elements driven by CSS `linear()` easing; zero JS timers; hover pauses animation
+
+## Props
+
+| Prop    | Type                                | Default | Description                                                                                                         |
+| ------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `items` | `(string \| (() => JSX.Element))[]` | —       | **Required.** List of text strings or render functions. Min: 2, Max: **6**                                          |
+| `class` | `{ root?: string; item?: string }`  | —       | Class overrides. `root` targets the outer `<span>`; `item` targets each string `<span>` (not render-function items) |
+
+## Class Slots
+
+`TextRotate` uses a slot object `{ root?, item? }` (equivalent to `Partial<Record<'root' | 'item', string>>`):
+- `root` — outer `<span class="text-rotate ...">` wrapper
+- `item` — each string item's inner `<span>` (not applied to render-function items)
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `tr01`, `tr02`) per project convention.
+
+### Item types
+
+Each element in `items` can be:
+
+- **`string`** — wrapped in `<span class={class.item}>`. Applies `class.item` if provided.
+- **`() => JSX.Element`** — called directly and rendered as-is. `class.item` is **not** applied to render-function items; style them inside the function itself.
+
+## Hard Limits
+
+| Condition                     | Behavior                                  |
+| ----------------------------- | ----------------------------------------- |
+| `items` is empty or undefined | Returns `<>` (empty), logs `console.warn` |
+| `items.length > 6`            | Returns `<>` (empty), logs `console.warn` |
+
+Always pass **2–6 items**.
+
+## Usage Examples
+
+### Basic — strings
+
+```tsx
+<p class="text-2xl font-bold">
+  I{' '}
+  <TextRotate
+    items={['love', 'enjoy', 'build with']}
+    class={{ root: 'text-rotate text-primary' }}
+  />{' '}
+  SolidJS
+</p>
+```
+
+### Inline within text
+
+`TextRotate` renders as an inline `<span>` — use it freely inside a sentence:
+
+```tsx
+<h1 class="text-4xl font-bold">
+  Build{' '}
+  <TextRotate items={['faster', 'better', 'smarter']} class={{ root: 'text-rotate text-accent' }} />{' '}
+  with SolidJS
+</h1>
+```
+
+### Render functions — arbitrary JSX
+
+When items need custom styling, badges, icons, or complex markup, use render functions:
+
+```tsx
+<TextRotate
+  items={[
+    () => <span class="badge badge-success font-bold">Online ✅</span>,
+    () => <span class="badge badge-error font-bold">Offline 🔴</span>,
+    () => <span class="badge badge-warning font-bold">Away 🟡</span>,
+  ]}
+/>
+```
+
+### Mixed strings and render functions
+
+```tsx
+<TextRotate
+  items={[
+    'Vite ⚡',
+    () => <span class="text-success font-mono">TypeScript</span>,
+    'Tailwind 🎨',
+    () => <span class="text-secondary italic">DaisyUI</span>,
+  ]}
+  class={{ root: 'text-rotate' }}
+/>
+```
+
+### Custom item class (strings only)
+
+`class.item` applies to the wrapping `<span>` of each **string** item:
+
+```tsx
+<TextRotate
+  items={['Creative', 'Efficient', 'Simple']}
+  class={{
+    root: 'text-rotate text-info',
+    item: 'font-mono uppercase',
+  }}
+/>
+```
+
+### Controlling animation speed
+
+The animation duration is driven by the `--duration` CSS custom property, which reads from Tailwind's `--tw-duration`. Override it with Tailwind's `duration-*` utility on the `root` element:
+
+```tsx
+{
+  /* Slow: 20s per full cycle */
+}
+<TextRotate items={['fast', 'slow', 'smooth']} class={{ root: 'text-rotate duration-20000' }} />;
+
+{
+  /* Fast: 4s per full cycle */
+}
+<TextRotate items={['fast', 'slow', 'smooth']} class={{ root: 'text-rotate duration-4000ms' }} />;
+```
+
+Default duration when not set: `10s`.
+
+### Hero heading
+
+```tsx
+<h1 class="text-5xl font-extrabold">
+  We build{' '}
+  <TextRotate
+    items={[
+      () => <span class="text-primary">faster</span>,
+      () => <span class="text-secondary">better</span>,
+      () => <span class="text-accent">smarter</span>,
+    ]}
+  />{' '}
+  products
+</h1>
+```
+
+## How the Animation Works
+
+The CSS class `text-rotate` (from `text-rotate.daisy.css`) does the following:
+
+1. **Container** (`<span class="text-rotate">`):
+   - `display: inline-block; height: 1lh; overflow: hidden` — crops to exactly one line-height.
+   - `vertical-align: bottom` — aligns cleanly inside surrounding text.
+
+2. **Inner grid** (the inner `<span>` wrapper):
+   - `display: grid; height: calc(N * 100%)` — stacks all `N` items vertically.
+   - Each item gets `align-content: baseline` and `clip-path: inset(0.5px 0 0.5px 0)` to clip half-pixels between items.
+
+3. **Animation**:
+   - CSS `:has(*:nth-child(N))` selectors auto-detect item count (2–6) and apply the matching `rotator` keyframe.
+   - The `linear()` easing function creates discrete hold phases at each step position, then snaps to the next — giving the appearance of a pause-then-flip rather than a smooth scroll.
+   - A single `animation: rotator 10s linear(...) infinite` drives the whole thing.
+
+4. **Hover pause**:
+   - `.text-rotate:hover > * { animation-play-state: paused }` — hover on the component pauses the cycle.
+
+## Rendered HTML Structure
+
+```html
+<span class="text-rotate [root class]">
+  <span>
+    <!-- inner grid, height = N × 100% -->
+    <span class="[item class]">Item 1</span>
+    <!-- string item -->
+    <span class="[item class]">Item 2</span>
+    <!-- OR: raw JSX from render function, no wrapping span -->
+  </span>
+</span>
+```
+
+## Common Mistakes
+
+| Mistake                                                        | Fix                                                                                                                                                                      |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Passing `items.length > 6`                                     | Component silently returns empty — keep items ≤ 6                                                                                                                        |
+| Passing 0 or 1 items                                           | Minimum 2 items required                                                                                                                                                 |
+| Applying `class.item` expecting it to work on render functions | `class.item` only applies to string items. Style render-function items inline                                                                                            |
+| Forgetting `text-rotate` in `class.root`                       | The `text-rotate` CSS class is what enables the animation. Without it, items render stacked but don't animate. Pass `class={{ root: 'text-rotate ...' }}`                |
+| Expecting the component to accept `duration` as a prop         | Duration is CSS-driven: add `duration-[Xms]` Tailwind utility to `class.root`                                                                                            |
+| Using `TextRotate` outside inline text context                 | It renders as `inline-block` with `height: 1lh` — works in paragraph and heading text. Avoid placing it in a `flex` container row where `1lh` might resolve unexpectedly |
+
+> **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/timeline.skill.md.txt

@@ -0,0 +1,247 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Timeline } from 'solid-tom-ui';`
+- **Export**: `Timeline` (named export), `TimelineItem` (type export)
+- **Framework**: SolidJS
+- **Purpose**: Display a sequence of events, milestones, or process steps in chronological order — for history/audit trails, NOT a navigation wizard (use `Steps` for that)
+
+**Good fit:**
+- Order tracking (e-commerce shipment status)
+- Audit / activity log (newest-first with `reverse`)
+- Multi-level approval workflow
+- Project roadmap or release history
+
+---
+
+## Props Reference
+
+### `TimelineProps`
+
+| Prop          | Type                                | Default        | Description |
+|---------------|-------------------------------------|----------------|-------------|
+| `items`       | `TimelineItem[]`                    | `[]`           | Array of timeline items |
+| `color`       | `BaseColorProps`                    | `'primary'`    | Global color for the entire timeline |
+| `orientation` | `'vertical' \| 'horizontal'`        | `'vertical'`   | Layout direction |
+| `mode`        | `'start' \| 'end' \| 'alternate'`   | `'alternate'`  | Content position relative to the axis |
+| `reverse`     | `boolean`                           | `false`        | Reverse the display order (does NOT mutate the data array) |
+| `class`       | `TimelineClassSlots`                | —              | Per-slot class overrides |
+
+All other native `<div>` HTML attributes are forwarded to the root element.
+
+### `TimelineItem`
+
+| Prop        | Type                                              | Description |
+|-------------|---------------------------------------------------|-------------|
+| `title`     | `JSXElement`                                      | Short milestone label |
+| `content`   | `JSXElement`                                      | Detail text or description |
+| `timestamp` | `JSXElement`                                      | Date, time, or relative label |
+| `icon`      | `() => JSX.Element`                               | **Factory function** returning a custom icon (replaces default icon) |
+| `color`     | `BaseColorProps`                                  | Per-item color — overrides global `color` |
+| `status`    | `'pending' \| 'active' \| 'done' \| 'error'`      | Item status — drives default color and icon |
+| `loading`   | `boolean`                                         | Show a spinner instead of the icon |
+| `position`  | `'start' \| 'end'`                                | Override content side for this specific item |
+
+### Class Slots
+
+```ts
+class?: {
+  root?:        string;  // outermost wrapper div
+  item?:        string;  // each timeline row/column
+  dot?:         string;  // circular marker
+  connector?:   string;  // line connecting dots
+  label?:       string;  // column/row that holds content
+  content?:     string;  // inner content box
+  title?:       string;  // title text
+  description?: string;  // content/detail text
+  timestamp?:   string;  // timestamp text
+}
+```
+
+---
+
+## Color Priority
+
+Color is resolved per-item using this chain (first match wins):
+
+```
+item.color  →  STATUS_COLOR[item.status]  →  global props.color
+```
+
+Default status → color mapping:
+
+| Status    | Auto color  | Default icon  |
+|-----------|-------------|---------------|
+| `done`    | `success`   | Checkmark     |
+| `active`  | `primary`   | Empty dot + ring pulse |
+| `error`   | `error`     | Alert circle  |
+| `pending` | `neutral`   | Clock         |
+
+**Rule:** Only set `item.color` when you need to override the automatic status color.
+Redundant color props (e.g. `status="done" color="success"`) are harmless but noisy.
+
+---
+
+## Mode — Layout Behavior
+
+| Mode          | Vertical                          | Horizontal                      |
+|---------------|-----------------------------------|---------------------------------|
+| `'alternate'` | Content alternates left / right (default) | Content alternates top / bottom |
+| `'start'`     | All content on the **left**       | All content **above** the axis  |
+| `'end'`       | All content on the **right**      | All content **below** the axis  |
+
+**Decision guide:**
+- Use `mode="alternate"` for rich timelines with long descriptions (balanced layout).
+- Use `mode="end"` for compact audit logs or sidebar widgets (all content on one side).
+- Use `mode="start"` when you need a right-to-left reading order.
+
+Individual items can override `mode` via `position="start" | "end"` on the item itself.
+
+---
+
+## Common Patterns
+
+### Basic order tracking
+
+```tsx
+const items: TimelineItem[] = [
+  { title: 'Order placed',    status: 'done',    timestamp: '08:30' },
+  { title: 'Payment verified', status: 'done',   timestamp: '08:32' },
+  { title: 'Packing',         status: 'active',  loading: true },
+  { title: 'Shipped',         status: 'pending', timestamp: 'ETA 14:00' },
+  { title: 'Delivered',       status: 'pending' },
+];
+
+<Timeline items={items} color="primary" />
+```
+
+### Audit log — newest first
+
+```tsx
+<Timeline
+  items={auditLogs}
+  color="neutral"
+  orientation="vertical"
+  mode="end"
+  reverse
+  class={{ root: 'max-w-sm' }}
+/>
+```
+
+### Horizontal process steps
+
+```tsx
+<Timeline
+  items={steps}
+  orientation="horizontal"
+  mode="alternate"
+  color="success"
+  class={{ root: 'w-full' }}
+/>
+```
+
+### Custom icon per item
+
+```tsx
+import Truck from 'lucide-solid/icons/truck';
+
+// icon must be a factory function: () => JSX.Element
+const items: TimelineItem[] = [
+  { title: 'Shipped', status: 'done', icon: () => <Truck size={14} /> },
+];
+```
+
+### Per-item color
+
+```tsx
+const items: TimelineItem[] = [
+  { title: 'Success', status: 'done',  color: 'success' },
+  { title: 'Warning', status: 'error', color: 'warning' },
+  { title: 'Info',    status: 'active', color: 'info' },
+];
+<Timeline items={items} orientation="vertical" mode="end" />
+```
+
+### Force a specific item position (override `mode`)
+
+```tsx
+// mode="alternate" but item B is always on the right
+const items: TimelineItem[] = [
+  { title: 'A', status: 'done' },
+  { title: 'B (forced right)', status: 'done', position: 'end' },
+  { title: 'C', status: 'active' },
+];
+<Timeline items={items} mode="alternate" />
+```
+
+### Reactive loading state (SolidJS signal)
+
+```tsx
+const [isProcessing, setIsProcessing] = createSignal(false);
+
+const items = (): TimelineItem[] => [
+  { title: 'Step 1', status: 'done' },
+  {
+    title: 'Step 2',
+    status: isProcessing() ? 'active' : 'done',
+    loading: isProcessing(),
+    content: isProcessing() ? 'Processing…' : 'Completed',
+  },
+  { title: 'Step 3', status: 'pending' },
+];
+
+<Timeline items={items()} color="primary" mode="end" />
+```
+
+### Style slot overrides
+
+```tsx
+<Timeline
+  items={items}
+  color="accent"
+  mode="end"
+  class={{
+    root: 'bg-base-200 rounded-2xl p-5 max-w-sm',
+    title: 'text-base font-semibold',
+    description: 'italic text-sm',
+    timestamp: 'font-mono text-xs',
+  }}
+/>
+```
+
+---
+
+## Gotchas & Constraints
+
+### `icon` must be a factory function
+```tsx
+// WRONG — JSX evaluated immediately, not reactive
+icon: <Truck size={14} />
+
+// CORRECT — factory function
+icon: () => <Truck size={14} />
+```
+
+### `loading` overrides `icon`
+When `loading={true}`, the custom icon is hidden and replaced by a spinner.
+The icon reappears automatically once `loading` is set back to `false`.
+
+### Connector color is global
+The connector line uses the global `--tl-color` CSS variable (set by the root `color` prop).
+Per-item connector color is not supported out of the box — override via `class.connector`
+and a CSS custom property if needed.
+
+### `reverse` does not mutate data
+`reverse={true}` creates a reversed copy internally. The original `items` array is
+never modified. Do not pre-reverse your data array and also pass `reverse` — that
+would double-reverse and show original order.
+
+### Horizontal layout — item count limit
+Each item takes `flex: 1` of the container width. Keep horizontal timelines to **≤ 6 items**
+to prevent content from becoming too narrow to read.
+
+### `mode="start"` vertical — right column collapses
+In `mode="start"`, the right column has `width: 0`. Any content accidentally rendered
+there (e.g. via a wrong `position` override) will be clipped and invisible.
+
+### `title`, `content`, `timestamp` accept `JSXElement`
+All three fields accept any JSX, not just strings. You can embed badges, icons,
+or interactive elements — but keep them lightweight since they render once per item.