@ds-mo/ui 9.0.0 → 9.1.0

package/dist/mcp-data/registry/panel-tools.json

@@ -0,0 +1,374 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "panel-tools",
+  "title": "PanelTools",
+  "description": "Required AppShell utility rail and persistent drawer host for the fixed set of global Search, Agents, Messages, Stacks, Activity, and Help products.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/panel-tools",
+    "source": "src/wc/components/PanelTools/PanelTools.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "specialized",
+      "status": "stable",
+      "summary": "Required AppShell utility rail and persistent drawer host for the fixed set of global Search, Agents, Messages, Stacks, Activity, and Help products.",
+      "useWhen": [
+        "Composing the required global tools region inside the application's single AppShell.",
+        "Users need to move between application-wide utilities without losing each tool's in-progress state.",
+        "Search, AI conversations, user messages, review stacks, notifications, or help content must remain available alongside route content."
+      ],
+      "avoidWhen": [
+        "The action is specific to the current page or selected content rather than globally available across the application.",
+        "The item navigates to a primary or secondary route; use PanelNav or BarNav instead.",
+        "A consumer wants to add arbitrary tools, reorder fixed tools, or repurpose a semantic tool id.",
+        "Building the mobile tools experience; future mobile AppShell composition uses a different bottom-bar and panel pattern.",
+        "PanelTools would be mounted outside the application's single AppShell."
+      ],
+      "alternatives": [
+        {
+          "when": "The action navigates to a top-level application destination.",
+          "component": "component:ds-panel-nav",
+          "reason": "PanelNav exclusively owns primary application navigation."
+        },
+        {
+          "when": "The action navigates between route sections of the active destination.",
+          "component": "component:ds-bar-nav",
+          "reason": "BarNav exclusively owns secondary route navigation."
+        },
+        {
+          "when": "Temporary contextual actions or options are needed.",
+          "component": "component:ds-menu",
+          "reason": "Menu owns transient contextual choices rather than persistent global products."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-app-shell",
+        "component:ds-panel-nav",
+        "component:ds-bar-nav"
+      ],
+      "patterns": [
+        "pattern:application-shell"
+      ],
+      "accessibility": [
+        "Provide localized accessible labels for the rail, shortcut group, and every rendered tool.",
+        "Keep Search first in the rail header and Help last in the rail footer so keyboard and visual order remain predictable.",
+        "Keep focus on the selected rail action when opening a drawer and allow normal Tab navigation into its content.",
+        "Do not trigger global shortcuts while focus is in an editable control.",
+        "Use notification dots only as supplemental unread or new-content status and never as the sole status indication.",
+        "Explain temporarily inactive tools through an accessible label or adjacent product guidance; omit unauthorized tools entirely."
+      ],
+      "states": [
+        "Search and Help are required; optional Agents, Messages, Stacks, and Activity tools are filtered by the application for authorization and entitlement.",
+        "Use only the fixed semantic tool ids and canonical order: Search, Agents, Messages, Stacks, Activity, Help; do not reorder, duplicate, or repurpose them.",
+        "Search is application-wide; Agents is user-to-AI chat; Messages is user-to-user chat; Stacks is a specialized inbox of grouped application events for review; Activity is the notification center; Help is drawer content that may link to external resources.",
+        "Only one drawer is open at a time; selecting another tool switches directly and selecting the active tool closes to rail-only mode.",
+        "The drawer starts closed, remains open across ordinary route changes, and retains every mounted tool's independent conversation, query, scroll, and work state.",
+        "When storageKey is set, persist only the last active tool in this browser and still restore the drawer closed after reload.",
+        "The application owns unread state; opening Messages, Agents, Stacks, or Activity does not automatically clear its notification dot.",
+        "If an active optional tool becomes unavailable, PanelTools closes the drawer, clears activeTool, and emits its deselection.",
+        "Use isInactive only for a temporarily unavailable visible tool; omit tools the user is not authorized to access.",
+        "The application owns slotted tool products and data while PanelTools owns rail ordering, drawer selection, open state, motion, and shell events."
+      ],
+      "responsiveBehavior": [
+        "On desktop at 1200px and wider, the open drawer reduces main-content width and uses --dimension-panel-width-sm (400px).",
+        "On tablet from 768px through 1199px, the open drawer also reduces main-content width and uses --dimension-panel-width-xs (300px).",
+        "AppShell owns the responsive drawer-width variable and fixed breakpoint policy; consumers must not hardcode alternate drawer widths.",
+        "Below 768px, do not reuse desktop PanelTools: future AppShell mobile composition uses a bottom bar for Search, Agents, Notifications, and Stacks, while Help moves into mobile primary navigation.",
+        "Keep named-slot content mounted while tools switch or the drawer closes so users can return to in-progress global work.",
+        "Use fixed drawer widths for now; do not add user resizing or width persistence."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Assign items as a JavaScript property for structured data; items-json is the string fallback.",
+          "Keep PanelTools mounted at AppShell scope across route changes and provide each product through its matching named slot."
+        ],
+        "react": [
+          "Pass the fixed item collection through the generated React wrapper and keep named-slot product content mounted at AppShell scope.",
+          "Use storageKey only for same-browser last-tool continuity; do not persist the open drawer."
+        ],
+        "angular": [
+          "Import DsPanelTools from @ds-mo/ui/angular/ds-panel-tools and bind items as a property.",
+          "Keep the component in the persistent shell layout rather than recreating it in routed page components."
+        ]
+      },
+      "references": [
+        {
+          "label": "Executable Storybook examples",
+          "path": "src/wc/components/PanelTools/PanelTools.stories.ts"
+        },
+        {
+          "label": "Framework and shell integration",
+          "path": "docs/framework-integration.md"
+        },
+        {
+          "label": "Application shell composition",
+          "path": "agent/patterns/application-shell/pattern.agent.json"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "activeTool": {
+          "type": "PanelToolsToolId | ''",
+          "resolvedType": "\"\" | \"activity\" | \"agents\" | \"help\" | \"messages\" | \"search\" | \"stacks\"",
+          "attribute": "active-tool",
+          "default": "''",
+          "required": false,
+          "mutable": true,
+          "description": "Active tool view — `search`, `agents`, `messages`, `stacks`, `activity`, or `help`."
+        },
+        "items": {
+          "type": "PanelToolsItem[]",
+          "resolvedType": "PanelToolsItem[]",
+          "default": "[]",
+          "required": false,
+          "mutable": false,
+          "description": "Rail items rendered in the right column.\nSet via JS property: `el.items = [...]`. Replace the array reference to update."
+        },
+        "itemsJson": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "items-json",
+          "default": "''",
+          "required": false,
+          "mutable": false,
+          "description": "JSON fallback for `items` — useful when framework bindings don't propagate arrays."
+        },
+        "open": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "open",
+          "default": "false",
+          "required": false,
+          "mutable": true,
+          "description": "When false, only the icon rail is shown."
+        },
+        "storageKey": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "storage-key",
+          "default": "''",
+          "required": false,
+          "mutable": false,
+          "description": "Optional localStorage key for the last active tool. The drawer always starts\nclosed; only the tool identity is restored for continuity within this browser."
+        },
+        "toolShortcutsLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "tool-shortcuts-label",
+          "default": "'Tool shortcuts'",
+          "required": false,
+          "mutable": false
+        },
+        "toolsLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "tools-label",
+          "default": "'Tools'",
+          "required": false,
+          "mutable": false
+        }
+      },
+      "events": [
+        {
+          "name": "dsChromeTransitionEnd",
+          "detail": "ChromeTransitionDetail",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        },
+        {
+          "name": "dsChromeTransitionStart",
+          "detail": "ChromeTransitionDetail",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Bubbling lifecycle — `ds-bar-nav` defers overflow checks during drawer motion."
+        },
+        {
+          "name": "dsToolChange",
+          "detail": "{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Emitted when a rail button is toggled. Detail = { id, selected }."
+        }
+      ],
+      "methods": [
+        {
+          "name": "activateTool",
+          "signature": "activateTool(id: PanelToolsToolId) => Promise<void>",
+          "description": "Toggle any rail tool open/closed — shell shortcuts K/A/S/M/N call this."
+        },
+        {
+          "name": "closeDrawer",
+          "signature": "closeDrawer() => Promise<void>",
+          "description": "Close the tools drawer when open — used by shell keyboard shortcuts."
+        }
+      ],
+      "slots": []
+    },
+    "props": {
+      "activeTool": {
+        "type": "PanelToolsToolId | ''",
+        "resolvedType": "\"\" | \"activity\" | \"agents\" | \"help\" | \"messages\" | \"search\" | \"stacks\"",
+        "attribute": "active-tool",
+        "default": "''",
+        "required": false,
+        "mutable": true,
+        "description": "Active tool view — `search`, `agents`, `messages`, `stacks`, `activity`, or `help`."
+      },
+      "items": {
+        "type": "PanelToolsItem[]",
+        "resolvedType": "PanelToolsItem[]",
+        "default": "[]",
+        "required": false,
+        "mutable": false,
+        "description": "Rail items rendered in the right column.\nSet via JS property: `el.items = [...]`. Replace the array reference to update."
+      },
+      "itemsJson": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "items-json",
+        "default": "''",
+        "required": false,
+        "mutable": false,
+        "description": "JSON fallback for `items` — useful when framework bindings don't propagate arrays."
+      },
+      "open": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "open",
+        "default": "false",
+        "required": false,
+        "mutable": true,
+        "description": "When false, only the icon rail is shown."
+      },
+      "storageKey": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "storage-key",
+        "default": "''",
+        "required": false,
+        "mutable": false,
+        "description": "Optional localStorage key for the last active tool. The drawer always starts\nclosed; only the tool identity is restored for continuity within this browser."
+      },
+      "toolShortcutsLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "tool-shortcuts-label",
+        "default": "'Tool shortcuts'",
+        "required": false,
+        "mutable": false
+      },
+      "toolsLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "tools-label",
+        "default": "'Tools'",
+        "required": false,
+        "mutable": false
+      }
+    },
+    "events": [
+      {
+        "name": "dsChromeTransitionEnd",
+        "detail": "ChromeTransitionDetail",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      },
+      {
+        "name": "dsChromeTransitionStart",
+        "detail": "ChromeTransitionDetail",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Bubbling lifecycle — `ds-bar-nav` defers overflow checks during drawer motion."
+      },
+      {
+        "name": "dsToolChange",
+        "detail": "{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Emitted when a rail button is toggled. Detail = { id, selected }."
+      }
+    ],
+    "methods": [
+      {
+        "name": "activateTool",
+        "signature": "activateTool(id: PanelToolsToolId) => Promise<void>",
+        "description": "Toggle any rail tool open/closed — shell shortcuts K/A/S/M/N call this."
+      },
+      {
+        "name": "closeDrawer",
+        "signature": "closeDrawer() => Promise<void>",
+        "description": "Close the tools drawer when open — used by shell keyboard shortcuts."
+      }
+    ],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-panel-tools",
+      "react": "DsPanelTools",
+      "angular": "DsPanelTools"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-panel-tools.js';",
+        "example": "<ds-panel-tools></ds-panel-tools>"
+      },
+      "react": {
+        "import": "import { DsPanelTools } from '@ds-mo/ui/react';",
+        "example": "<DsPanelTools />"
+      },
+      "angular": {
+        "import": "import { DsPanelTools } from '@ds-mo/ui/angular/ds-panel-tools';",
+        "example": "<ds-panel-tools></ds-panel-tools>"
+      },
+      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: items.",
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.2.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [
+    "button-unfilled",
+    "text",
+    "tooltip"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/PanelTools/PanelTools.css",
+      "content": ":host {\n  display: block;\n  flex: 0 0 auto;\n  box-sizing: border-box;\n  height: 100%;\n  min-height: 0;\n  overflow: hidden;\n  --_panel-tools-rail-width: var(--dimension-size-600);\n  --_panel-tools-drawer-width: var(\n    --ds-shell-panel-tools-width,\n    var(--dimension-panel-width-sm)\n  );\n  --_panel-tools-border: var(--dimension-stroke-width-012, 1px) solid var(--color-border-tertiary);\n  --_panel-tools-surface-bg: var(--color-background-secondary);\n  /* Match panel-nav expand timing (medium-1); easing differs by direction. */\n  --_panel-tools-expand-dur: var(--effect-animation-duration-medium-1, 300ms);\n}\n\n.panel-tools__layout {\n  display: flex;\n  flex-direction: row-reverse;\n  align-items: stretch;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n}\n\n/* Clip frame — only max-width animates (slide reveal, same as pre-rail :host). */\n.panel-tools__drawer {\n  flex: 0 0 auto;\n  max-width: 0;\n  min-width: 0;\n  height: 100%;\n  min-height: 0;\n  overflow: hidden;\n  box-sizing: border-box;\n  transition: none;\n}\n\n:host(.panel-tools--ready) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in-out, ease);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-out, ease-out);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in, ease-in);\n}\n\n:host(.panel-tools--open) .panel-tools__drawer {\n  max-width: var(--_panel-tools-drawer-width);\n}\n\n.panel-tools__drawer--visible {\n  border-left: var(--_panel-tools-border);\n}\n\n/* Fixed-width surface — AppShell supplies 400px desktop / 300px tablet tokens. */\n.panel-tools__drawer-surface {\n  display: flex;\n  flex-direction: column;\n  width: var(--_panel-tools-drawer-width);\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  background-color: var(--_panel-tools-surface-bg);\n}\n\n/* Shell-owned chrome (bg + wash) — drawer + rail are transparent frames. */\n:host-context(ds-app-shell:not([gradient-preset='none'])) .panel-tools__drawer-surface,\n:host-context(ds-app-shell:not([gradient-preset='none'])) .panel-tools__rail {\n  background-color: transparent;\n}\n\n/* Aligns with ds-bar-nav row — same height, inset, border, and title token. */\n.panel-tools__header {\n  flex: 0 0 auto;\n  display: flex;\n  align-items: center;\n  height: var(--dimension-size-600);\n  padding: var(--dimension-space-100);\n  border-bottom: var(--_panel-tools-border);\n  color: var(--color-foreground-primary);\n  box-sizing: border-box;\n  -webkit-user-select: none;\n  user-select: none;\n}\n\n/*\n * Drawer title — match rail action height (size-400) and BarNav heading inset.\n * Use `ds-text.` so scoped specificity beats Text's `:host(.ds-text--inline-box)`\n * (class-only `.panel-tools__title` ties and loses when Text CSS loads later).\n */\nds-text.panel-tools__title {\n  display: inline-flex;\n  align-items: center;\n  height: var(--dimension-size-400);\n  padding-inline: var(--dimension-space-100);\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n/*\n * Fade title + slot body with the drawer slide (same dur/easing).\n * Header border stays opaque — only inner content opacity animates.\n */\nds-text.panel-tools__title,\n.panel-tools__body {\n  opacity: 0;\n  transition: none;\n}\n\n:host(.panel-tools--ready) ds-text.panel-tools__title,\n:host(.panel-tools--ready) .panel-tools__body {\n  transition: opacity var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in-out, ease);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-opening) ds-text.panel-tools__title,\n:host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__body {\n  transition: opacity var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-out, ease-out);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-closing) ds-text.panel-tools__title,\n:host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__body {\n  transition: opacity var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in, ease-in);\n}\n\n:host(.panel-tools--open) ds-text.panel-tools__title,\n:host(.panel-tools--open) .panel-tools__body {\n  opacity: 1;\n}\n\n.panel-tools__body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n  position: relative;\n}\n\n/* Skip paint while fully closed; cleared during open/close motion for WYSIWYG slide. */\n:host(.panel-tools--drawer-resting) .panel-tools__body {\n  content-visibility: auto;\n  contain-intrinsic-size: auto 200px;\n}\n\n.panel-tools__view {\n  display: none;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  padding: var(--dimension-space-200);\n  color: var(--color-foreground-secondary);\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n}\n\n.panel-tools__view ::slotted(*) {\n  margin: 0;\n  color: var(--color-foreground-secondary);\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n}\n\n.panel-tools__view--active {\n  display: block;\n}\n\n/* Rail — mirrors collapsed panel-nav width, padding, and item rhythm. */\n.panel-tools__rail {\n  flex: 0 0 var(--_panel-tools-rail-width);\n  width: var(--_panel-tools-rail-width);\n  min-width: var(--_panel-tools-rail-width);\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  height: 100%;\n  min-height: 0;\n  border-left: var(--_panel-tools-border);\n  background-color: var(--_panel-tools-surface-bg);\n}\n\n.panel-tools__rail-header {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  height: var(--dimension-size-600);\n  padding: var(--dimension-space-100);\n  flex-shrink: 0;\n  box-sizing: border-box;\n  border-bottom: var(--_panel-tools-border);\n}\n\n.panel-tools__rail-body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow-y: auto;\n  overflow-x: hidden;\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  padding: var(--dimension-space-100);\n  box-sizing: border-box;\n  scrollbar-width: none;\n}\n\n.panel-tools__rail-body::-webkit-scrollbar {\n  display: none;\n}\n\n/* Flush to the bottom of the rail — mirrors Search header pin. */\n.panel-tools__rail-footer {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  margin-top: auto;\n  padding: var(--dimension-space-100);\n  box-sizing: border-box;\n}\n\n.panel-tools__rail-action {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 100%;\n  height: var(--dimension-size-400);\n  flex-shrink: 0;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  :host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__drawer,\n  :host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__drawer,\n  :host(.panel-tools--ready.panel-tools--motion-opening) ds-text.panel-tools__title,\n  :host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__body,\n  :host(.panel-tools--ready.panel-tools--motion-closing) ds-text.panel-tools__title,\n  :host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__body {\n    transition: none;\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/PanelTools/PanelTools.tsx",
+      "content": "import { Component, Prop, Event, EventEmitter, Element, State, Watch, Method, h, Host } from '@stencil/core';\nimport type { ChromeTransitionDetail } from '../../shell/chrome-transition';\nimport {\n  PANEL_TOOLS_FOOTER_TOOL_ID,\n  PANEL_TOOLS_LABELS,\n  PANEL_TOOLS_PRIMARY_TOOL_ID,\n  PANEL_TOOLS_SHORTCUTS,\n  type PanelToolsItem,\n  type PanelToolsToolId,\n} from './panel-tools-types';\nimport {\n  isPanelToolsToolId,\n  orderPanelToolsItems,\n  parsePanelToolsItems,\n  panelToolsDrawerResting,\n  panelToolsDrawerTransitionMs,\n  reconcilePanelToolsAvailability,\n  resolvePanelToolActivation,\n} from './panel-tools-utils';\n\n@Component({\n  tag: 'ds-panel-tools',\n  styleUrl: 'PanelTools.css',\n  scoped: true,\n})\nexport class PanelTools {\n  @Element() el!: HTMLElement;\n\n  /** When false, only the icon rail is shown. */\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n\n  /** Active tool view — `search`, `agents`, `messages`, `stacks`, `activity`, or `help`. */\n  @Prop({ mutable: true, attribute: 'active-tool', reflect: true })\n  activeTool: PanelToolsToolId | '' = '';\n\n  /**\n   * Rail items rendered in the right column.\n   * Set via JS property: `el.items = [...]`. Replace the array reference to update.\n   */\n  @Prop() items: PanelToolsItem[] = [];\n\n  /** JSON fallback for `items` — useful when framework bindings don't propagate arrays. */\n  @Prop({ attribute: 'items-json' }) itemsJson: string = '';\n  @Prop() toolsLabel: string = 'Tools';\n  @Prop() toolShortcutsLabel: string = 'Tool shortcuts';\n\n  /**\n   * Optional localStorage key for the last active tool. The drawer always starts\n   * closed; only the tool identity is restored for continuity within this browser.\n   */\n  @Prop({ attribute: 'storage-key' }) storageKey: string = '';\n\n  /** Emitted when a rail button is toggled. Detail = { id, selected }. */\n  @Event({ bubbles: true, composed: true }) dsToolChange!: EventEmitter<{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }>;\n\n  /** Bubbling lifecycle — `ds-bar-nav` defers overflow checks during drawer motion. */\n  @Event({ bubbles: true, composed: true })\n  dsChromeTransitionStart!: EventEmitter<ChromeTransitionDetail>;\n\n  @Event({ bubbles: true, composed: true })\n  dsChromeTransitionEnd!: EventEmitter<ChromeTransitionDetail>;\n\n  /** Arms open vs close easing for the in-flight width transition. */\n  @State() private motion: 'opening' | 'closing' | 'idle' = 'idle';\n\n  /** Suppresses width transition until the host has painted its initial open state. */\n  @State() private readyForMotion = false;\n\n  @State() private rovingIndex = 0;\n\n  private motionEnableGeneration = 0;\n  private transitionGeneration = 0;\n  private transitionFallbackTimer: number | null = null;\n  /** Ignores the old transition's terminal event when reversing direction. */\n  private ignoreReplacementTerminal = false;\n\n  private get railItems(): PanelToolsItem[] {\n    return parsePanelToolsItems(this.items, this.itemsJson);\n  }\n\n  private get orderedRailItems(): PanelToolsItem[] {\n    const railItems = orderPanelToolsItems(this.railItems);\n    const headerItem = railItems.find(item => item.id === PANEL_TOOLS_PRIMARY_TOOL_ID);\n    const footerItem = railItems.find(item => item.id === PANEL_TOOLS_FOOTER_TOOL_ID);\n    const bodyItems = railItems.filter(\n      item => item.id !== PANEL_TOOLS_PRIMARY_TOOL_ID && item.id !== PANEL_TOOLS_FOOTER_TOOL_ID,\n    );\n    const ordered: PanelToolsItem[] = [];\n    if (headerItem) ordered.push(headerItem);\n    ordered.push(...bodyItems);\n    if (footerItem) ordered.push(footerItem);\n    return ordered;\n  }\n\n  disconnectedCallback() {\n    this.el.removeEventListener('transitionend', this.handleTransitionEnd);\n    this.el.removeEventListener('transitioncancel', this.handleTransitionEnd);\n    this.clearTransitionCompletion();\n    this.motionEnableGeneration += 1;\n  }\n\n  private deferMotionEnable() {\n    if (this.readyForMotion) return;\n    const generation = ++this.motionEnableGeneration;\n    requestAnimationFrame(() => {\n      if (generation !== this.motionEnableGeneration) return;\n      requestAnimationFrame(() => {\n        if (generation !== this.motionEnableGeneration) return;\n        this.readyForMotion = true;\n      });\n    });\n  }\n\n  connectedCallback() {\n    this.el.addEventListener('transitionend', this.handleTransitionEnd);\n    this.el.addEventListener('transitioncancel', this.handleTransitionEnd);\n  }\n\n  componentWillLoad() {\n    this.restoreLastActiveTool();\n  }\n\n  @Watch('open')\n  openChanged(isOpen: boolean, wasOpen?: boolean) {\n    if (this.readyForMotion && wasOpen !== undefined && wasOpen !== isOpen) {\n      this.startDrawerTransition(isOpen ? 'opening' : 'closing');\n    }\n    this.deferMotionEnable();\n  }\n\n  @Watch('activeTool')\n  activeToolChanged() {\n    this.persistLastActiveTool();\n    this.deferMotionEnable();\n  }\n\n  @Watch('storageKey')\n  storageKeyChanged() {\n    this.restoreLastActiveTool();\n  }\n\n  componentDidLoad() {\n    this.deferMotionEnable();\n  }\n\n  @Watch('items')\n  @Watch('itemsJson')\n  itemsChanged() {\n    this.rovingIndex = 0;\n    this.reconcileActiveTool();\n    this.deferMotionEnable();\n  }\n\n  private restoreLastActiveTool() {\n    if (!this.storageKey || this.activeTool) return;\n    try {\n      const stored = localStorage.getItem(this.storageKey);\n      if (isPanelToolsToolId(stored)) this.activeTool = stored;\n    } catch { /* localStorage unavailable */ }\n  }\n\n  private persistLastActiveTool() {\n    if (!this.storageKey || !this.activeTool) return;\n    try { localStorage.setItem(this.storageKey, this.activeTool); } catch { /* unavailable */ }\n  }\n\n  private clearPersistedTool() {\n    if (!this.storageKey) return;\n    try { localStorage.removeItem(this.storageKey); } catch { /* unavailable */ }\n  }\n\n  private reconcileActiveTool() {\n    const next = reconcilePanelToolsAvailability(this.railItems, this.open, this.activeTool);\n    if (!next.removedTool) return;\n    this.clearPersistedTool();\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id: next.removedTool, selected: false });\n  }\n\n  private startDrawerTransition(phase: 'opening' | 'closing') {\n    const drawer = this.el.querySelector('.panel-tools__drawer') as HTMLElement | null;\n    const widthBefore = drawer?.getBoundingClientRect().width ?? 0;\n    if (this.motion !== 'idle') {\n      this.finishDrawerTransition();\n      this.ignoreReplacementTerminal = true;\n    }\n    this.motion = phase;\n    this.dsChromeTransitionStart.emit({ source: 'panel-tools', phase });\n    const generation = ++this.transitionGeneration;\n\n    requestAnimationFrame(() => {\n      requestAnimationFrame(() => {\n        if (generation !== this.transitionGeneration || this.motion !== phase) return;\n        if (!drawer) {\n          this.finishDrawerTransition();\n          return;\n        }\n\n        const widthAfter = drawer.getBoundingClientRect().width;\n        if (Math.abs(widthAfter - widthBefore) < 1) {\n          this.finishDrawerTransition();\n          return;\n        }\n\n        const fallbackMs = panelToolsDrawerTransitionMs(getComputedStyle(drawer));\n        if (fallbackMs <= 0) {\n          this.finishDrawerTransition();\n          return;\n        }\n        this.transitionFallbackTimer = window.setTimeout(() => {\n          this.finishDrawerTransition();\n        }, fallbackMs);\n      });\n    });\n  }\n\n  private handleTransitionEnd = (event: TransitionEvent) => {\n    if (event.target !== this.el.querySelector('.panel-tools__drawer')) return;\n    if (event.propertyName !== 'max-width') return;\n    if (this.ignoreReplacementTerminal) {\n      this.ignoreReplacementTerminal = false;\n      return;\n    }\n    this.finishDrawerTransition();\n  };\n\n  private finishDrawerTransition() {\n    const wasTransitioning = this.motion !== 'idle';\n    this.clearTransitionCompletion();\n    if (!wasTransitioning) return;\n    this.ignoreReplacementTerminal = false;\n    this.motion = 'idle';\n    this.dsChromeTransitionEnd.emit({ source: 'panel-tools' });\n  }\n\n  private clearTransitionCompletion() {\n    this.transitionGeneration += 1;\n    if (this.transitionFallbackTimer !== null) {\n      window.clearTimeout(this.transitionFallbackTimer);\n      this.transitionFallbackTimer = null;\n    }\n  }\n\n  /** Rail selection follows `open` immediately — independent of the slide animation. */\n  private isRailSelected(id: PanelToolsToolId): boolean {\n    return this.open && this.activeTool === id;\n  }\n\n  /** Drawer body stays mounted while the clip frame animates closed. */\n  private isDrawerPresent(): boolean {\n    return this.open || this.motion === 'closing';\n  }\n\n  private isViewActive(id: PanelToolsToolId): boolean {\n    return this.isDrawerPresent() && this.activeTool === id;\n  }\n\n  private headerLabel(): string {\n    if (!this.isDrawerPresent() || !this.activeTool) return '';\n    return PANEL_TOOLS_LABELS[this.activeTool as PanelToolsToolId] ?? '';\n  }\n\n  private handleToolChange = (id: PanelToolsToolId) => {\n    const next = resolvePanelToolActivation(this.open, this.activeTool, id);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id, selected: next.selected });\n  };\n\n  /** Toggle any rail tool open/closed — shell shortcuts K/A/S/M/N call this. */\n  @Method()\n  async activateTool(id: PanelToolsToolId) {\n    const item = this.railItems.find(entry => entry.id === id);\n    if (!item || item.isInactive) return;\n    this.handleToolChange(id);\n  }\n\n  /** Close the tools drawer when open — used by shell keyboard shortcuts. */\n  @Method()\n  async closeDrawer() {\n    if (!this.open) return;\n    const id = this.activeTool;\n    this.open = false;\n    if (id) {\n      this.dsToolChange.emit({ id, selected: false });\n    }\n  }\n\n  private focusRailAt(index: number) {\n    const items = this.orderedRailItems;\n    if (!items.length) return;\n    const bounded = Math.max(0, Math.min(index, items.length - 1));\n    if (bounded === this.rovingIndex) return;\n    this.rovingIndex = bounded;\n    const actions = Array.from(\n      this.el.querySelectorAll<HTMLElement>('.panel-tools__rail-action .button-icon'),\n    );\n    actions[bounded]?.focus({ preventScroll: true });\n  }\n\n  private handleRailKeyDown = (e: KeyboardEvent, index: number) => {\n    const items = this.orderedRailItems;\n    if (!items.length) return;\n\n    if (e.key === 'Enter' || e.key === ' ') {\n      e.preventDefault();\n      this.handleToolChange(items[index].id);\n      return;\n    }\n\n    if (e.key === 'ArrowDown') {\n      if (index >= items.length - 1) return;\n      e.preventDefault();\n      this.focusRailAt(index + 1);\n      return;\n    }\n\n    if (e.key === 'ArrowUp') {\n      if (index <= 0) return;\n      e.preventDefault();\n      this.focusRailAt(index - 1);\n    }\n  };\n\n  private renderRailAction(item: PanelToolsItem, index: number) {\n    const label = item.ariaLabel ?? PANEL_TOOLS_LABELS[item.id];\n    return (\n      <ds-tooltip\n        key={item.id}\n        label={label}\n        shortcutKey={PANEL_TOOLS_SHORTCUTS[item.id]}\n        side=\"left\"\n        size=\"sm\"\n      >\n        <ds-button-unfilled variant=\"icon\"\n          class=\"panel-tools__rail-action\"\n          icon={item.icon}\n          isActive={this.isRailSelected(item.id)}\n          activeFill={false}\n          hasBorder={false}\n          dot={item.dot ?? false}\n          isInactive={item.isInactive}\n          focusTabIndex={index === this.rovingIndex ? 0 : -1}\n          aria-label={label}\n          pressed={this.isRailSelected(item.id)}\n          onFocusin={() => { this.rovingIndex = index; }}\n          onKeyDown={(e: KeyboardEvent) => this.handleRailKeyDown(e, index)}\n          onDsClick={() => this.handleToolChange(item.id)}\n        />\n      </ds-tooltip>\n    );\n  }\n\n  render() {\n    const headerLabel = this.headerLabel();\n    const orderedRailItems = this.orderedRailItems;\n    const headerItem = orderedRailItems.find(item => item.id === PANEL_TOOLS_PRIMARY_TOOL_ID);\n    const footerItem = orderedRailItems.find(item => item.id === PANEL_TOOLS_FOOTER_TOOL_ID);\n    const bodyItems = orderedRailItems.filter(\n      item => item.id !== PANEL_TOOLS_PRIMARY_TOOL_ID && item.id !== PANEL_TOOLS_FOOTER_TOOL_ID,\n    );\n    const footerIndex = footerItem\n      ? (headerItem ? 1 : 0) + bodyItems.length\n      : -1;\n    const showDrawerChrome = this.isDrawerPresent();\n    const drawerResting = panelToolsDrawerResting(this.open, this.motion);\n\n    return (\n      <Host\n        class={{\n          'panel-tools': true,\n          'panel-tools--open': this.open,\n          'panel-tools--ready': this.readyForMotion,\n          'panel-tools--motion-opening': this.motion === 'opening',\n          'panel-tools--motion-closing': this.motion === 'closing',\n          'panel-tools--drawer-resting': drawerResting,\n        }}\n        role=\"complementary\"\n        aria-label={this.toolsLabel}\n      >\n        <div class=\"panel-tools__layout\">\n          <nav class=\"panel-tools__rail\" aria-label={this.toolShortcutsLabel}>\n            {headerItem ? (\n              <div class=\"panel-tools__rail-header\">\n                {this.renderRailAction(headerItem, 0)}\n              </div>\n            ) : null}\n            <div class=\"panel-tools__rail-body\">\n              {bodyItems.map((item, bodyIdx) =>\n                this.renderRailAction(item, headerItem ? bodyIdx + 1 : bodyIdx),\n              )}\n            </div>\n            {footerItem ? (\n              <div class=\"panel-tools__rail-footer\">\n                {this.renderRailAction(footerItem, footerIndex)}\n              </div>\n            ) : null}\n          </nav>\n\n          <div\n            class={{\n              'panel-tools__drawer': true,\n              'panel-tools__drawer--visible': showDrawerChrome,\n            }}\n            aria-hidden={showDrawerChrome ? null : 'true'}\n            inert={showDrawerChrome ? undefined : true}\n          >\n            <div class=\"panel-tools__drawer-surface\">\n              <header class=\"panel-tools__header\">\n                <ds-text\n                  class=\"panel-tools__title\"\n                  as=\"span\"\n                  variant=\"text-body-medium\"\n                  emphasis\n                  color=\"primary\"\n                  wrap=\"nowrap\"\n                >\n                  {headerLabel}\n                </ds-text>\n              </header>\n              <div class=\"panel-tools__body\">\n                <div\n                  class={{\n                    'panel-tools__view': true,\n                    'panel-tools__view--active': this.isViewActive('search'),\n                  }}\n                  hidden={!this.isViewActive('search')}\n                >\n                  <slot name=\"search\" />\n                </div>\n                <div\n                  class={{\n                    'panel-tools__view': true,\n                    'panel-tools__view--active': this.isViewActive('messages'),\n                  }}\n                  hidden={!this.isViewActive('messages')}\n                >\n                  <slot name=\"messages\" />\n                </div>\n                <div\n                  class={{\n                    'panel-tools__view': true,\n                    'panel-tools__view--active': this.isViewActive('stacks'),\n                  }}\n                  hidden={!this.isViewActive('stacks')}\n                >\n                  <slot name=\"stacks\" />\n                </div>\n                <div\n                  class={{\n                    'panel-tools__view': true,\n                    'panel-tools__view--active': this.isViewActive('activity'),\n                  }}\n                  hidden={!this.isViewActive('activity')}\n                >\n                  <slot name=\"activity\" />\n                </div>\n                <div\n                  class={{\n                    'panel-tools__view': true,\n                    'panel-tools__view--active': this.isViewActive('agents'),\n                  }}\n                  hidden={!this.isViewActive('agents')}\n                >\n                  <slot name=\"agents\" />\n                </div>\n                <div\n                  class={{\n                    'panel-tools__view': true,\n                    'panel-tools__view--active': this.isViewActive('help'),\n                  }}\n                  hidden={!this.isViewActive('help')}\n                >\n                  <slot name=\"help\" />\n                </div>\n              </div>\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/PanelTools/panel-tools-types.ts",
+      "content": "/** Tool ids for the `ds-panel-tools` rail and drawer views. */\nexport type PanelToolsToolId =\n  | 'search'\n  | 'agents'\n  | 'messages'\n  | 'stacks'\n  | 'activity'\n  | 'help';\n\nexport const PANEL_TOOLS_TOOL_IDS: PanelToolsToolId[] = [\n  'search',\n  'agents',\n  'messages',\n  'stacks',\n  'activity',\n  'help',\n];\n\n/** Rail header slot — mirrors panel-nav M logo row. */\nexport const PANEL_TOOLS_PRIMARY_TOOL_ID: PanelToolsToolId = 'search';\n\n/** Rail footer slot — flush to the bottom of the tools column. */\nexport const PANEL_TOOLS_FOOTER_TOOL_ID: PanelToolsToolId = 'help';\n\nexport const PANEL_TOOLS_LABELS: Record<PanelToolsToolId, string> = {\n  search: 'Search',\n  messages: 'Messages',\n  stacks: 'Stacks',\n  activity: 'Activity',\n  agents: 'Agents',\n  help: 'Help & Support',\n};\n\nexport const PANEL_TOOLS_SHORTCUTS: Partial<Record<PanelToolsToolId, string>> = {\n  search: 'K',\n  agents: 'A',\n  messages: 'M',\n  stacks: 'S',\n  activity: 'N',\n  help: '?',\n};\n\nexport interface PanelToolsItem {\n  id: PanelToolsToolId;\n  /** Icon name for <ds-icon>. */\n  icon: string;\n  /** Whether this rail button is currently pressed/active. */\n  selected?: boolean;\n  /** Show a notification dot. */\n  dot?: boolean;\n  isInactive?: boolean;\n  ariaLabel?: string;\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/PanelTools/panel-tools-utils.ts",
+      "content": "import { parseJsonArrayProp } from '../BarNav/bar-nav-utils';\nimport { parseCssTimeMs } from '../../utils/resolve-css-time-ms';\nimport {\n  PANEL_TOOLS_TOOL_IDS,\n  type PanelToolsItem,\n  type PanelToolsToolId,\n} from './panel-tools-types';\n\nexport function parsePanelToolsItems(\n  items: PanelToolsItem[],\n  itemsJson: string,\n): PanelToolsItem[] {\n  if (itemsJson) {\n    return parseJsonArrayProp<PanelToolsItem>(itemsJson, []);\n  }\n  return items ?? [];\n}\n\nexport function orderPanelToolsItems(items: PanelToolsItem[]): PanelToolsItem[] {\n  const firstById = new Map<PanelToolsToolId, PanelToolsItem>();\n  for (const item of items) {\n    if (!firstById.has(item.id)) firstById.set(item.id, item);\n  }\n  return PANEL_TOOLS_TOOL_IDS.flatMap(id => {\n    const item = firstById.get(id);\n    return item ? [item] : [];\n  });\n}\n\nexport function isPanelToolsToolId(value: string | null): value is PanelToolsToolId {\n  return value !== null && PANEL_TOOLS_TOOL_IDS.includes(value as PanelToolsToolId);\n}\n\nexport function reconcilePanelToolsAvailability(\n  items: PanelToolsItem[],\n  open: boolean,\n  activeTool: PanelToolsToolId | '',\n): { open: boolean; activeTool: PanelToolsToolId | ''; removedTool: PanelToolsToolId | '' } {\n  if (!activeTool || items.some(item => item.id === activeTool)) {\n    return { open, activeTool, removedTool: '' };\n  }\n  return { open: false, activeTool: '', removedTool: activeTool };\n}\n\nexport function shouldResyncPanelToolsItems(\n  prev: PanelToolsItem[],\n  next: PanelToolsItem[],\n): boolean {\n  if (prev.length !== next.length) return true;\n  return next.some((item, index) => {\n    const prior = prev[index];\n    if (!prior) return true;\n    return (\n      prior.id !== item.id ||\n      prior.icon !== item.icon ||\n      prior.selected !== item.selected ||\n      prior.dot !== item.dot ||\n      prior.isInactive !== item.isInactive ||\n      prior.ariaLabel !== item.ariaLabel\n    );\n  });\n}\n\nexport type PanelToolsMotion = 'opening' | 'closing' | 'idle';\n\nexport interface PanelToolsTransitionStyle {\n  transitionProperty: string;\n  transitionDuration: string;\n  transitionDelay: string;\n}\n\n/** Maximum computed time for the drawer's max-width transition, including delay. */\nexport function panelToolsDrawerTransitionMs(style: PanelToolsTransitionStyle): number {\n  const properties = style.transitionProperty.split(',').map(item => item.trim());\n  const durations = style.transitionDuration.split(',').map(item => parseCssTimeMs(item.trim(), 0));\n  const delays = style.transitionDelay.split(',').map(item => parseCssTimeMs(item.trim(), 0));\n\n  return properties.reduce((max, property, index) => {\n    if (property !== 'all' && property !== 'max-width') return max;\n    const duration = durations[index % durations.length] ?? 0;\n    const delay = delays[index % delays.length] ?? 0;\n    return Math.max(max, duration + delay, 0);\n  }, 0);\n}\n\n/** True when the drawer clip is fully closed — safe to skip painting slot content. */\nexport function panelToolsDrawerResting(open: boolean, motion: PanelToolsMotion): boolean {\n  return !open && motion === 'idle';\n}\n\n/** Toggle or switch rail tool selection — repeat activation closes the active tool. */\nexport function resolvePanelToolActivation(\n  open: boolean,\n  activeTool: PanelToolsToolId | '',\n  id: PanelToolsToolId,\n): { open: boolean; activeTool: PanelToolsToolId; selected: boolean } {\n  if (open && activeTool === id) {\n    return { open: false, activeTool: id, selected: false };\n  }\n  return { open: true, activeTool: id, selected: true };\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}