solid-tom-ui 1.0.8 → 1.0.11

package/dist/skill/tooltip.skill.md.txt

@@ -0,0 +1,222 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Tooltip } from 'solid-tom-ui';`
+- **Export**: `Tooltip` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Tooltip component — DaisyUI + CVA styling engine; two render modes (default / portal) controlled by `type` prop
+
+---
+
+## TYPE SIGNATURE
+
+```ts
+// Unified entry point — render mode controlled by `type` prop
+type TooltipProps = TooltipDefaultProps | TooltipPortalProps;
+
+// Default mode (IO-based, no overflow clip)
+type TooltipDefaultProps = {
+  type?: 'default';        // omit or set 'default'
+  hidden?: boolean;
+  children: JSX.Element;
+  position?: 'top' | 'bottom' | 'left' | 'right'; // default: 'top'
+  color?: BaseColorProps;  // default: 'neutral'
+  zIndex?: number;
+  class?: {
+    root?: string;
+    content?: string;
+  };
+} & (WithContent | WithCustomContent);
+
+// Portal mode (event-delegation, escapes overflow:hidden)
+type TooltipPortalProps = {
+  type: 'portal';          // REQUIRED to activate portal mode
+  hidden?: boolean;
+  children: SolidComponent;
+  position?: 'top' | 'bottom' | 'left' | 'right'; // default: 'top'
+  color?: BaseColorProps;  // default: 'neutral'
+  zIndex?: number;
+  class?: {
+    root?: string;
+    content?: string;
+  };
+  /**
+   * `id` of the overflow:hidden parent container.
+   * Required when type='portal'.
+   */
+  containerId: string;
+} & (WithContent | WithCustomContent);
+
+// MUTUALLY EXCLUSIVE — use ONE of the two below:
+type WithContent = {
+  content: string;         // plain text tooltip
+  customContent?: never;
+};
+type WithCustomContent = {
+  content?: never;
+  customContent: JSX.Element; // arbitrary JSX tooltip body
+};
+```
+
+### CONSTRAINTS
+
+- `content` and `customContent` are mutually exclusive.
+- `containerId` is **required** when `type='portal'`. TypeScript will error if omitted.
+- `TooltipPortal` is still exported as a backward-compat alias for `<Tooltip type="portal" ...>`.
+
+---
+
+## PROP REFERENCE
+
+| Prop            | Type                                     | Default     | Description                                                                   |
+| --------------- | ---------------------------------------- | ----------- | ----------------------------------------------------------------------------- |
+| `type`          | `'default' \| 'portal'`                  | `'default'` | Render mode: IO-based (default) or event-delegation portal                    |
+| `children`      | `JSX.Element` / `SolidComponent`         | —           | **Required.** The element that triggers the tooltip on hover                  |
+| `content`       | `string`                                 | —           | Plain text shown in tooltip                                                   |
+| `customContent` | `JSX.Element`                            | —           | Arbitrary JSX rendered inside tooltip bubble                                  |
+| `position`      | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'`     | Direction tooltip appears relative to trigger                                 |
+| `color`         | `BaseColorProps`                         | `'neutral'` | DaisyUI color variant                                                         |
+| `hidden`        | `boolean`                                | `undefined` | When `true`, bypasses tooltip wrapper entirely — renders children only        |
+| `zIndex`        | `number`                                 | `undefined` | Override automatic z-index management                                         |
+| `containerId`   | `string`                                 | —           | **Required when `type='portal'`.** The `id` of the element causing clipping   |
+| `class.root`    | `string`                                 | `undefined` | Extra Tailwind classes on the outer wrapper div                               |
+| `class.content` | `string`                                 | `undefined` | Extra Tailwind classes on the tooltip bubble                                  |
+
+---
+
+## TYPE DECISION RULE
+
+> **Always default to `type='default'` (or omit the `type` prop entirely).**
+> Only switch to `type='portal'` when the tooltip is **clipped by `overflow:hidden`, `overflow:clip`, or `clip-path`** on a parent container.
+
+| Situation                                                              | Choice                                                                        |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Tooltip renders normally, not clipped                                  | `type='default'` _(default — no declaration needed)_                          |
+| Tooltip is inside a container with `overflow:hidden` / `overflow:clip` | `type='portal'` + `containerId` pointing to that specific container           |
+| Tooltip inside a scrollable table with hundreds of cells               | `type='portal'` + same `containerId` for all tooltips (the table's wrapper)   |
+| Not sure whether it will be clipped                                    | Try default first; switch to portal only if you observe the tooltip being cut |
+
+---
+
+## CHOOSING THE RIGHT `containerId`
+
+> **`containerId` must identify the specific element that is causing the tooltip to be hidden — not a global ancestor.**
+
+1. Find the element with `overflow:hidden` / `overflow:clip`.
+2. Assign that element an `id`.
+3. Pass that `id` as `containerId`.
+
+### What NOT to use as `containerId`
+
+| ❌ Avoid                                       | Why                                                         |
+| ---------------------------------------------- | ----------------------------------------------------------- |
+| `containerId="html-root"` (pointing to `<html>`) | Near-global listener — defeats all scoping               |
+| `containerId="root"` (app root div)             | Too broad — still covers the entire application            |
+
+---
+
+## USAGE PATTERNS
+
+### Pattern 1 — Plain text tooltip (most common)
+
+```tsx
+<Tooltip content="Save your work" position="top" color="primary">
+  <Button>Save</Button>
+</Tooltip>
+```
+
+### Pattern 2 — Custom JSX content
+
+```tsx
+<Tooltip
+  position="bottom"
+  color="info"
+  customContent={
+    <div class="bg-info text-info-content rounded-lg p-2">
+      <p class="font-bold">Title</p>
+      <p class="text-sm">Description text</p>
+    </div>
+  }
+>
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+### Pattern 3 — Conditionally hidden tooltip
+
+```tsx
+<Tooltip content="Only when permitted" hidden={!userHasPermission}>
+  <Button>Action</Button>
+</Tooltip>
+```
+
+### Pattern 4 — Portal mode (only when tooltip is clipped by overflow:hidden)
+
+```tsx
+<div id="my-overflow-box" style={{ overflow: 'hidden' }}>
+  <Tooltip type="portal" content="Escapes overflow!" containerId="my-overflow-box" position="top">
+    <Button>Hover me</Button>
+  </Tooltip>
+</div>
+```
+
+### Pattern 5 — Portal on many cells in a table (performance-optimized)
+
+```tsx
+// All tooltips sharing the same containerId use ONE pair of listeners
+<div id="my-table-container" class="max-h-64 overflow-auto">
+  <table>
+    <tbody>
+      <For each={rows}>
+        {row => (
+          <tr>
+            <td>
+              <Tooltip
+                type="portal"
+                content={row.label}
+                position="top"
+                color="primary"
+                containerId="my-table-container"
+              >
+                <span>{row.value}</span>
+              </Tooltip>
+            </td>
+          </tr>
+        )}
+      </For>
+    </tbody>
+  </table>
+</div>
+```
+
+---
+
+## BEHAVIOR NOTES FOR AGENTS
+
+1. **`hidden` prop short-circuits all tooltip logic** — when `hidden={true}`, renders `<>{children}</>` only.
+
+2. **`type='default'` uses IntersectionObserver** — a CSS sentinel (`too08`) inside the wrapper becomes visible on `:hover`, triggering the IO callback which appends the bubble to `document.body`. Zero JS event listeners on the trigger.
+
+3. **`type='portal'` uses event delegation** — internally uses a `WeakMap<Element, ContainerState>` keyed by the resolved container. Multiple tooltips with the same `containerId` share a single `mouseover`/`mouseout` listener pair.
+
+4. **`containerId` timing** — registration is deferred via `queueMicrotask` so it is safe even when the container is a parent in the same JSX tree.
+
+5. **`TooltipPortal` is a backward-compat alias** — `<TooltipPortal containerId="x" ...>` is equivalent to `<Tooltip type="portal" containerId="x" ...>`.
+
+---
+
+## COMMON MISTAKES TO AVOID
+
+| Mistake                                                      | Correct approach                                                           |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| Providing both `content` and `customContent`                 | Use only one — they are mutually exclusive                                 |
+| Using `type='portal'` as the default for every tooltip       | Only use it when the tooltip is actually clipped by overflow               |
+| Using `type='portal'` without `containerId`                  | TypeScript will error — always provide `containerId`                       |
+| Using `containerId="html-root"` or pointing to `<html>`      | Creates a near-global listener. Point to the specific overflow container   |
+| Using different `containerId` values in a loop               | All tooltips in the same container should share the same `containerId`     |
+
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `too01`, `too06`) per project convention.
+
+> **Unique IDs**: uses `createUniqueId()` from `solid-js` — never `Math.random()` or `Date.now()`.

package/dist/skill/tour.skill.md.txt

@@ -0,0 +1,156 @@
+## COMPONENT IDENTITY
+- **Import**: `import { createTour } from 'solid-tom-ui';`
+- **Export**: `createTour` (factory function)
+- **Framework**: SolidJS
+- **Purpose**: Step-by-step walkthrough — highlights elements with a spotlight overlay and shows a popup at each step; uses a factory pattern, NOT a JSX component
+
+## API: createTour()
+
+`Tour` is NOT declared as a regular JSX component. Instead, use `createTour()` which returns:
+- **`api`**: object with control methods
+- **`TourUI`**: component that must be mounted in JSX
+
+```tsx
+import { createTour } from 'solid-tom-ui';
+
+const MyPage = () => {
+  const [tour, TourUI] = createTour({
+    steps: [...],
+    onFinish: () => console.log('Done!'),
+  });
+
+  return (
+    <>
+      <TourUI />  {/* Must be mounted */}
+      <button onClick={() => tour.start()}>Start</button>
+    </>
+  );
+};
+```
+
+## TourProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `TourStep[]` | required | Array of step definitions |
+| `onFinish` | `() => void` | - | Callback when all steps are completed |
+| `onClose` | `(step: number) => void` | - | Callback when closed before finishing |
+| `onStepChange` | `(step: number) => void` | - | Callback on each step change |
+| `showClose` | `boolean` | `true` | Show the X close button |
+| `prevLabel` | `string` | `'Prev'` | Label for the Previous button |
+| `nextLabel` | `string` | `'Next'` | Label for the Next button |
+| `doneLabel` | `string` | `'Done'` | Label for the button on the last step |
+| `showProgress` | `boolean` | `true` | Show dot progress indicator |
+| `maskClosable` | `boolean` | `false` | Click overlay to close |
+| `class` | `Partial<Record<SlotName, string>>` | - | Override CSS per slot |
+
+## TourStep
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `target` | `string` | - | HTML `id` of the element to highlight |
+| `title` | `JSX.Element` | - | Popup title |
+| `content` | `JSX.Element` | - | Popup body content |
+| `footer` | `JSX.Element` | - | Custom footer (overrides Prev/Next buttons) |
+| `placement` | `TourPlacement` | `'bottom'` | Popup position relative to the element |
+| `spotlightPadding` | `number` | `8` | Padding (px) around the highlighted area |
+| `onEnter` | `(step: number) => void` | - | Callback when step is shown |
+| `onLeave` | `(step: number) => void` | - | Callback when leaving step |
+
+## TourAPI (control methods)
+
+| Method | Description |
+|--------|-------------|
+| `start(stepIndex?)` | Start tour from step 0 (or specified index) |
+| `stop()` | Stop and close the tour |
+| `next()` | Go to next step |
+| `prev()` | Go to previous step |
+| `goTo(stepIndex)` | Jump to a specific step (0-indexed) |
+| `isActive()` | Signal → boolean: whether tour is running |
+| `currentStep()` | Signal → number: current step index |
+
+## TourPlacement
+
+```
+'top' | 'top-start' | 'top-end'
+'bottom' | 'bottom-start' | 'bottom-end'
+'left' | 'left-start' | 'left-end'
+'right' | 'right-start' | 'right-end'
+'center'   ← popup centered on screen, not anchored to any element
+```
+
+## Common examples
+
+### Basic tour
+
+```tsx
+const [tour, TourUI] = createTour({
+  steps: [
+    {
+      target: 'header-logo',
+      title: 'Logo',
+      content: 'Click to go back to homepage.',
+      placement: 'bottom',
+    },
+    {
+      target: 'nav-search',
+      title: 'Search',
+      content: 'Enter keywords to find content.',
+    },
+  ],
+  onFinish: () => console.log('Finished!'),
+});
+```
+
+### Start from step 2
+
+```tsx
+tour.start(1); // 0-indexed
+```
+
+### Center popup (no element highlight)
+
+```tsx
+const [tour, TourUI] = createTour({
+  steps: [
+    { title: 'Welcome!', content: 'Quick guide...', placement: 'center' },
+  ],
+});
+```
+
+### Custom footer
+
+```tsx
+{
+  target: 'my-element',
+  title: 'Special step',
+  footer: (
+    <div class="flex justify-between w-full">
+      <button onClick={() => tour.stop()}>Skip</button>
+      <button onClick={() => tour.next()}>Continue →</button>
+    </div>
+  ),
+}
+```
+
+### Class override (slots)
+
+Slots: `root`, `mask`, `spotlight`, `popup`, `header`, `body`, `footer`, `progress`
+
+```tsx
+const [tour, TourUI] = createTour({
+  steps: [...],
+  class: {
+    popup: 'border border-primary',
+    header: 'bg-primary/10',
+  },
+});
+```
+
+## Gotchas
+
+- **`TourUI` MUST be mounted in JSX** — without it, the overlay and popup will not render.
+- **`target` must be an HTML `id`** — not a class or CSS selector; the element must exist in the DOM.
+- `goTo()` and `start(n)` both trigger `onLeave` for the old step and `onEnter` for the new step.
+- When `maskClosable: false` (default), users must use Prev/Next/Done buttons to navigate.
+- Tour auto-scrolls the target element into the viewport if it is out of view.