snice 7.0.2 → 7.0.3

package/docs/components/spotlight.md

@@ -12,6 +12,7 @@ A guided tour and onboarding component that highlights elements on the page with
 - [CSS Custom Properties](#css-custom-properties)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
+- [CSS Parts](#css-parts)
 - [Accessibility](#accessibility)
 
 ## Properties
@@ -49,6 +50,7 @@ interface SpotlightStep {
 | `spotlight-step` | `{ index: number, step: SpotlightStep }` | Navigated to a new step |
 | `spotlight-end` | `void` | Tour ended (completed or ended programmatically) |
 | `spotlight-skip` | `{ index: number }` | User skipped the tour at the given step |
+| `spotlight-target-missing` | `{ index: number, step: SpotlightStep }` | A step's target element is no longer in the DOM (e.g. a route change removed it). The popover stops rather than pointing at nothing. |
 
 ## CSS Custom Properties
 

package/docs/components/tabs.md

@@ -13,6 +13,7 @@ A tabbed interface for organizing content into separate panels, using `<snice-ta
 - [Slots](#slots)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
+- [CSS Custom Properties](#css-custom-properties)
 - [Examples](#examples)
 
 ## Components

package/docs/components/terminal.md

@@ -37,6 +37,9 @@ A shell terminal emulator with command execution, history navigation, and ANSI c
 | `focus()` | -- | Focus the input |
 | `getHistory()` | -- | Get command history, returns `string[]` |
 | `clearHistory()` | -- | Clear command history |
+| `appendChunk()` | `chunk: string, type?: TerminalLineType` | Feed a raw chunk without splitting on newlines; a trailing partial line stays live and grows as more chunks arrive |
+| `pipeFrom()` | `source: AsyncIterable<string> \| ReadableStream<string \| Uint8Array>, type?: TerminalLineType` | Stream a source to the terminal until it ends. Returns `Promise<void>` |
+| `commitLiveLine()` | -- | Force the current live (un-newlined) buffer to be treated as a finished line |
 
 ## Events
 

package/docs/components/textarea.md

@@ -49,7 +49,7 @@ A multi-line text input with validation, character counting, and optional auto-g
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `focus()` | `options?: FocusOptions` | Focus the textarea |
+| `focus()` | -- | Focus the textarea |
 | `blur()` | -- | Remove focus |
 | `select()` | -- | Select all text |
 | `checkValidity()` | -- | Check validation, returns `boolean` |

package/docs/components/time-picker.md

@@ -4,6 +4,20 @@
 
 `<snice-time-picker>` is an editable, form-associated time control with 12-hour and 24-hour displays, dropdown or inline selectors, optional seconds, range and step constraints, native reset and restoration, and constraint validation.
 
+## Table of Contents
+
+- [Basic usage](#basic-usage)
+- [Time and form-value contract](#time-and-form-value-contract)
+- [Live value and reset default](#live-value-and-reset-default)
+- [Native form lifecycle](#native-form-lifecycle)
+- [External labels and accessible naming](#external-labels-and-accessible-naming)
+- [Validation](#validation)
+- [Display and interaction](#display-and-interaction)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS parts](#css-parts)
+
 ## Basic usage
 
 ```ts

package/docs/components/tooltip.md

@@ -12,6 +12,7 @@ Provides contextual information when users hover, click, or focus an element. Su
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
+- [CSS Custom Properties](#css-custom-properties)
 - [Attribute-Based Tooltips](#attribute-based-tooltips)
 
 ## Properties
@@ -231,6 +232,7 @@ This is the primary use case -- adding tooltips without disrupting component str
 | `--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-arrow-size` | `6px` | Arrow width and height |
 | `--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 auto-flip |

package/docs/components/tree.md

@@ -24,8 +24,8 @@ Displays hierarchical data with expandable/collapsible nodes, selection, checkbo
 | `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 |
+| `selectedNodes` | `string[]` | `[]` | Selected node IDs (JS-only; no attribute) |
+| `checkedNodes` | `string[]` | `[]` | Checked node IDs (JS-only; no attribute) |
 
 ### TreeNode Interface
 

package/docs/events.md

@@ -7,6 +7,7 @@ Event handling in Snice provides two powerful approaches: **template event synta
 - [Template Event Syntax (Preferred for Elements)](#template-event-syntax-preferred-for-elements)
 - [@on Decorator](#on-decorator)
 - [@dispatch Decorator](#dispatch-decorator)
+- [Event Bus](#event-bus)
 - [Custom Events](#custom-events)
 - [Event Delegation](#event-delegation)
 - [Keyboard Shortcuts](#keyboard-shortcuts)
@@ -715,6 +716,78 @@ class ColorPicker extends HTMLElement {
 }
 ```
 
+## Event Bus
+
+Snice has no bus object and no singleton. A bus is `@dispatch` publishing upward and
+`@on` subscribing at a chosen ancestor -- the scope is a DOM node, so it is created and
+torn down with the DOM.
+
+There are two ways to publish, and the choice decides who can hear it.
+
+**Bubble up from the host.** `@dispatch` is `bubbles: true, composed: true` by default, so
+the event crosses shadow boundaries and passes every ancestor on its way to `document`.
+Use this when the event is about *this* element and ancestors may care.
+
+```typescript
+@element('product-tile')
+class ProductTile extends HTMLElement {
+  @dispatch('bus:cart-added')
+  addToCart(sku: string) {
+    return { sku, qty: 1 };
+  }
+}
+```
+
+**Dispatch directly on a scope.** `@dispatch` takes the same `scope` option as `@on`, which
+fires the event *on* that target instead of bubbling from the host. Use this when the
+subscriber is not an ancestor -- a sibling subtree, or a host that may be detached.
+
+```typescript
+@dispatch('bus:cart-added', { scope: 'global' })   // dispatched on document
+add(id: string) { return { id }; }
+```
+
+Subscribe at the scope you want to share.
+
+```typescript
+// App-wide: listens on document
+@on('bus:cart-added', { scope: 'global' })
+onCartAdded(e: CustomEvent) { /* ... */ }
+
+// Feature-scoped: listens on the nearest <cart-shell> ancestor, so a second
+// <cart-shell> elsewhere on the page keeps its own traffic
+@on('bus:cart-added', { scope: 'cart-shell' })
+onCartAdded(e: CustomEvent) { /* ... */ }
+```
+
+Choosing a scope:
+
+| Reach | `scope` | Use when |
+|---|---|---|
+| Whole document | `'global'` | Genuinely app-wide: auth expiry, theme change, save shortcut |
+| A feature subtree | selector string | The event belongs to one shell and must not leak to a sibling instance |
+| A specific node | `EventTarget` / resolver | You already hold the node, or the target moves and must re-resolve |
+
+Prefer the narrowest scope that works. `'global'` means every instance on the page hears
+every message, which is what makes singleton buses hard to reason about.
+
+Match the two halves. A bubbling publish only reaches subscribers that sit on the host's
+ancestor chain; if the subscriber lives in a sibling subtree, scope the dispatch too so
+both meet on the same node. See
+[scope on @dispatch](#scope-controlling-the-dispatch-target).
+
+Name events so the routing is visible at the call site -- the `bus:` prefix above is a
+convention, not a framework feature. Any string works.
+
+Teardown is automatic: the listener is removed on disconnect from whichever target it
+resolved to, and re-resolved on reconnect, so subscribers follow the host when it moves.
+If a selector scope matches no ancestor the listener is skipped with a `console.warn`
+rather than silently binding to the wrong node. See
+[scope](#scope-controlling-the-listener-target) for the full resolution table.
+
+For a request that needs an answer rather than a broadcast, use
+[@request / @respond](./request-response.md) instead.
+
 ## Custom Events
 
 ### Dispatching Manually

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "7.0.2",
+  "version": "7.0.3",
   "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",