snice 4.14.0 → 4.16.0

package/docs/components/markdown.md

@@ -22,7 +22,7 @@ import 'snice/components/markdown/snice-markdown';
 ```
 
 ```html
-<snice-markdown content="# Hello World"></snice-markdown>
+<snice-markdown># Hello World</snice-markdown>
 ```
 
 ## Importing
@@ -42,7 +42,6 @@ import 'snice/components/markdown/snice-markdown';
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `content` | `string` | `''` | The markdown source text to render |
 | `sanitize` | `boolean` | `true` | Whether to sanitize the HTML output to prevent XSS |
 | `theme` | `'default' \| 'github'` | `'default'` | Visual theme for the rendered output |
 
@@ -88,23 +87,22 @@ The component supports GitHub Flavored Markdown (GFM):
 
 ### Rendering Static Content
 
-Use the `content` attribute to render a markdown string.
+Use slotted text to render markdown:
 
 ```html
-<snice-markdown
-  content="# Welcome
+<snice-markdown># Welcome
 
 This is **bold** and *italic* text.
 
 - Item one
 - Item two
-- Item three"
-></snice-markdown>
+- Item three
+</snice-markdown>
 ```
 
 ### Dynamic Content Updates
 
-Set the `content` property via JavaScript to update the rendered markdown dynamically.
+Use `setContent()` to update the rendered markdown programmatically:
 
 ```html
 <snice-markdown id="preview"></snice-markdown>
@@ -119,11 +117,11 @@ Type some **markdown** and see it render in real time.</textarea>
   const editor = document.getElementById('editor');
 
   // Set initial content
-  preview.content = editor.value;
+  preview.setContent(editor.value);
 
   // Update on input
   editor.addEventListener('input', () => {
-    preview.content = editor.value;
+    preview.setContent(editor.value);
   });
 </script>
 ```
@@ -133,9 +131,7 @@ Type some **markdown** and see it render in real time.</textarea>
 Use the `theme="github"` attribute for GitHub-style markdown rendering.
 
 ```html
-<snice-markdown
-  theme="github"
-  content="# GitHub Style
+<snice-markdown theme="github"># GitHub Style
 
 > This blockquote uses GitHub-style rendering.
 
@@ -143,11 +139,7 @@ Use the `theme="github"` attribute for GitHub-style markdown rendering.
 |---------|-----------|
 | Tables  | Yes       |
 | GFM     | Yes       |
-
-```javascript
-console.log('Syntax highlighting');
-```"
-></snice-markdown>
+</snice-markdown>
 ```
 
 ### Intercepting Link Clicks
@@ -155,10 +147,7 @@ console.log('Syntax highlighting');
 Listen for the `link-click` event to handle navigation within your application instead of following the default link behavior.
 
 ```html
-<snice-markdown
-  id="docs"
-  content="Check out [the documentation](/docs) or visit [our website](https://example.com)."
-></snice-markdown>
+<snice-markdown id="docs">Check out [the documentation](/docs) or visit [our website](https://example.com).</snice-markdown>
 
 <script type="module">
   import 'snice/components/markdown/snice-markdown';
@@ -184,21 +173,10 @@ Listen for the `link-click` event to handle navigation within your application i
 Render markdown that includes fenced code blocks and GFM tables.
 
 ```html
-<snice-markdown
-  content="## API Response
+<snice-markdown>## API Response
 
 The endpoint returns the following JSON:
 
-```json
-{
-  &quot;id&quot;: 1,
-  &quot;name&quot;: &quot;Example&quot;,
-  &quot;active&quot;: true
-}
-```
-
-### Status Codes
-
 | Code | Meaning |
 |------|---------|
 | 200  | Success |
@@ -207,8 +185,8 @@ The endpoint returns the following JSON:
 
 - [x] GET endpoint
 - [x] POST endpoint
-- [ ] DELETE endpoint"
-></snice-markdown>
+- [ ] DELETE endpoint
+</snice-markdown>
 ```
 
 ## Accessibility

package/docs/components/modal.md

@@ -188,6 +188,8 @@ modal.addEventListener('modal-close', () => console.log('Closed'));
 | `noEscapeDismiss` (attr: `no-escape-dismiss`) | `boolean` | `false` | Prevent closing with Escape key |
 | `noFocusTrap` (attr: `no-focus-trap`) | `boolean` | `false` | Disable focus trapping |
 | `noCloseButton` (attr: `no-close-button`) | `boolean` | `false` | Hide the close button |
+| `noHeader` (attr: `no-header`) | `boolean` | `false` | Hide the header section entirely |
+| `noFooter` (attr: `no-footer`) | `boolean` | `false` | Hide the footer section entirely |
 | `label` | `string` | `''` | Accessible label for screen readers |
 
 ## Events

package/docs/components/music-player.md

@@ -183,13 +183,14 @@ interface Track {
 |-------|--------|-------------|
 | `player-play` | `{ track: Track }` | Playback started |
 | `player-pause` | `{ track: Track }` | Playback paused |
-| `player-stop` | `{ track: Track }` | Playback stopped |
+| `player-stop` | `{ player: SniceMusicPlayerElement }` | Playback stopped |
 | `player-track-change` | `{ track: Track }` | Track changed |
 | `player-track-ended` | `{ track: Track }` | Track finished playing |
 | `player-shuffle-change` | `{ shuffle: boolean }` | Shuffle mode toggled |
 | `player-repeat-change` | `{ repeat: string }` | Repeat mode changed |
 | `player-volume-change` | `{ volume: number }` | Volume level changed |
-| `@snice/player-time-update` | `{ currentTime: number, duration: number }` | Playback time updated |
+| `player-seek` | `{ time: number }` | Seeked to a new position |
+| `player-time-update` | `{ currentTime: number, duration: number }` | Playback time updated |
 | `player-error` | `{ error: any }` | An error occurred |
 
 ## Methods

package/docs/components/network-graph.md

@@ -116,15 +116,15 @@ graph.data = {
 ### Event Handling
 
 ```typescript
-graph.addEventListener('@snice/node-click', (e) => {
+graph.addEventListener('node-click', (e) => {
   console.log('Clicked:', e.detail.node.label);
 });
 
-graph.addEventListener('@snice/node-drag', (e) => {
+graph.addEventListener('node-drag', (e) => {
   console.log(`Dragged ${e.detail.node.id} to (${e.detail.x}, ${e.detail.y})`);
 });
 
-graph.addEventListener('@snice/graph-zoom', (e) => {
+graph.addEventListener('graph-zoom', (e) => {
   console.log('Zoom:', e.detail.scale);
 });
 ```
@@ -181,7 +181,7 @@ interface NetworkEdge {
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `@snice/node-click` | `{ node: NetworkNode }` | Node clicked |
-| `@snice/edge-click` | `{ edge: NetworkEdge }` | Edge clicked |
-| `@snice/node-drag` | `{ node: NetworkNode, x: number, y: number }` | Node dragged |
-| `@snice/graph-zoom` | `{ scale: number, x: number, y: number }` | Zoom changed |
+| `node-click` | `{ node: NetworkNode }` | Node clicked |
+| `edge-click` | `{ edge: NetworkEdge }` | Edge clicked |
+| `node-drag` | `{ node: NetworkNode, x: number, y: number }` | Node dragged |
+| `graph-zoom` | `{ scale: number, x: number, y: number }` | Zoom changed |

package/docs/components/notification-center.md

@@ -44,6 +44,7 @@ import 'snice/components/notification-center/snice-notification-center';
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `notifications` | `NotificationItem[]` | `[]` | Array of notification objects to display |
+| `open` | `boolean` | `false` | Whether the dropdown panel is visible |
 
 ## Methods
 

package/docs/components/pdf-viewer.md

@@ -4,7 +4,7 @@
 
 `<snice-pdf-viewer>`
 
-A PDF document viewer with a built-in toolbar for page navigation, zoom control, fit modes, printing, and downloading. Uses PDF.js loaded from CDN for rendering.
+A PDF document viewer with a built-in toolbar for page navigation, zoom control, fit modes, printing, and downloading. Uses a vendored PDF.js bundle included with the component.
 
 ## Table of Contents
 - [Basic Usage](#basic-usage)

package/docs/components/sankey.md

@@ -120,15 +120,15 @@ Set the `animation` attribute for animated rendering.
 ```typescript
 const sankey = document.querySelector('snice-sankey');
 
-sankey.addEventListener('@snice/sankey-node-click', (e) => {
+sankey.addEventListener('sankey-node-click', (e) => {
   console.log('Node:', e.detail.node.label);
 });
 
-sankey.addEventListener('@snice/sankey-link-click', (e) => {
+sankey.addEventListener('sankey-link-click', (e) => {
   console.log('Link:', e.detail.link.source, '->', e.detail.link.target);
 });
 
-sankey.addEventListener('@snice/sankey-hover', (e) => {
+sankey.addEventListener('sankey-hover', (e) => {
   if (e.detail) {
     console.log('Hovering:', e.detail.type, e.detail.item);
   }
@@ -173,6 +173,6 @@ interface SankeyLink {
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `@snice/sankey-node-click` | `{ node: SankeyNode }` | Node clicked |
-| `@snice/sankey-link-click` | `{ link: SankeyLink }` | Link clicked |
-| `@snice/sankey-hover` | `{ type: 'node' \| 'link', item } \| null` | Hover state changed |
+| `sankey-node-click` | `{ node: SankeyNode }` | Node clicked |
+| `sankey-link-click` | `{ link: SankeyLink }` | Link clicked |
+| `sankey-hover` | `{ type: 'node' \| 'link', item } \| null` | Hover state changed |

package/docs/components/switch.md

@@ -58,7 +58,7 @@ Use the `label-on` and `label-off` attributes for text inside the switch track.
 
 ### In a Form
 
-The switch is form-associated and participates in form submission.
+The switch contains a native `<input type="checkbox">` internally, which participates in form submission when `name` is set.
 
 ```html
 <form id="settings-form">

package/docs/components/table.md

@@ -167,7 +167,7 @@ Use the `@request`/`@respond` pattern to load data from an external source.
 
   @element('my-table-controller')
   class MyTableController extends HTMLElement {
-    @respond('@snice/table/config')
+    @respond('table/config')
     getConfig() {
       return {
         columns: [
@@ -177,7 +177,7 @@ Use the `@request`/`@respond` pattern to load data from an external source.
       };
     }
 
-    @respond('@snice/table/data')
+    @respond('table/data')
     async getData(params) {
       const response = await fetch(`/api/users?search=${params.search}`);
       const data = await response.json();

package/docs/components/tooltip.md

@@ -177,3 +177,136 @@ Set the `strict-positioning` attribute to disable automatic repositioning when n
 | `hide()` | -- | Hide the tooltip |
 | `toggle()` | -- | Toggle visibility |
 | `updatePosition()` | -- | Recalculate position |
+
+## Attribute-Based Tooltips (`useTooltips`)
+
+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.
+
+### Setup
+
+Call `useTooltips()` once in your app entry point. It's idempotent — safe to call multiple times.
+
+```typescript
+import { useTooltips } from 'snice';
+useTooltips();
+```
+
+### Basic Usage
+
+```html
+<button tooltip="Save changes">Save</button>
+
+<button tooltip="Below the button" style="--tooltip-position: bottom">
+  Bottom tooltip
+</button>
+
+<button tooltip="With delay" style="--tooltip-delay: 300">
+  Hover and wait
+</button>
+```
+
+### Inside Strict-Children Components
+
+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-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-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
+
+To disconnect the observer and remove all tooltip portals:
+
+```typescript
+import { cleanupTooltips } from 'snice';
+cleanupTooltips();
+```

package/docs/controllers.md

@@ -68,7 +68,7 @@ interface IController<T extends HTMLElement = HTMLElement> {
 6. Observers are set up
 7. Channel/response handlers are set up
 8. Event handlers are set up
-9. `@snice/controller-attached` event is dispatched
+9. `controller-attached` event is dispatched
 
 ### Detachment Flow
 
@@ -78,7 +78,7 @@ interface IController<T extends HTMLElement = HTMLElement> {
 4. Channel/response handlers are cleaned up
 5. Event handlers are cleaned up
 6. Controller scope is cleaned up
-7. `@snice/controller-detached` event is dispatched
+7. `controller-detached` event is dispatched
 
 ### Example with Lifecycle Logging
 
@@ -428,23 +428,12 @@ class WebSocketController implements IController {
 Listen for attachment on the element itself (the event does **not** bubble):
 
 ```typescript
-element.addEventListener('@snice/controller-attached', (e: CustomEvent) => {
+element.addEventListener('controller-attached', (e: CustomEvent) => {
   console.log('Name:', e.detail.name);           // controller name string
   console.log('Instance:', e.detail.controller);  // IController instance
 });
 ```
 
-### Via getController()
-
-```typescript
-import { getController } from 'snice';
-
-const ctrl = getController<MyController>(element);
-if (ctrl) {
-  ctrl.doSomething();
-}
-```
-
 ### Auto-Cleanup
 
 The framework automatically cleans up `@on` handlers, observers, and `@respond` handlers during detach. Manual cleanup in `detach()` is only needed for resources you manage yourself (WebSockets, intervals, manual event listeners).

package/docs/elements.md

@@ -345,7 +345,6 @@ interface PropertyOptions {
   type?: String | Number | Boolean | Array | Object | Date | BigInt | SimpleArray;
   attribute?: string | boolean;  // Custom attribute name, or false to disable attribute sync
   converter?: PropertyConverter;  // Custom converter
-  hasChanged?: (value: any, oldValue: any) => boolean;
 }
 ```
 

package/docs/events.md

@@ -381,6 +381,9 @@ interface OnOptions {
   // Timing controls
   debounce?: number;           // Debounce the handler by specified milliseconds
   throttle?: number;           // Throttle the handler by specified milliseconds
+
+  // Shadow DOM delegation
+  target?: string;             // CSS selector to target specific elements within shadow root
 }
 ```
 

package/docs/request-response.md

@@ -47,6 +47,8 @@ interface RequestOptions extends EventInit {
   discoveryTimeout?: number; // Handler discovery timeout in ms (default: 50ms)
   debounce?: number;        // Debounce requests by specified ms
   throttle?: number;        // Throttle requests by specified ms
+  // Note: `composed` is always forced to `true` (crosses shadow DOM boundaries)
+  // `bubbles` defaults to true, `cancelable` defaults to false
 }
 
 interface RespondOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "4.14.0",
+  "version": "4.16.0",
   "type": "module",
   "description": "Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.",
   "main": "dist/index.cjs",