@adia-ai/web-components 0.4.8 → 0.5.0

package/USAGE.md

@@ -166,11 +166,46 @@ function MinLSlider({ minL, onMinLChange }) {
 <slider-ui value={minL * 100} on:change={e => minL = e.detail.value / 100}></slider-ui>
 ```
 
+### Derived reactive bindings
+
+When the value you want to render is a **transformation of a signal** — e.g. you store `0..1` but the slider displays `0..100`, or the displayed text is `${count} items` — pass a **function** as the binding. The template engine detects functions and wraps them in an `effect()`, so the binding re-evaluates whenever any signal read inside the function changes.
+
+```js
+// ✅ Derived reactive — re-evaluates whenever minL changes
+html`<slider-ui .value=${() => minL.value * 100} min="0" max="100" />`
+
+// ✅ Direct signal — re-evaluates whenever minL changes
+html`<slider-ui .value=${minL} min="0" max="1" step="0.01" />`
+
+// ❌ Static snapshot — reads minL.value ONCE at render time; thumb never moves
+html`<slider-ui .value=${minL.value * 100} />`
+
+// ❌ Function as the value, not a binding — slider receives the function object, not its result
+html`<slider-ui .value=${(v) => v * 100} />`
+```
+
+The rule: **inside `.prop=${…}`, anything that reads `.value` directly is a snapshot. Wrap in `() => …` to get reactivity.**
+
+For more complex derived values, `computed()` gives you a named reactive holder you can pass directly or read in templates:
+
+```js
+import { signal, computed, html } from '@adia-ai/web-components/core';
+
+const minL = signal(0.4);
+const displayPct = computed(() => Math.round(minL.value * 100));
+
+html`<slider-ui .value=${displayPct} />`        // ✅ pass the computed signal direct
+html`<text-ui>${displayPct}</text-ui>`           // ✅ same in text bindings
+html`<text-ui>${() => `${displayPct.value}%`}</text-ui>`  // ✅ function form with template literal
+```
+
+`computed()` memoizes (re-runs only when its dependencies change) and gives you a stable handle you can pass to multiple bindings without re-instantiating the effect at every render.
+
 ### The eager-evaluation trap
 
 Reported real-world bug: a consumer wrote `.value=${signal.value * 100}` and reported "the slider doesn't move on undo." The slider IS reactive; the binding pattern wasn't. `signal.value * 100` evaluates eagerly to a number; the template system never sees the signal, so it can't subscribe.
 
-**Fix:** pass `${signal}` (signal direct) or `${() => signal.value * 100}` (function as value). Both get effect-wrapped.
+**Fix:** pass `${signal}` (signal direct) or `${() => signal.value * 100}` (function as value). Both get effect-wrapped. See the "Derived reactive bindings" section above for the full pattern.
 
 ---
 
@@ -218,7 +253,7 @@ Some primitives emit named events beyond `change`/`input`:
 - `<select-ui>` — emits `action` for option-callbacks with `detail.action`
 - `<search-ui>` — emits `search` after debounce with `detail.value`
 - `<chat-composer>` — emits `composer-submit` on Enter with `detail.value`
-- `<color-picker-ui>` — emits multiple typed events (`input`, `change`, `format-change`) with structured detail
+- `<color-picker-ui>` — emits `input` + `change` with rich detail (`{ value, l, c, h, hex, oklch }`)
 
 Each primitive's yaml lists its complete event surface. Live demos at `https://ui-kit.exe.xyz/site/components/<name>`.
 
@@ -226,6 +261,90 @@ Each primitive's yaml lists its complete event surface. Live demos at `https://u
 
 All standard events bubble. Internal-routing collisions (e.g. a trait listening for an event then re-emitting one with the same name) are avoided by name discipline — see the `event-name-collision` memory entry for the lesson.
 
+### Authoring events in yaml (for contributors)
+
+> *This subsection is for contributors authoring new primitives or extending an existing primitive's event surface. If you're a consumer integrating AdiaUI, skip ahead.*
+
+Each component's `<name>.yaml` declares its event surface in a top-level `events:` block. The build pipeline (`npm run build:components`) carries that block into `<name>.a2ui.json` under `x-adiaui.events`, and v0.4.8 §80 codegen reads it from there to emit typed `addEventListener` overloads + `CustomEvent<X>` aliases in `<name>.d.ts`. **The yaml is the single source of truth**; the sidecar + `.d.ts` regenerate from it.
+
+#### When to add an `events:` entry
+
+Whenever your primitive's `class.js` calls `this.dispatchEvent(new CustomEvent('NAME', ...))` or `new Event('NAME', ...)`, the yaml needs a matching entry. The `check-form-bearing-dts.mjs` audit (v0.5.0-staged) catches drift between dispatch literals and `.d.ts` typings; populating yaml correctly prevents that drift.
+
+#### The shape
+
+```yaml
+events:
+  open:
+    description: Fired when the modal becomes visible.
+    detail:
+      trigger:
+        type: string
+        description: One of 'click' | 'keyboard' | 'programmatic'.
+  close:
+    description: Fired when the modal is dismissed.
+    # No detail block → CustomEvent<unknown> at the .d.ts surface.
+  toggle:
+    description: Fired when state flips.
+    detail:
+      open:
+        type: boolean
+        description: New open state after the toggle.
+    bubbles: false   # default is true; set false only for non-bubbling events
+```
+
+#### What ends up where
+
+For a yaml entry like the `toggle` event above on `<my-thing-ui>`:
+
+| Surface | Shape |
+|---|---|
+| `<my-thing-ui>.a2ui.json` | `x-adiaui.events.toggle = { description, detail: { open: { type, description } }, bubbles? }` |
+| `<my-thing-ui>.d.ts` (codegen) | `interface MyThingToggleEventDetail { open: boolean; }` + `type MyThingToggleEvent = CustomEvent<MyThingToggleEventDetail>` + `addEventListener` overload for `'toggle'` |
+| Runtime | `this.dispatchEvent(new CustomEvent('toggle', { detail: { open: this.open }, bubbles: true }))` |
+
+#### Detail-key types
+
+The codegen recognizes these `type:` values inside a detail key:
+
+| yaml `type:` | TS emitted |
+|---|---|
+| `string` | `string` |
+| `number` / `integer` | `number` |
+| `boolean` | `boolean` |
+| `object` | `Record<string, unknown>` |
+| `array` | `unknown[]` |
+| missing | `unknown` |
+
+If you need a string-literal union, declare via `enum: [a, b, c]` and the codegen emits `'a' | 'b' | 'c'`.
+
+#### Worked example: `<modal-ui>` close
+
+Yaml at `packages/web-components/components/modal/modal.yaml`:
+
+```yaml
+events:
+  close:
+    description: Fires when the modal is dismissed (backdrop click, Escape, programmatic hide()).
+```
+
+Sidecar after `npm run build:components`:
+
+```json
+{ "x-adiaui": { "events": { "close": { "description": "Fires when the modal is dismissed..." } } } }
+```
+
+Emitted `.d.ts` after `npm run codegen:dts`:
+
+```ts
+export type ModalCloseEvent = CustomEvent<unknown>;
+export class UIModal extends UIElement {
+  addEventListener(type: 'close', listener: (ev: ModalCloseEvent) => unknown, options?: ...): void;
+}
+```
+
+Reference: [`docs/conventions/component-events.md`](../../docs/conventions/component-events.md) for the 1-page convention summary; [`scripts/build/dts-codegen.mjs`](../../scripts/build/dts-codegen.mjs) for the codegen logic that reads `x-adiaui.events`; [`scripts/release/check-form-bearing-dts.mjs`](../../scripts/release/check-form-bearing-dts.mjs) for the drift audit.
+
 ---
 
 ## Form participation
@@ -592,6 +711,140 @@ Properties are installed by `installProps()` in `super()`, but the host's render
 
 ---
 
+## Worked examples
+
+Migrations from common custom-helper shapes to AdiaUI primitives. Each example pairs a real consumer's pre-AdiaUI helper with the equivalent AdiaUI declaration.
+
+### Replace a hand-rolled color-token swatch with `<swatch-ui>` (v0.4.9+)
+
+Pre-v0.4.9, design-token tools commonly hand-rolled a `renderSwatch()` helper composing: background color, key label, gamut badge (sRGB / P3 markers), APCA contrast badge, copy-to-clipboard button, light/dark auto-contrast label, keyboard select. v0.4.9 extends `<swatch-ui>` with all six surfaces — the helper collapses to one declarative tag.
+
+```diff
+- // Pre — 70 LOC helper
+- function renderSwatch({ color, label, detail, gamutBadge, copyValue, selected, onSelect }) {
+-   const el = document.createElement('div')
+-   el.className = 'token-swatch'
+-   el.style.backgroundColor = color
+-   el.tabIndex = 0
+-   el.setAttribute('role', 'button')
+-   el.setAttribute('aria-pressed', String(selected))
+-   if (selected) el.classList.add('selected')
+-
+-   const labelEl = document.createElement('span')
+-   labelEl.className = 'swatch-label'
+-   labelEl.textContent = label
+-   labelEl.style.color = isLight(color) ? 'var(--fg-dark)' : 'var(--fg-light)'
+-   el.appendChild(labelEl)
+-
+-   const detailEl = document.createElement('span')
+-   detailEl.className = 'swatch-detail'
+-   detailEl.textContent = detail
+-   el.appendChild(detailEl)
+-
+-   if (gamutBadge) {
+-     const badge = document.createElement('span')
+-     badge.className = 'swatch-badge'
+-     badge.textContent = gamutBadge === 'out-of-gamut' ? '△' : '✦'
+-     badge.setAttribute('aria-label', gamutBadge)
+-     el.appendChild(badge)
+-   }
+-
+-   const copyBtn = document.createElement('button')
+-   copyBtn.className = 'swatch-copy'
+-   copyBtn.textContent = '⧉'
+-   copyBtn.setAttribute('aria-label', `Copy ${copyValue}`)
+-   copyBtn.addEventListener('click', async (e) => {
+-     e.stopPropagation()
+-     try { await navigator.clipboard.writeText(copyValue); copyBtn.textContent = '✓' }
+-     catch { copyBtn.textContent = '⚠' }
+-     setTimeout(() => { copyBtn.textContent = '⧉' }, 1200)
+-   })
+-   el.appendChild(copyBtn)
+-
+-   el.addEventListener('click', (e) => {
+-     if (e.target === copyBtn) return
+-     onSelect({ color, label })
+-   })
+-   el.addEventListener('keydown', (e) => {
+-     if (e.key !== 'Enter' && e.key !== ' ') return
+-     if (e.target === copyBtn) return
+-     e.preventDefault()
+-     onSelect({ color, label })
+-   })
+-
+-   return el
+- }
+
++ // Post — one declarative tag
++ html`<swatch-ui
++   shape="block" size="lg"
++   color=${color}
++   label=${label}
++   detail=${detail}
++   badge=${gamutBadge}
++   copyable
++   copy-value=${copyValue}
++   selectable
++   ?selected=${selected}
++   auto-contrast
++   @select=${(e) => onSelect({ color: e.detail.color, label: e.detail.label })}
++ ></swatch-ui>`
+```
+
+The primitive owns: badge symbol + ARIA mapping, copy-clipboard state machine (⧉ → ✓ / ⚠ → ⧉ after 1.2s), `role="button"` + `tabindex="0"` only when `[selectable]`, focus ring on `:focus-visible` + always-on when `[selected]`, click-on-copy-doesn't-toggle-selection guard, label auto-contrast via OKLCH luminance (when `[auto-contrast]` is set).
+
+The `select` event detail is `{ value, color, label }` — `value` is `[color]` (or `[label]` as fallback) so consumers binding to a value-shaped select handler get the canonical accessor uniformly across form-bearing primitives.
+
+For multiple simultaneous badges (e.g. both `out-of-gamut` and `apca-fail`), pass a comma-separated list: `badge="out-of-gamut, apca-fail"` — v0.4.9 renders both stacked in the upper-right.
+
+### Guard global keyboard shortcuts with `isFocusInInput()` (v0.4.8+)
+
+```diff
+- // Pre — manual cast boilerplate at every shortcut site
+- document.addEventListener('keydown', (e) => {
+-   const active = document.activeElement as HTMLElement | null
+-   if (active && (
+-     active.tagName === 'INPUT' ||
+-     active.tagName === 'TEXTAREA' ||
+-     active.isContentEditable
+-   )) return
+-   if (e.key === '/') openCommandPalette()
+- })
+
++ // Post — one import + one call
++ import { isFocusInInput } from '@adia-ai/web-modules/editor'
++
++ document.addEventListener('keydown', (e) => {
++   if (isFocusInInput()) return
++   if (e.key === '/') openCommandPalette()
++ })
+```
+
+`isFocusInInput()` also recognizes AdiaUI text-input primitives (`<input-ui>`, `<textarea-ui>`, `<otp-input-ui>`, `<search-ui>`) by host tag-name — important because focus may land on the custom-element host before the inner native input mounts.
+
+### Use derived reactive bindings for unit-conversion (v0.4.6+)
+
+```diff
+- // Pre — eager evaluation; slider doesn't move on undo
+- <slider-ui .value=${minL.value * 100} min="0" max="100" step="1"></slider-ui>
+
++ // Post — function-as-value gets effect-wrapped
++ <slider-ui .value=${() => minL.value * 100} min="0" max="100" step="1"></slider-ui>
+```
+
+The function re-runs on every dependency mutation. Same pattern works for derived computations (e.g. `() => clamp(minL.value * 100, 0, 100)`) and signal-array transforms.
+
+### Persist `<editor-sidebar>` width across reloads (v0.4.9+)
+
+```diff
+- <editor-sidebar collapsible name="dts-layout">
++ <editor-sidebar collapsible persist="dts-layout">
+```
+
+`[persist]` is the preferred name in v0.4.9+. `[name]` keeps working (back-compat alias; deprecated, not scheduled for v0.5.x removal). Storage namespace + `sidebar-toggle` event detail are unchanged.
+
+---
+
 ## More
 
 - [`README.md`](./README.md) — package overview + authoring guide

package/components/action-list/action-list.a2ui.json

@@ -29,7 +29,21 @@
     ],
     "events": {
       "action": {
-        "description": "Fired on action."
+        "description": "Fired on action.",
+        "detail": {
+          "item": {
+            "description": "The triggering list-item element.",
+            "type": "object"
+          },
+          "text": {
+            "description": "Item text content or [text] attribute.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Item value attribute (preferred over text for stable IDs).",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/action-list/action-list.d.ts

@@ -12,7 +12,16 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type ActionListActionEvent = CustomEvent<unknown>;
+export interface ActionListActionEventDetail {
+  /** The triggering list-item element. */
+  item: Record<string, unknown>;
+  /** Item text content or [text] attribute. */
+  text: string;
+  /** Item value attribute (preferred over text for stable IDs). */
+  value: string;
+}
+
+export type ActionListActionEvent = CustomEvent<ActionListActionEventDetail>;
 
 export class UIActionList extends UIElement {
 

package/components/action-list/action-list.yaml

@@ -16,6 +16,16 @@ props: {}
 events:
   action:
     description: "Fired on action."
+    detail:
+      value:
+        type: string
+        description: Item value attribute (preferred over text for stable IDs).
+      text:
+        type: string
+        description: Item text content or [text] attribute.
+      item:
+        type: object
+        description: The triggering list-item element.
 slots:
   default (action-item-ui children):
     description: "Child content region for the `default (action-item-ui children)` slot."

package/components/agent-artifact/agent-artifact.a2ui.json

@@ -55,7 +55,13 @@
     ],
     "events": {
       "artifact-toggle": {
-        "description": "Fired on artifact-toggle."
+        "description": "Fired on artifact-toggle.",
+        "detail": {
+          "collapsed": {
+            "description": "New collapsed state after the toggle.",
+            "type": "boolean"
+          }
+        }
       }
     },
     "examples": [

package/components/agent-artifact/agent-artifact.d.ts

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AgentArtifactArtifactToggleEvent = CustomEvent<unknown>;
+export interface AgentArtifactArtifactToggleEventDetail {
+  /** New collapsed state after the toggle. */
+  collapsed: boolean;
+}
+
+export type AgentArtifactArtifactToggleEvent = CustomEvent<AgentArtifactArtifactToggleEventDetail>;
 
 export class UIAgentArtifact extends UIElement {
   /** Header title. */

package/components/agent-artifact/agent-artifact.yaml

@@ -36,6 +36,10 @@ props:
 events:
   artifact-toggle:
     description: "Fired on artifact-toggle."
+    detail:
+      collapsed:
+        type: boolean
+        description: New collapsed state after the toggle.
 slots:
   default:
     description: "Default slot — primary child content."

package/components/agent-feedback-bar/agent-feedback-bar.a2ui.json

@@ -44,7 +44,13 @@
     ],
     "events": {
       "feedback-rate": {
-        "description": "Fired on feedback-rate."
+        "description": "Fired on feedback-rate.",
+        "detail": {
+          "rating": {
+            "description": "Rating value selected by the user.",
+            "type": "number"
+          }
+        }
       },
       "feedback-save": {
         "description": "Fired on feedback-save."

package/components/agent-feedback-bar/agent-feedback-bar.d.ts

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AgentFeedbackBarFeedbackRateEvent = CustomEvent<unknown>;
+export interface AgentFeedbackBarFeedbackRateEventDetail {
+  /** Rating value selected by the user. */
+  rating: number;
+}
+
+export type AgentFeedbackBarFeedbackRateEvent = CustomEvent<AgentFeedbackBarFeedbackRateEventDetail>;
 export type AgentFeedbackBarFeedbackSaveEvent = CustomEvent<unknown>;
 
 export class UIAgentFeedbackBar extends UIElement {

package/components/agent-feedback-bar/agent-feedback-bar.yaml

@@ -30,6 +30,10 @@ props:
 events:
   feedback-rate:
     description: "Fired on feedback-rate."
+    detail:
+      rating:
+        type: number
+        description: Rating value selected by the user.
   feedback-save:
     description: "Fired on feedback-save."
 slots:

package/components/agent-questions/agent-questions.a2ui.json

@@ -49,7 +49,17 @@
     ],
     "events": {
       "questions-answer": {
-        "description": "Fired on questions-answer."
+        "description": "Fired on questions-answer.",
+        "detail": {
+          "option": {
+            "description": "The full selected option object.",
+            "type": "object"
+          },
+          "selected": {
+            "description": "Array of selected option IDs.",
+            "type": "array"
+          }
+        }
       }
     },
     "examples": [

package/components/agent-questions/agent-questions.d.ts

@@ -12,7 +12,14 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AgentQuestionsQuestionsAnswerEvent = CustomEvent<unknown>;
+export interface AgentQuestionsQuestionsAnswerEventDetail {
+  /** The full selected option object. */
+  option: Record<string, unknown>;
+  /** Array of selected option IDs. */
+  selected: unknown[];
+}
+
+export type AgentQuestionsQuestionsAnswerEvent = CustomEvent<AgentQuestionsQuestionsAnswerEventDetail>;
 
 export class UIAgentQuestions extends UIElement {
   /** Helper text. */

package/components/agent-questions/agent-questions.yaml

@@ -32,6 +32,13 @@ props:
 events:
   questions-answer:
     description: "Fired on questions-answer."
+    detail:
+      selected:
+        type: array
+        description: Array of selected option IDs.
+      option:
+        type: object
+        description: The full selected option object.
 slots:
   default:
     description: "Default slot — primary child content."

package/components/agent-reasoning/agent-reasoning.a2ui.json

@@ -56,13 +56,35 @@
     ],
     "events": {
       "reasoning-finish": {
-        "description": "Fired on reasoning-finish."
+        "description": "Fired on reasoning-finish.",
+        "detail": {
+          "status": {
+            "description": "Whether reasoning was resolved.",
+            "type": "boolean"
+          },
+          "summary": {
+            "description": "Summary label text rendered after finish.",
+            "type": "string"
+          }
+        }
       },
       "reasoning-step-toggle": {
-        "description": "Fired on reasoning-step-toggle."
+        "description": "Fired on reasoning-step-toggle.",
+        "detail": {
+          "stepId": {
+            "description": "ID of the toggled reasoning step (matches data-step-id).",
+            "type": "string"
+          }
+        }
       },
       "reasoning-toggle": {
-        "description": "Fired on reasoning-toggle."
+        "description": "Fired on reasoning-toggle.",
+        "detail": {
+          "collapsed": {
+            "description": "Whether the reasoning section is now collapsed.",
+            "type": "boolean"
+          }
+        }
       }
     },
     "examples": [

package/components/agent-reasoning/agent-reasoning.d.ts

@@ -12,9 +12,26 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AgentReasoningReasoningFinishEvent = CustomEvent<unknown>;
-export type AgentReasoningReasoningStepToggleEvent = CustomEvent<unknown>;
-export type AgentReasoningReasoningToggleEvent = CustomEvent<unknown>;
+export interface AgentReasoningReasoningFinishEventDetail {
+  /** Whether reasoning was resolved. */
+  status: boolean;
+  /** Summary label text rendered after finish. */
+  summary: string;
+}
+
+export type AgentReasoningReasoningFinishEvent = CustomEvent<AgentReasoningReasoningFinishEventDetail>;
+export interface AgentReasoningReasoningStepToggleEventDetail {
+  /** ID of the toggled reasoning step (matches data-step-id). */
+  stepId: string;
+}
+
+export type AgentReasoningReasoningStepToggleEvent = CustomEvent<AgentReasoningReasoningStepToggleEventDetail>;
+export interface AgentReasoningReasoningToggleEventDetail {
+  /** Whether the reasoning section is now collapsed. */
+  collapsed: boolean;
+}
+
+export type AgentReasoningReasoningToggleEvent = CustomEvent<AgentReasoningReasoningToggleEventDetail>;
 
 export class UIAgentReasoning extends UIElement {
   /** Start collapsed. */

package/components/agent-reasoning/agent-reasoning.yaml

@@ -35,10 +35,25 @@ props:
 events:
   reasoning-finish:
     description: "Fired on reasoning-finish."
+    detail:
+      summary:
+        type: string
+        description: Summary label text rendered after finish.
+      status:
+        type: boolean
+        description: Whether reasoning was resolved.
   reasoning-step-toggle:
     description: "Fired on reasoning-step-toggle."
+    detail:
+      stepId:
+        type: string
+        description: ID of the toggled reasoning step (matches data-step-id).
   reasoning-toggle:
     description: "Fired on reasoning-toggle."
+    detail:
+      collapsed:
+        type: boolean
+        description: Whether the reasoning section is now collapsed.
 slots:
   default:
     description: "Default slot — primary child content."

package/components/agent-suggestions/agent-suggestions.a2ui.json

@@ -44,7 +44,21 @@
     ],
     "events": {
       "suggestion-select": {
-        "description": "Fired on suggestion-select."
+        "description": "Fired on suggestion-select.",
+        "detail": {
+          "index": {
+            "description": "Index of the selected suggestion.",
+            "type": "number"
+          },
+          "label": {
+            "description": "Suggestion label text.",
+            "type": "string"
+          },
+          "prompt": {
+            "description": "Suggestion prompt content.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/agent-suggestions/agent-suggestions.d.ts

@@ -12,7 +12,16 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AgentSuggestionsSuggestionSelectEvent = CustomEvent<unknown>;
+export interface AgentSuggestionsSuggestionSelectEventDetail {
+  /** Index of the selected suggestion. */
+  index: number;
+  /** Suggestion label text. */
+  label: string;
+  /** Suggestion prompt content. */
+  prompt: string;
+}
+
+export type AgentSuggestionsSuggestionSelectEvent = CustomEvent<AgentSuggestionsSuggestionSelectEventDetail>;
 
 export class UIAgentSuggestions extends UIElement {
   /** Disable all chips. */

package/components/agent-suggestions/agent-suggestions.yaml

@@ -28,6 +28,16 @@ props:
 events:
   suggestion-select:
     description: "Fired on suggestion-select."
+    detail:
+      label:
+        type: string
+        description: Suggestion label text.
+      prompt:
+        type: string
+        description: Suggestion prompt content.
+      index:
+        type: number
+        description: Index of the selected suggestion.
 slots:
   default:
     description: "Default slot — primary child content."

package/components/agent-trace/agent-trace.a2ui.json

@@ -37,7 +37,13 @@
     "composes": [],
     "events": {
       "trace-toggle": {
-        "description": "Fired on trace-toggle."
+        "description": "Fired on trace-toggle.",
+        "detail": {
+          "collapsed": {
+            "description": "Whether the trace is now collapsed.",
+            "type": "boolean"
+          }
+        }
       }
     },
     "examples": [