snice 4.34.2 → 4.35.1

package/dist/react/SniceProvider.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/react/SniceRouter.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/react/index.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/react/matchRoute.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/react/useRequestHandler.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.34.1
+ * snice v4.35.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.

package/docs/STORYBOOK.md

@@ -0,0 +1,178 @@
+# Storybook
+
+Storybook provides an interactive component explorer for Snice components. Each component has its own story file that documents its variants, sizes, and states.
+
+## Getting Started
+
+```bash
+# Start the development server
+npm run storybook
+# Open http://localhost:6006
+
+# Build a static version
+npm run build-storybook
+```
+
+The `prestorybook` script ensures `dist/index.esm.js` exists (runs `npm run build:core` if not).
+
+## How It Works
+
+Storybook uses the `@storybook/web-components-vite` framework. Stories mount Snice components as standard HTML custom elements — no framework adapter needed.
+
+The SWC plugin (`unplugin-swc`) is injected via `viteFinal` in `.storybook/main.ts` to handle TC39 Stage 3 decorators (`decoratorVersion: '2022-03'`). This matches the existing Vite/Vitest config.
+
+### Theme
+
+The Snice theme CSS is loaded from `dist/components/theme/theme.css` (served at `/snice-components/theme/theme.css`). A toolbar button in Storybook lets you toggle between `dark` and `light` themes.
+
+## Where Stories Live
+
+```
+components/<name>/snice-<name>.stories.ts
+```
+
+For example:
+- `components/button/snice-button.stories.ts`
+- `components/input/snice-input.stories.ts`
+
+## Adding a Story
+
+### 1. Create the story file
+
+```ts
+// components/my-comp/snice-my-comp.stories.ts
+import type { Meta, StoryObj } from '@storybook/web-components-vite';
+import './snice-my-comp';
+import type { MyCompVariant, MyCompSize } from './snice-my-comp.types';
+
+type Args = {
+  variant?: MyCompVariant;
+  size?: MyCompSize;
+  disabled?: boolean;
+  label?: string;
+};
+
+const VARIANTS: MyCompVariant[] = ['default', 'primary', 'secondary'];
+const SIZES: MyCompSize[] = ['small', 'medium', 'large'];
+
+const meta: Meta<Args> = {
+  title: 'Category/MyComp',   // Use the appropriate category
+  component: 'snice-my-comp',
+  tags: ['autodocs'],          // Enables auto-generated docs page
+  argTypes: {
+    variant:  { control: 'select', options: VARIANTS },
+    size:     { control: 'select', options: SIZES },
+    disabled: { control: 'boolean' },
+    label:    { control: 'text' },
+  },
+  render: (args) => {
+    const el = document.createElement('snice-my-comp');
+    // String attributes
+    if (args.variant !== undefined) el.setAttribute('variant', String(args.variant));
+    if (args.size    !== undefined) el.setAttribute('size',    String(args.size));
+    // Boolean attributes — only set when true
+    if (args.disabled) el.toggleAttribute('disabled', true);
+    // Text content
+    el.textContent = args.label ?? 'Default';
+    return el;
+  },
+};
+export default meta;
+
+type Story = StoryObj<Args>;
+
+export const Default: Story = {
+  args: { variant: 'default', size: 'medium', label: 'Default' },
+};
+
+export const Primary: Story = {
+  args: { ...Default.args, variant: 'primary', label: 'Primary' },
+};
+
+export const AllVariants: Story = {
+  render: () => {
+    const wrap = document.createElement('div');
+    wrap.style.cssText = 'display:flex;gap:.75rem;flex-wrap:wrap;align-items:center;';
+    for (const variant of VARIANTS) {
+      const el = document.createElement('snice-my-comp');
+      el.setAttribute('variant', variant);
+      el.textContent = variant;
+      wrap.appendChild(el);
+    }
+    return wrap;
+  },
+};
+```
+
+### 2. Story naming convention
+
+- Always export `Default` and `AllVariants`
+- Add named stories for each significant showcase section
+- Use PascalCase for story names: `WithLabel`, `AllSizes`, `Disabled`, `Loading`
+
+### 3. Property types
+
+| Property type | How to set in render |
+|--------------|----------------------|
+| String attribute | `el.setAttribute('foo', String(args.foo))` |
+| Boolean attribute | `el.toggleAttribute('foo', true)` |
+| Object / Array | `(el as any).foo = args.foo` |
+| Kebab-case attribute | `el.setAttribute('my-attr', value)` |
+
+### 4. Events
+
+```ts
+el.addEventListener('my-event', (e: Event) => {
+  const detail = (e as CustomEvent).detail;
+  console.log(detail.value);
+});
+```
+
+## Snice Is NOT Lit
+
+Snice components are plain standard custom elements. Do NOT:
+- Import from `lit`, `lit-html`, or `lit-element`
+- Import `html` from `'snice'` in stories (that is Snice's internal template engine)
+- Extend `LitElement`
+
+Instead, use `document.createElement('snice-...')` and standard DOM APIs.
+
+## SWC / Decorator Configuration
+
+The `.storybook/main.ts` uses `viteFinal` to inject `unplugin-swc` with:
+
+```ts
+{
+  jsc: {
+    parser: { syntax: 'typescript', decorators: true },
+    target: 'es2022',
+    transform: {
+      decoratorMetadata: false,
+      decoratorVersion: '2022-03',
+      useDefineForClassFields: false,
+    },
+  },
+}
+```
+
+This matches `vite.config.ts` and `vitest.config.ts`. Never set `experimentalDecorators: true`.
+
+## File Structure
+
+```
+.storybook/
+  main.ts          # Framework config, SWC plugin, static dirs
+  preview.ts       # Global decorators, theme, backgrounds
+  tsconfig.json    # Extends root tsconfig, includes stories
+
+components/
+  button/
+    snice-button.ts
+    snice-button.types.ts
+    snice-button.css
+    snice-button.stories.ts   ← story file lives here
+
+docs/
+  STORYBOOK.md               ← this file
+  ai/STORYBOOK.md            ← token-efficient AI reference
+```

package/docs/ai/DEVELOPMENT.md

@@ -8,6 +8,7 @@ All components MUST:
 1. Support CDN builds (bundle with runtime)
 2. Have React adapter (React 17+)
 3. Be tested (CDN + React)
+4. Have Storybook stories at `components/<name>/snice-<name>.stories.ts` — one story per `<h2>` section in `full-showcase.html`, using `@storybook/html-vite` and `document.createElement` (see `docs/ai/STORYBOOK.md`)
 
 ## Build Commands
 

package/docs/ai/STORYBOOK.md

@@ -0,0 +1,66 @@
+# Storybook (AI Reference)
+
+## Commands
+```bash
+npm run storybook          # Dev server on :6006
+npm run build-storybook    # Static build → storybook-static/
+```
+
+`prestorybook` runs `npm run build:core` if `dist/index.esm.js` is missing.
+
+## Story locations
+`components/<name>/snice-<name>.stories.ts`
+
+## Story template
+```ts
+import type { Meta, StoryObj } from '@storybook/web-components-vite';
+import './snice-<name>';
+
+type Args = { variant?: string; disabled?: boolean; label?: string };
+
+const meta: Meta<Args> = {
+  title: 'Form/<PascalName>',
+  component: 'snice-<name>',
+  tags: ['autodocs'],
+  argTypes: {
+    variant:  { control: 'select', options: ['default', 'primary'] },
+    disabled: { control: 'boolean' },
+    label:    { control: 'text' },
+  },
+  render: (args) => {
+    const el = document.createElement('snice-<name>');
+    if (args.variant  !== undefined) el.setAttribute('variant', String(args.variant));
+    if (args.disabled)               el.toggleAttribute('disabled', true);
+    el.textContent = args.label ?? '';
+    return el;
+  },
+};
+export default meta;
+
+type Story = StoryObj<Args>;
+export const Default: Story = { args: { variant: 'default', label: 'Default' } };
+export const AllVariants: Story = { render: () => { /* build DOM */ } };
+```
+
+## DOM APIs in render
+- String attrs: `el.setAttribute('foo', value)`
+- Boolean attrs: `el.toggleAttribute('foo', bool)`
+- Object/Array props: `(el as any).foo = value`
+- Text content: `el.textContent = '...'`
+
+## IMPORTANT: NO LIT
+- Do NOT import from `lit`, `lit-html`, or `lit-element`
+- Do NOT import `html` from `'snice'` in stories
+- Snice components are standard custom elements; mount via `document.createElement`
+
+## Theme
+- CSS loaded from `/snice-components/theme/theme.css` in preview.ts
+- `data-theme="dark"` set on `<html>` by default
+- Theme switcher in toolbar toggles `dark` / `light`
+
+## Decorator config (SWC)
+`.storybook/main.ts` injects `unplugin-swc` via `viteFinal` with `decoratorVersion: '2022-03'`.
+Never use `experimentalDecorators`.
+
+## Long-form docs
+See `docs/STORYBOOK.md`

package/docs/ai/patterns.md

@@ -333,6 +333,24 @@ class MyForm extends HTMLElement {
 }
 ```
 
+## Icons
+```html
+<!-- Auto-detected: URL, file path, emoji, or ligature name -->
+<snice-button icon="search">Search</snice-button>
+<snice-button icon="🔍">Search</snice-button>
+<snice-button icon="/assets/icon.svg">Search</snice-button>
+<snice-input prefix-icon="search" suffix-icon="check_circle"></snice-input>
+
+<!-- Slot for full control -->
+<snice-input label="Amount">
+  <span slot="prefix-icon" class="fa fa-dollar-sign"></span>
+</snice-input>
+```
+```css
+/* Ligature icons use Material Symbols by default. Override: */
+:root { --snice-icon-font: 'Font Awesome 6 Free'; }
+```
+
 ## Keyboard Shortcuts
 ```typescript
 @element('editor')

package/docs/elements.md

@@ -632,6 +632,54 @@ class HostStyled extends HTMLElement {
 }
 ```
 
+### Icons
+
+Many Snice components accept an `icon` property (or `prefix-icon` / `suffix-icon` for inputs). The icon value is auto-detected:
+
+| Value | Rendered As |
+|-------|-------------|
+| `"search"`, `"check_circle"` | Ligature icon with icon font |
+| `"🔍"`, `"$"` | Text/emoji as-is |
+| `"https://example.com/icon.svg"` | `<img>` element |
+| `"logo.png"`, `"icon.svg"` | `<img>` element |
+| `"img://url"` | Explicit `<img>` |
+| `"text://content"` | Explicit `<span>` |
+
+#### Changing the Icon Font
+
+By default, ligature icons (lowercase words like `search`, `home`, `check_circle`) use **Material Symbols Outlined**. To use a different icon font like Font Awesome, set the `--snice-icon-font` CSS custom property:
+
+```css
+:root {
+  --snice-icon-font: 'Font Awesome 6 Free';
+}
+```
+
+Make sure to load the corresponding font in your HTML:
+
+```html
+<!-- Material Symbols (default) -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&display=swap">
+
+<!-- Or Font Awesome -->
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css">
+```
+
+#### Icon Slots
+
+For full control over icon rendering (e.g., using a specific icon library class), use named slots instead of the `icon` attribute:
+
+```html
+<snice-input label="Search">
+  <span slot="prefix-icon" class="fa-solid fa-magnifying-glass"></span>
+</snice-input>
+
+<snice-button>
+  <svg slot="icon" viewBox="0 0 24 24">...</svg>
+  Submit
+</snice-button>
+```
+
 ## Template Events
 
 Handle events directly in templates using `@event=${handler}` syntax:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "4.34.2",
+  "version": "4.35.1",
   "type": "module",
   "description": "A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.",
   "main": "dist/index.cjs",
@@ -96,6 +96,9 @@
     "access": "public"
   },
   "scripts": {
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build",
+    "prestorybook": "test -f dist/index.esm.js || npm run build:core",
     "dev": "node scripts/dev.js",
     "dev:framework": "vite",
     "sync-versions": "node scripts/sync-template-versions.js",
@@ -148,6 +151,10 @@
     "@semantic-release/gitlab": "^13.2.6",
     "@semantic-release/npm": "^12.0.2",
     "@semantic-release/release-notes-generator": "^14.0.3",
+    "@storybook/addon-essentials": "^8.6.12",
+    "@storybook/addon-interactions": "^8.6.12",
+    "@storybook/html": "^8.6.12",
+    "@storybook/html-vite": "^8.6.12",
     "@swc/core": "^1.13.5",
     "@types/node": "^20.0.0",
     "@types/react": "^19.2.2",
@@ -160,6 +167,7 @@
     "react-dom": "^19.2.0",
     "rollup": "^4.50.2",
     "semantic-release": "^24.2.7",
+    "storybook": "^8.6.12",
     "typescript": "^5.9.2",
     "unplugin-swc": "^1.5.7",
     "vite": "^5.0.10",