solid-tom-ui 1.0.8 → 1.0.11

package/dist/skill/avatar.skill.md.txt

@@ -0,0 +1,255 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Avatar } from 'solid-tom-ui';`
+- **Exports**: `Avatar` (main), `Avatar.Group` (sub-component)
+- **Framework**: SolidJS
+- **Purpose**: Display user profile images, initials, or icon placeholders; supports groups
+
+## TYPE SIGNATURES
+
+### Avatar (single)
+```typescript
+import { Avatar } from 'solid-tom-ui';
+
+type AvatarProps = {
+  width: string | number;           // REQUIRED: size in px (number) or CSS units (string)
+  image?: string;                   // Image URL — if provided, renders <img>
+  placeholder?: SolidComponent;     // Fallback JSX shown when no image (initials, icon, etc.)
+  mask?: 'heart' | 'squircle' | 'hexagon';  // Shape mask; omit for default circle
+  status?: 'online' | 'offline';    // Status indicator dot; omit for no indicator
+  class?: {
+    avatar?: string;                // Extra classes on the avatar container div
+  };
+};
+```
+
+### Avatar.Group
+```typescript
+type AvatarGroup = {
+  width: string | number;           // REQUIRED: uniform size for all avatars in group
+  avatars: Omit<AvatarProps, 'width' | 'status'>[];  // REQUIRED: array of avatar configs
+  counter?: number;                 // Show "+N" badge at end of group
+  class?: string;                   // Extra classes on the group container
+};
+```
+
+## KEY RULES
+- `width` is **always required** on both `Avatar` and `Avatar.Group`
+- `image` and `placeholder` are mutually exclusive in intent — if `image` is set and loads, `placeholder` is not shown
+- `Avatar.Group` does **not** support per-avatar `status` — statuses are stripped in the group type
+- In `Avatar.Group`, the `width` prop applies uniformly to all avatars; individual avatar items cannot override it
+
+## WIDTH SPECIFICATION
+```tsx
+// Number → interpreted as pixels
+<Avatar width={48} image={url} />   // 48px × 48px
+
+// String → any valid CSS unit
+<Avatar width="3rem" image={url} />
+<Avatar width="5rem" image={url} />
+<Avatar width="100px" image={url} />
+```
+
+## MASK (SHAPE) OPTIONS
+| `mask` value | Shape |
+|-------------|-------|
+| `undefined` (omit) | Circle (default) |
+| `"squircle"` | Rounded square |
+| `"hexagon"` | Hexagonal |
+| `"heart"` | Heart shape |
+
+## STATUS INDICATOR
+| `status` value | Indicator |
+|---------------|-----------|
+| `undefined` (omit) | None |
+| `"online"` | Green dot |
+| `"offline"` | Gray dot |
+
+## USAGE PATTERNS
+
+### Basic image avatar (circle, no status)
+```tsx
+<Avatar image="https://example.com/user.jpg" width={48} />
+```
+
+### Sized avatar
+```tsx
+// Common sizes: 32, 48, 64, 80, 96 (pixels)
+<Avatar image={userPhotoUrl} width={32} />   // small (e.g., in list rows)
+<Avatar image={userPhotoUrl} width={48} />   // medium (e.g., comment threads)
+<Avatar image={userPhotoUrl} width={64} />   // large (e.g., profile cards)
+<Avatar image={userPhotoUrl} width={96} />   // xl (e.g., profile page header)
+```
+
+### With online/offline status
+```tsx
+<Avatar image={userPhotoUrl} width={48} status="online" />
+<Avatar image={userPhotoUrl} width={48} status="offline" />
+```
+
+### With mask (non-circle shape)
+```tsx
+<Avatar image={userPhotoUrl} width={64} mask="squircle" />
+<Avatar image={userPhotoUrl} width={64} mask="hexagon" />
+<Avatar image={userPhotoUrl} width={64} mask="heart" />
+```
+
+### Placeholder — initials (when no image)
+```tsx
+<Avatar
+  width={64}
+  placeholder={
+    <div class="bg-neutral text-neutral-content flex h-16 w-16 items-center justify-center rounded-full">
+      <span class="text-xl">AB</span>
+    </div>
+  }
+/>
+```
+
+### Placeholder — icon (generic user silhouette)
+```tsx
+<Avatar
+  width={64}
+  placeholder={
+    <div class="bg-primary text-primary-content flex h-16 w-16 items-center justify-center rounded-full">
+      <DynamicIcon name="user" size={32} />
+    </div>
+  }
+/>
+```
+
+### Placeholder with status
+```tsx
+<Avatar
+  width={64}
+  status="online"
+  placeholder={
+    <div class="bg-accent text-accent-content flex h-16 w-16 items-center justify-center rounded-full">
+      <span class="text-xl">JD</span>
+    </div>
+  }
+/>
+```
+
+### Avatar.Group — basic group
+```tsx
+const users = [
+  { image: 'https://example.com/user1.jpg' },
+  { image: 'https://example.com/user2.jpg' },
+  { image: 'https://example.com/user3.jpg' },
+];
+
+<Avatar.Group width={48} avatars={users} />
+```
+
+### Avatar.Group — with overflow counter
+```tsx
+// Shows avatars + "+12" badge at the end
+<Avatar.Group
+  width={48}
+  avatars={[
+    { image: url1 },
+    { image: url2 },
+    { image: url3 },
+  ]}
+  counter={12}
+/>
+```
+
+### Avatar.Group — with custom masks
+```tsx
+<Avatar.Group
+  width={48}
+  avatars={[
+    { image: url1, mask: 'squircle' },
+    { image: url2, mask: 'squircle' },
+    { image: url3, mask: 'squircle' },
+  ]}
+  counter={5}
+/>
+```
+
+### Avatar.Group — with placeholder avatars
+```tsx
+<Avatar.Group
+  width={40}
+  avatars={[
+    { image: url1 },
+    {
+      placeholder: (
+        <div class="bg-neutral text-neutral-content flex items-center justify-center rounded-full" style={{ width: '40px', height: '40px' }}>
+          <span class="text-sm">AB</span>
+        </div>
+      )
+    },
+    { image: url3 },
+  ]}
+  counter={8}
+/>
+```
+
+## DECISION RULES
+
+**Single Avatar vs Avatar.Group:**
+- One user → `Avatar`
+- Multiple users shown together (team, participants, collaborators) → `Avatar.Group`
+
+**Image vs placeholder:**
+- User has a profile photo → use `image`
+- No profile photo → use `placeholder` with initials derived from user's name
+- Unknown user → use `placeholder` with a generic user icon
+
+**Width selection:**
+- Navigation bar / list row → `32` or `40`
+- Comment / chat UI → `48`
+- Card / profile preview → `64`
+- Full profile page header → `80` or `96`
+- Group avatars → smaller size (e.g., `40` or `48`) since they overlap
+
+**Mask selection:**
+- Standard user avatar → no mask (circle)
+- App/bot/system avatar → `squircle` or `hexagon`
+- Decorative / brand avatar → `heart` or any mask
+
+**Status dots:**
+- Real-time presence system → use `status`
+- Static display (profile page without live data) → omit `status`
+
+**Counter in Avatar.Group:**
+- Total participants count is known → set `counter` to (total - displayed) or total count
+- If all participants are shown → omit `counter`
+
+## PLACEHOLDER SIZING NOTE
+When using `placeholder`, the inner element's dimensions must match the `width` prop manually:
+```tsx
+// width={64} → inner element must be 64px × 64px
+<Avatar
+  width={64}
+  placeholder={
+    <div class="flex h-16 w-16 items-center justify-center rounded-full bg-primary text-primary-content">
+      {/* h-16 = 64px, w-16 = 64px */}
+      <span>AB</span>
+    </div>
+  }
+/>
+```
+
+## ANTI-PATTERNS
+```tsx
+// ❌ Missing required width
+<Avatar image={url} />  // TypeScript error
+
+// ❌ Setting status on Avatar.Group items (not supported — stripped from type)
+<Avatar.Group width={48} avatars={[{ image: url, status: 'online' }]} />  // TypeScript error
+
+// ❌ Mismatched placeholder size vs width prop
+<Avatar width={96} placeholder={<div class="h-8 w-8 rounded-full bg-gray-300" />} />
+// ✅ Match placeholder dimensions to width
+<Avatar width={96} placeholder={<div class="h-24 w-24 rounded-full bg-gray-300" />} />
+```
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `av01`, `av02`) 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/badge.skill.md.txt

@@ -0,0 +1,223 @@
+## COMPONENT IDENTITY
+
+- **Import**: `import { Badge } from 'solid-tom-ui';`
+- **Export**: `Badge` (named export), `BadgeVariantsProps` (type export)
+- **Framework**: SolidJS
+- **Purpose**: Small label/tag for status, category, count, or metadata display
+
+## TYPE SIGNATURE
+
+```typescript
+import { Badge } from 'solid-tom-ui';
+
+interface BadgeProps {
+  content?: SolidComponent; // Text string or JSXElement (default: "lorem")
+  size?: '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+  color?: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error';
+  variants?: 'outline' | 'soft' | 'dashed';
+  class?: string; // Append additional Tailwind classes
+  overrideClass?: string; // Completely replace all variant classes
+  customColor?: string; // Custom CSS color string
+}
+```
+
+## CLASS SLOTS
+
+`Badge` is a single-element component. Use `class` to append classes and `overrideClass` to fully replace all variant classes. No named sub-element slots.
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `bg01`, `bg02`) per project convention.
+
+## DEFAULTS
+
+| Prop       | Default     |
+| ---------- | ----------- |
+| `size`     | `"md"`      |
+| `color`    | `"primary"` |
+| `variants` | `"soft"`    |
+| `content`  | `"lorem"`   |
+
+## SIZE REFERENCE
+
+| Size  | Height | Font size         |
+| ----- | ------ | ----------------- |
+| `3xs` | h-3.5  | text-[10px]       |
+| `2xs` | h-4    | text-xs           |
+| `xs`  | h-4.5  | text-sm           |
+| `sm`  | h-5    | text-sm           |
+| `md`  | h-5.5  | text-sm (default) |
+| `lg`  | h-6    | text-base         |
+| `xl`  | h-6.5  | text-base         |
+| `2xl` | h-7    | text-base         |
+| `3xl` | h-7.5  | text-base         |
+
+## VARIANT SEMANTICS
+
+| Variant   | Visual appearance               | Use case                           |
+| --------- | ------------------------------- | ---------------------------------- |
+| `soft`    | Filled background (low opacity) | Default — status labels, tags      |
+| `outline` | Transparent bg, colored border  | Category tags, filters             |
+| `dashed`  | Dashed border, white bg         | Draft / temporary / pending states |
+
+## COLOR SEMANTICS
+
+| Color       | Semantic meaning             |
+| ----------- | ---------------------------- |
+| `primary`   | Brand / highlight (default)  |
+| `secondary` | Secondary brand              |
+| `accent`    | Special highlight            |
+| `neutral`   | Gray, no meaning, draft      |
+| `info`      | Informational                |
+| `success`   | Positive / active / complete |
+| `warning`   | Caution / pending            |
+| `error`     | Negative / failed / critical |
+
+## USAGE PATTERNS
+
+### Simple text badge
+
+```tsx
+<Badge content="Active" color="success" variants="soft" size="sm" />
+<Badge content="Pending" color="warning" variants="soft" size="sm" />
+<Badge content="Failed" color="error" variants="soft" size="sm" />
+```
+
+### Status indicators
+
+```tsx
+// Active/inactive status
+<Badge color="success" variants="soft" size="xs" content="Active" />
+<Badge color="error" variants="soft" size="xs" content="Inactive" />
+<Badge color="warning" variants="soft" size="xs" content="Pending" />
+<Badge color="info" variants="soft" size="xs" content="Processing" />
+<Badge color="neutral" variants="soft" size="xs" content="Draft" />
+```
+
+### Category / filter tags
+
+```tsx
+<Badge color="primary" variants="outline" size="xs" content="Technology" />
+<Badge color="secondary" variants="outline" size="xs" content="Design" />
+<Badge color="accent" variants="outline" size="xs" content="Marketing" />
+```
+
+### Notification count badges
+
+```tsx
+// Small number counts — use tiny sizes
+<Badge color="error" variants="soft" size="3xs" content="5" />
+<Badge color="primary" variants="soft" size="3xs" content="12" />
+<Badge color="success" variants="soft" size="3xs" content="99+" />
+```
+
+### Priority levels
+
+```tsx
+<Badge color="error" variants="dashed" size="xs" content="Critical" />
+<Badge color="warning" variants="dashed" size="xs" content="High" />
+<Badge color="info" variants="dashed" size="xs" content="Medium" />
+<Badge color="neutral" variants="dashed" size="xs" content="Low" />
+```
+
+### Badge with icon (JSX content)
+
+```tsx
+import { Icon } from 'lucide-solid';
+
+// Completed badge with checkmark
+<Badge
+  color="success"
+  variants="soft"
+  size="sm"
+  content={() => (
+    <div class="flex items-center gap-1">
+      <Icon name="check" size={12} />
+      <span class="-translate-y-px">Completed</span>
+    </div>
+  )}
+/>
+
+// Closable badge (close button inside content)
+<Badge
+  color="neutral"
+  variants="soft"
+  size="sm"
+  content={() => (
+    <div class="flex items-center gap-1">
+      <span class="-translate-y-px">Tag Label</span>
+      <Icon name="x" size={10} class="cursor-pointer hover:opacity-70" onClick={handleRemove} />
+    </div>
+  )}
+/>
+```
+
+### Custom Tailwind classes (append)
+
+```tsx
+// Append extra styles — does not remove defaults
+<Badge content="Amber" class="h-5 bg-amber-200 text-sm text-amber-900/80" />
+<Badge content="Gradient" class="h-5 bg-linear-to-r from-purple-400 to-pink-400 text-sm text-white" />
+<Badge content="Pill shape" class="h-5 rounded-full px-3" />
+```
+
+### Full class override
+
+```tsx
+// Completely replace component classes
+<Badge
+  content="Custom"
+  overrideClass="inline-flex items-center px-2 py-1 rounded text-xs font-bold bg-purple-600 text-white"
+/>
+```
+
+## DECISION RULES
+
+**Choosing `variants`:**
+
+- Status / label → `soft` (default, most readable)
+- Filter chip / selectable tag → `outline`
+- Unconfirmed / draft / temporary → `dashed`
+
+**Choosing `size`:**
+
+- Inline with body text → `xs` or `sm`
+- Standalone label → `md` (default)
+- Notification dot / count → `3xs` or `2xs`
+- Headline-level badge → `lg` or `xl`
+
+**Choosing `color`:**
+
+- Boolean positive state (active, online, success) → `success`
+- Boolean negative state (inactive, offline, error) → `error`
+- Transitional state (loading, pending) → `warning`
+- Informational only → `info`
+- Neutral tags with no semantic meaning → `neutral`
+- Primary brand label → `primary`
+
+**Rich content (icons, buttons inside badge):**
+
+- Pass a function `() => JSX` or a JSX element to `content`
+- Keep content minimal — badge is meant to be small
+
+**Text truncation:**
+
+- Long text auto-truncates with ellipsis
+- Wrap badge in a width-constrained container if truncation is needed
+
+## ANTI-PATTERNS
+
+```tsx
+// ❌ Missing content — shows "lorem" placeholder
+<Badge color="success" />
+
+// ❌ Using overrideClass for minor adjustments — use class instead
+<Badge content="X" overrideClass="rounded px-2 text-xs bg-blue-500 text-white flex items-center" />
+// ✅ Prefer class for additive changes
+<Badge content="X" color="info" variants="soft" class="rounded-full px-3" />
+
+// ❌ Nesting complex interactive UIs inside Badge content
+// Badge is display-only — avoid heavy interaction inside content
+
+// ✅ For notification bubbles over avatars/icons, compose Badge with the parent container
+```
+
+> **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/breadcrumb.skill.md.txt

@@ -0,0 +1,177 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Breadcrumb } from 'solid-tom-ui';`
+- **Export**: `Breadcrumb` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Navigation trail showing hierarchy of current page location
+
+## TYPE SIGNATURE
+
+```typescript
+import { Breadcrumb } from 'solid-tom-ui';
+
+type BreadcrumbProps = {
+  items: SolidComponent[];          // REQUIRED: array of items (string | JSXElement | () => JSX)
+  separate?: SolidComponent;        // Custom separator between items (default: CSS chevron arrow)
+  class?: Partial<Record<'root' | 'item', string>>;  // Scoped custom classes
+  onItemClick?: (e: MouseEvent) => void;  // Click handler for any item
+};
+```
+
+## KEY RULES
+- `items` is the **only required prop**
+- Items are rendered in order: `items[0]` → separator → `items[1]` → ... → `items[n-1]`
+- Separator is inserted **between** items, **not after the last** item
+- Each item can be a plain string or any JSXElement (supports icons, links, styled content)
+- `onItemClick` fires for **every** item clicked — use the event target to identify which item
+
+## USAGE PATTERNS
+
+### Minimal — plain text items
+```tsx
+<Breadcrumb items={['Home', 'Products', 'Electronics', 'Laptops']} />
+```
+
+### Custom separator
+```tsx
+// Text separator
+<Breadcrumb
+  items={['Home', 'Settings', 'Profile']}
+  separate={<span class="mx-2 text-gray-400">/</span>}
+/>
+
+// Icon separator
+<Breadcrumb
+  items={['Home', 'Settings', 'Profile']}
+  separate={<DynamicIcon name="chevron-right" size={14} class="mx-1 text-gray-400" />}
+/>
+
+// Dash separator
+<Breadcrumb
+  items={['Section 1', 'Section 2', 'Section 3']}
+  separate={<div class="mx-2">-</div>}
+/>
+```
+
+### With icons in items
+```tsx
+import { DynamicIcon } from 'solid-tom-ui';
+
+<Breadcrumb
+  items={[
+    <div class="flex items-center gap-2">
+      <DynamicIcon name="home" size={16} />
+      Home
+    </div>,
+    <div class="flex items-center gap-2">
+      <DynamicIcon name="folder" size={16} />
+      Documents
+    </div>,
+    <div class="flex items-center gap-2">
+      <DynamicIcon name="file" size={16} />
+      report.pdf
+    </div>,
+  ]}
+/>
+```
+
+### With click handler
+```tsx
+const [activePath, setActivePath] = createSignal<string[]>(['Home', 'Products']);
+
+<Breadcrumb
+  items={activePath()}
+  onItemClick={(e) => {
+    const clickedText = (e.target as HTMLElement).textContent;
+    console.log('Clicked breadcrumb item:', clickedText);
+    // Handle navigation here
+  }}
+/>
+```
+
+### Custom CSS classes
+```tsx
+<Breadcrumb
+  items={['Home', 'Library', 'Data']}
+  class={{
+    root: 'bg-gray-100 rounded-lg px-4 py-2',
+    item: 'text-blue-600 hover:text-blue-800 font-medium',
+  }}
+/>
+```
+
+### Clickable items as anchor tags
+```tsx
+<Breadcrumb
+  items={[
+    <a href="/" class="hover:underline">Home</a>,
+    <a href="/products" class="hover:underline">Products</a>,
+    <span class="text-gray-500">Current Page</span>,
+  ]}
+/>
+```
+
+## DECISION RULES
+
+**When to use a custom separator:**
+- Default: use the built-in CSS chevron (no `separate` prop needed)
+- Brand-specific style: pass a custom icon or character via `separate`
+- Minimal/flat UI: use `<span class="mx-2">/</span>`
+
+**Item content strategy:**
+- Plain navigation labels → plain strings
+- Route with icon → JSXElement with icon + label
+- Clickable items → wrap in `<a>` tags inside the JSX items, OR use `onItemClick`
+- Last item (current page) → typically rendered non-clickable / different style
+
+**When NOT to use Breadcrumb:**
+- If hierarchy depth is always 1 level → use a back button instead
+- If items are dynamic and represent tabs or steps → use a stepper or tabs component
+
+## COMMON PATTERNS IN APPS
+
+### Dynamic breadcrumb from route
+```tsx
+const routes = () => [
+  { label: 'Home', href: '/' },
+  { label: 'Products', href: '/products' },
+  { label: currentProduct().name, href: null },
+];
+
+<Breadcrumb
+  items={routes().map(r =>
+    r.href
+      ? <a href={r.href} class="hover:underline">{r.label}</a>
+      : <span>{r.label}</span>
+  )}
+/>
+```
+
+### File path navigator
+```tsx
+const pathParts = () => currentPath().split('/').filter(Boolean);
+
+<Breadcrumb
+  items={['Root', ...pathParts()]}
+  separate={<span class="mx-1 text-gray-400">/</span>}
+  onItemClick={(e) => navigateToSegment(e)}
+/>
+```
+
+## ANTI-PATTERNS
+```tsx
+// ❌ Empty items array — renders nothing useful
+<Breadcrumb items={[]} />
+
+// ❌ Passing a separator that includes the chevron logic itself when default works fine
+<Breadcrumb items={items} separate={<span>›</span>} />  // redundant if default style fits
+
+// ✅ Use default separator when it fits the design system
+<Breadcrumb items={items} />
+```
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `bc01`, `bc02`) 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()`.