snice 4.27.0 → 4.29.0

package/docs/components/toast.md

@@ -1,22 +1,25 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/toast.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/toast.md -->
 
 # Toast
 `<snice-toast-container>`
 
 Temporary, non-blocking notification messages. Includes a static `Toast` API for programmatic creation.
 
-## Importing
+## Table of Contents
+- [Components](#components)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
-**ESM (bundler)**
-```typescript
-import Toast from 'snice/components/toast/snice-toast-container';
-```
+## Components
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-toast-container.min.js"></script>
-```
+| Component | Description |
+|-----------|-------------|
+| `<snice-toast-container>` | Container that positions and manages toast notifications |
+| `<snice-toast>` | Individual toast notification element |
 
 ## Properties
 
@@ -80,29 +83,11 @@ interface ToastOptions {
 
 ### snice-toast
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer toast container (includes type modifier class) |
-| `icon` | `<span>` | Wrapper around the type-specific SVG icon |
-| `content` | `<span>` | The message text element |
-
-```css
-snice-toast::part(base) {
-  border-radius: 12px;
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
-}
-
-snice-toast::part(content) {
-  font-weight: 500;
-}
-
-snice-toast::part(icon) {
-  width: 24px;
-  height: 24px;
-}
-```
+| Part | Description |
+|------|-------------|
+| `base` | Outer toast container (includes type modifier class) |
+| `icon` | Wrapper around the type-specific SVG icon |
+| `content` | The message text element |
 
 ## Basic Usage
 
@@ -181,14 +166,3 @@ const id = container.show('Hello!', { type: 'success' });
 container.hide(id);
 container.clear();
 ```
-
-### Form Validation
-
-```typescript
-try {
-  await submitForm(formData);
-  Toast.success('Form submitted');
-} catch (error) {
-  Toast.error(error.message);
-}
-```

package/docs/components/tooltip.md

@@ -1,9 +1,9 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/tooltip.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/tooltip.md -->
 
 # Tooltip
 `<snice-tooltip>`
 
-Provides contextual information when users hover, click, or focus an element.
+Provides contextual information when users hover, click, or focus an element. Supports smart repositioning near viewport edges.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -14,19 +14,6 @@ Provides contextual information when users hover, click, or focus an element.
 - [Examples](#examples)
 - [Attribute-Based Tooltips](#attribute-based-tooltips)
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/tooltip/snice-tooltip';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-tooltip.min.js"></script>
-```
-
 ## Properties
 
 | Property | Type | Default | Description |
@@ -60,30 +47,12 @@ import 'snice/components/tooltip/snice-tooltip';
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `trigger` | `<div>` | Wrapper around the slot/trigger content |
-| `tooltip` | `<div>` | The tooltip popup element |
-| `content` | `<span>` | The text content inside the tooltip |
-| `arrow` | `<div>` | The arrow/caret element pointing to the trigger |
-
-```css
-snice-tooltip::part(tooltip) {
-  background: #1e293b;
-  border-radius: 8px;
-  font-size: 13px;
-}
-
-snice-tooltip::part(arrow) {
-  color: #1e293b;
-}
-
-snice-tooltip::part(content) {
-  padding: 8px 14px;
-}
-```
+| Part | Description |
+|------|-------------|
+| `trigger` | Wrapper around the slot/trigger content |
+| `tooltip` | The tooltip popup element |
+| `content` | The text content inside the tooltip |
+| `arrow` | The arrow/caret element pointing to the trigger |
 
 ## Basic Usage
 
@@ -218,7 +187,7 @@ Set the `strict-positioning` attribute to disable automatic repositioning when n
 
 Wrapping elements in `<snice-tooltip>` can break parent-child relationships in components that require direct children (accordion, tabs, stepper, breadcrumbs, table, etc.). The attribute-based approach uses a plain `tooltip` attribute on any element, avoiding DOM disruption entirely.
 
-The tooltip observer activates automatically when any tooltip component is loaded — no setup needed.
+The tooltip observer activates automatically when any tooltip component is loaded -- no setup needed.
 
 ### Basic Usage
 
@@ -236,101 +205,30 @@ The tooltip observer activates automatically when any tooltip component is loade
 
 ### Inside Strict-Children Components
 
-This is the primary use case — adding tooltips without disrupting component structure:
+This is the primary use case -- adding tooltips without disrupting component structure:
 
 ```html
 <snice-tabs>
   <snice-tab slot="nav" tooltip="User settings">Settings</snice-tab>
   <snice-tab slot="nav" tooltip="Account info">Profile</snice-tab>
 </snice-tabs>
-
-<snice-accordion>
-  <snice-accordion-item tooltip="Click to expand">
-    <span slot="header">Section 1</span>
-    <p>Content here</p>
-  </snice-accordion-item>
-</snice-accordion>
-
-<snice-breadcrumbs>
-  <a href="/" tooltip="Go to homepage">Home</a>
-  <a href="/docs" tooltip="Documentation">Docs</a>
-</snice-breadcrumbs>
-```
-
-### Scoped Configuration via CSS
-
-Use CSS custom properties to configure tooltips. Properties cascade, so you can scope config with CSS selectors:
-
-```html
-<style>
-  /* All toolbar tooltips appear below with a delay */
-  .toolbar [tooltip] {
-    --tooltip-position: bottom;
-    --tooltip-delay: 200;
-  }
-
-  /* Sidebar tooltips appear to the right */
-  .sidebar [tooltip] {
-    --tooltip-position: right;
-    --tooltip-offset: 16;
-  }
-
-  /* Custom themed tooltips */
-  .dark-section [tooltip] {
-    --tooltip-bg: hsl(220 20% 15%);
-    --tooltip-color: hsl(220 20% 90%);
-    --tooltip-radius: 8px;
-    --tooltip-font-size: 13px;
-  }
-</style>
-
-<div class="toolbar">
-  <button tooltip="Bold (Ctrl+B)"><b>B</b></button>
-  <button tooltip="Italic (Ctrl+I)"><i>I</i></button>
-</div>
-```
-
-### Click Trigger
-
-```html
-<button tooltip="Click to toggle" style="--tooltip-trigger: click">
-  Click me
-</button>
-```
-
-### Focus Trigger
-
-```html
-<input tooltip="Enter your email" style="--tooltip-trigger: focus" type="email">
-```
-
-### Without Arrow
-
-```html
-<button tooltip="No arrow" style="--tooltip-arrow: none">
-  Hover me
-</button>
 ```
 
 ### CSS Variable Reference
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `--tooltip-position` | `top` | Position: `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end` |
-| `--tooltip-trigger` | `hover` | Trigger: `hover`, `click`, `focus` |
+| `--tooltip-position` | `top` | Position: top/bottom/left/right + -start/-end |
+| `--tooltip-trigger` | `hover` | Trigger: hover, click, focus |
 | `--tooltip-delay` | `0` | Show delay in milliseconds |
 | `--tooltip-hide-delay` | `0` | Hide delay in milliseconds |
 | `--tooltip-offset` | `12` | Distance from trigger element in pixels |
 | `--tooltip-arrow` | *(shown)* | Set to `none` to hide the arrow |
 | `--tooltip-max-width` | `250` | Maximum tooltip width in pixels |
 | `--tooltip-z-index` | `10000` | Z-index stacking order |
-| `--tooltip-strict-positioning` | *(false)* | Set to `true` to disable automatic repositioning when near viewport edges |
+| `--tooltip-strict-positioning` | *(false)* | Set to `true` to disable auto-flip |
 | `--tooltip-bg` | `hsl(0 0% 20%)` | Background color |
 | `--tooltip-color` | `white` | Text color |
 | `--tooltip-padding` | `8px 12px` | Content padding |
 | `--tooltip-radius` | `6px` | Border radius |
 | `--tooltip-font-size` | `14px` | Font size |
-
-### Cleanup
-
-The tooltip observer is managed automatically by the tooltip component. It activates as a side effect when any `<snice-tooltip>` component is loaded and cleans up when no longer needed.

package/docs/components/tree.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/tree.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/tree.md -->
 
 # Tree
 `<snice-tree>`
@@ -14,29 +14,16 @@ Displays hierarchical data with expandable/collapsible nodes, selection, checkbo
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/tree/snice-tree';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-tree.min.js"></script>
-```
-
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `selectable` | `boolean` | `true` | Enable or disable node selection |
-| `nodes` | `TreeNode[]` | `[]` | Array of tree nodes |
 | `selectionMode` (attr: `selection-mode`) | `'single' \| 'multiple' \| 'none'` | `'single'` | Selection behavior |
 | `showCheckboxes` (attr: `show-checkboxes`) | `boolean` | `false` | Display checkboxes |
 | `showIcons` (attr: `show-icons`) | `boolean` | `true` | Display node icons |
 | `expandOnClick` (attr: `expand-on-click`) | `boolean` | `false` | Expand/collapse on node click |
+| `nodes` | `TreeNode[]` | `[]` | Array of tree nodes |
 | `selectedNodes` (attr: `selected-nodes`) | `string[]` | `[]` | Selected node IDs |
 | `checkedNodes` (attr: `checked-nodes`) | `string[]` | `[]` | Checked node IDs |
 
@@ -182,10 +169,6 @@ tree.nodes = [
 
 Set `lazy: true` on nodes to load children on demand.
 
-```html
-<snice-tree></snice-tree>
-```
-
 ```typescript
 tree.nodes = [
   { id: 'folder', label: 'Click to load...', icon: '📁', lazy: true, children: [] }

package/docs/components/treemap.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/treemap.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/treemap.md -->
 
 # Treemap
 `<snice-treemap>`
 
-Renders hierarchical data as nested rectangles using a squarified treemap layout. Each rectangle's area is proportional to its value.
+Renders hierarchical data as nested rectangles using a squarified treemap layout. Each rectangle's area is proportional to its value. Supports drill-down navigation.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/treemap/snice-treemap';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-treemap.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
@@ -28,6 +23,7 @@ import 'snice/components/treemap/snice-treemap';
 | `colorScheme` (attr: `color-scheme`) | `'default' \| 'blue' \| 'green' \| 'purple' \| 'orange' \| 'warm' \| 'cool' \| 'rainbow'` | `'default'` | Color scheme |
 | `padding` | `number` | `2` | Padding between rectangles (px) |
 | `animation` | `boolean` | `true` | Enable transitions |
+| `drillPath` | `TreemapNode[]` | _(read-only)_ | Current drill-down path |
 
 ### TreemapNode Interface
 
@@ -48,8 +44,6 @@ interface TreemapNode {
 | `drillUp()` | -- | Go back one level |
 | `drillToRoot()` | -- | Reset to root level |
 
-The `drillPath` getter returns the current drill-down path as `TreemapNode[]`.
-
 ## Events
 
 | Event | Detail | Description |
@@ -60,26 +54,12 @@ The `drillPath` getter returns the current drill-down path as `TreemapNode[]`.
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `breadcrumbs` | `<div>` | Breadcrumb navigation for drill-down |
-| `base` | `<div>` | The main treemap container |
-| `chart` | `<div>` | The chart rendering area |
-| `tooltip` | `<div>` | The hover tooltip element |
-
-```css
-snice-treemap::part(base) {
-  border-radius: 8px;
-  overflow: hidden;
-}
-
-snice-treemap::part(breadcrumbs) {
-  padding: 0.5rem;
-  font-size: 0.875rem;
-}
-```
+| Part | Description |
+|------|-------------|
+| `breadcrumbs` | Breadcrumb navigation for drill-down |
+| `base` | The main treemap container |
+| `chart` | The chart rendering area |
+| `tooltip` | The hover tooltip element |
 
 ## Basic Usage
 
@@ -136,10 +116,6 @@ treemap.data = {
 
 Click a rectangle with children to drill into it. A breadcrumb trail appears for navigation.
 
-```html
-<snice-treemap show-labels style="height: 400px;"></snice-treemap>
-```
-
 ```typescript
 treemap.data = {
   label: 'Company',
@@ -170,8 +146,8 @@ treemap.data = {
 ### Programmatic Navigation
 
 ```typescript
-treemap.drillDown(node);   // Drill into a node
-treemap.drillUp();          // Go back one level
-treemap.drillToRoot();      // Reset to root
+treemap.drillDown(node);       // Drill into a node
+treemap.drillUp();              // Go back one level
+treemap.drillToRoot();          // Reset to root
 console.log(treemap.drillPath); // Current path
 ```

package/docs/components/user-card.md

@@ -1,23 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/user-card.md instead -->
-
-# User Card Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/user-card.md -->
 
+# User Card
 `<snice-user-card>`
 
-A profile card that displays a user's avatar, name, role, contact information, social links, and online status. Supports three layout variants for different use cases.
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/user-card/snice-user-card';
-```
+A profile card that displays a user's avatar, name, role, contact information, social links, and online status. Supports three layout variants.
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-user-card.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -30,7 +26,7 @@ import 'snice/components/user-card/snice-user-card';
 | `email` | `string` | `''` | Email address (displayed as mailto link) |
 | `phone` | `string` | `''` | Phone number (displayed as tel link) |
 | `location` | `string` | `''` | Location text |
-| `social` | `SocialLink[]` | `[]` | Array of `{ platform, url }` objects. Set via JS property. |
+| `social` | `SocialLink[]` | `[]` | Array of `{ platform, url }` objects (JS property only) |
 | `status` | `'online' \| 'away' \| 'offline' \| 'busy'` | `'offline'` | Online status indicator |
 | `variant` | `'card' \| 'horizontal' \| 'compact'` | `'card'` | Layout variant |
 
@@ -89,13 +85,8 @@ import 'snice/components/user-card/snice-user-card';
 Use the `variant` attribute to change the layout style.
 
 ```html
-<!-- Default card (centered) -->
 <snice-user-card variant="card" name="Sarah Johnson" role="Engineer"></snice-user-card>
-
-<!-- Horizontal layout -->
 <snice-user-card variant="horizontal" name="Sarah Johnson" role="Engineer"></snice-user-card>
-
-<!-- Compact (for lists) -->
 <snice-user-card variant="compact" name="Sarah Johnson" role="Engineer"></snice-user-card>
 ```