@ds-mo/ui 14.27.1 → 14.29.0

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

@@ -91,7 +91,8 @@
         "The application owns slotted tool products and data while PanelTools owns rail ordering, drawer selection, open state, motion, and shell events.",
         "Opening and closing clip an already-rendered fixed-width surface. Header and tool content remain fully opaque and retained during width motion; transition completion is accepted only at the measured terminal clip width, after which the closed surface becomes inert and paint-skipped.",
         "Entering and exiting fullscreen snaps without borrowing the drawer open or close animation.",
-        "When fullscreenHeaderMode is split, PanelTools suppresses only its fullscreen shared header. The application renders exactly two canonical ds-panel-tool-header instances: a tool-title/list-actions header over the 300px history pane and a chat-title/Exit-fullscreen/chat-actions header over the detail pane. The detail header omits Back because the list remains visible."
+        "When fullscreenHeaderMode is split, PanelTools suppresses only its fullscreen shared header. The application renders exactly two canonical ds-panel-tool-header instances: a tool-title/list-actions header over the 300px history pane and a chat-title/Exit-fullscreen/chat-actions header over the detail pane. The detail header omits Back because the list remains visible.",
+        "Header action surfaceOpen identifies the owner of an external menu or panel without turning that action into a selected tool or toggle. The application owns this surface lifecycle."
       ],
       "responsiveBehavior": [
         "The open drawer reduces main-content width and uses --dimension-panel-width-xs (300px) on every supported desktop and tablet viewport.",
@@ -130,6 +131,10 @@
         {
           "label": "Application shell composition",
           "path": "agent/patterns/application-shell/pattern.agent.json"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -521,7 +526,7 @@
     },
     {
       "path": "src/wc/components/PanelTools/panel-tools-types.ts",
-      "content": "/** Application-owned tool id for the shell rail and responsive tool views. */\nexport type PanelToolsToolId = string;\n\n/** Canonical Motive shell recipe used when item metadata is omitted. */\nexport type CanonicalPanelToolsToolId =\n  | 'search'\n  | 'messages'\n  | 'agents'\n  | 'stacks'\n  | 'activity'\n  | 'help';\n\nexport const PANEL_TOOLS_TOOL_IDS: CanonicalPanelToolsToolId[] = [\n  'agents',\n  'messages',\n  'activity',\n  'search',\n  'stacks',\n  'help',\n];\n\n/** Rail header slot — mirrors panel-nav M logo row. */\nexport const PANEL_TOOLS_PRIMARY_TOOL_ID: CanonicalPanelToolsToolId = 'agents';\n\n/** Rail footer slot — flush to the bottom of the tools column. */\nexport const PANEL_TOOLS_FOOTER_TOOL_ID: CanonicalPanelToolsToolId = 'help';\n\nexport const PANEL_TOOLS_LABELS: Record<CanonicalPanelToolsToolId, 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<CanonicalPanelToolsToolId, string>> = {\n  search: 'K',\n  agents: 'A',\n  messages: 'M',\n  stacks: 'S',\n  activity: 'N',\n  help: '/',\n};\n\nexport type PanelToolsRailPlacement = 'header' | 'body' | 'footer';\n\nexport interface PanelToolsItem {\n  id: PanelToolsToolId;\n  /** Icon name for <ds-icon>. */\n  icon: string;\n  /** Visible and accessible fallback label for custom tool ids. */\n  label?: string;\n  /** Explicit rail region; canonical Agents/Help placement is the fallback. */\n  railPlacement?: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order?: number;\n  /** Optional shortcut label displayed by the tooltip. */\n  shortcutKey?: string;\n  /** Mobile destination recipe; canonical ids retain their explicit defaults. */\n  mobileDestination?: 'search' | 'inbox' | 'activity' | 'messages' | 'agents' | 'help';\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\nexport type PanelToolsRailAccessoryVisual =\n  | { type: 'icon'; icon: string }\n  | { type: 'initial'; initial: string }\n  | { type: 'image'; src: string };\n\nexport interface PanelToolsRailAccessoryAction {\n  /** Stable application-owned action id emitted with the accessory id. */\n  id: string;\n  /** Overrides the accessory label for the primary action. */\n  ariaLabel?: string;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsRailAccessorySecondaryAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  isInactive?: boolean;\n}\n\nexport type PanelToolsRailTransientTone = 'active' | 'positive';\n\ninterface PanelToolsRailAccessoryBase {\n  /** Stable application-owned identity. Duplicate or blank ids are omitted. */\n  id: string;\n  /** Explicit rail region; accessories never infer placement from their id. */\n  railPlacement: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order: number;\n}\n\n/** Decorative boundary between application-owned rail accessory groups. */\nexport interface PanelToolsRailDividerAccessory extends PanelToolsRailAccessoryBase {\n  type: 'divider';\n}\n\n/**\n * A compact one-action shortcut that matches standard tool-button geometry.\n * PanelTools owns its initial orb, notification dot, and transient interaction paint.\n */\nexport interface PanelToolsRailShortcutAccessory extends PanelToolsRailAccessoryBase {\n  type: 'shortcut';\n  /** Accessible shortcut name and action-label fallback. */\n  ariaLabel: string;\n  /** One or two displayed graphemes. Longer values are truncated visually. */\n  initials: string;\n  /** Supplemental notification dot. Include its meaning in the accessible label when needed. */\n  dot?: boolean;\n  action: PanelToolsRailAccessoryAction;\n}\n\n/**\n * A direct application intent that never selects a tool or changes drawer state.\n * PanelTools owns the two-control-height surface and its focus behavior.\n */\nexport interface PanelToolsRailTransientAccessory extends PanelToolsRailAccessoryBase {\n  type: 'transient';\n  /** Accessible accessory name and primary-action fallback label. */\n  ariaLabel: string;\n  visual: PanelToolsRailAccessoryVisual;\n  /** State announced with the primary action and shown in its tooltip. */\n  statusText: string;\n  /** Bold surface treatment. Active uses brand; positive uses positive semantic color. */\n  statusTone: PanelToolsRailTransientTone;\n  primaryAction: PanelToolsRailAccessoryAction;\n  secondaryAction?: PanelToolsRailAccessorySecondaryAction;\n}\n\nexport type PanelToolsRailAccessory =\n  | PanelToolsRailDividerAccessory\n  | PanelToolsRailShortcutAccessory\n  | PanelToolsRailTransientAccessory;\n\nexport interface PanelToolsRailAccessoryActionDetail {\n  accessoryId: string;\n  actionId: string;\n  /** Rendered action control, suitable for anchoring an application-owned overlay. */\n  anchor: HTMLElement;\n}\n\n/** Canonical shell recipe used by Lab and by managed ShellApp examples. */\nexport const PANEL_TOOLS_DEFAULT_ITEMS: PanelToolsItem[] = [\n  {\n    id: 'agents',\n    icon: 'AI',\n    label: PANEL_TOOLS_LABELS.agents,\n    railPlacement: 'header',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.agents,\n    mobileDestination: 'agents',\n  },\n  {\n    id: 'messages',\n    icon: 'MessageBubbleStack',\n    label: PANEL_TOOLS_LABELS.messages,\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.messages,\n    mobileDestination: 'messages',\n  },\n  {\n    id: 'activity',\n    icon: 'Bell',\n    label: PANEL_TOOLS_LABELS.activity,\n    order: 1,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.activity,\n    mobileDestination: 'activity',\n  },\n  {\n    id: 'search',\n    icon: 'MagnifyingGlass',\n    label: PANEL_TOOLS_LABELS.search,\n    order: 2,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.search,\n    mobileDestination: 'search',\n  },\n  {\n    id: 'help',\n    icon: 'CircleQuestion',\n    label: PANEL_TOOLS_LABELS.help,\n    railPlacement: 'footer',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.help,\n    mobileDestination: 'help',\n  },\n];\n\nexport interface PanelToolsHeaderAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  triggerId?: string;\n  controls?: string;\n  expanded?: boolean;\n  haspopup?: 'menu' | 'dialog' | 'listbox' | 'tree' | 'grid';\n  pressed?: boolean;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsHeaderActionDetail {\n  tool: PanelToolsToolId;\n  id: string;\n  /** Rendered header action host. Pass this to an external overlay's element anchor prop. */\n  anchor?: HTMLElement;\n}\n\nexport interface PanelToolHeaderActionDetail {\n  id: string;\n  originalEvent: MouseEvent;\n  /** Rendered action host, suitable for anchoring an external overlay across a shadow boundary. */\n  anchor: HTMLElement;\n}\n\nexport interface PanelToolsHeaderConfig {\n  title?: string;\n  showBack?: boolean;\n  backIcon?: string;\n  backAriaLabel?: string;\n  actions?: PanelToolsHeaderAction[];\n}\n\n/** Per-tool header state. The application replaces the object when a tool changes depth or actions. */\nexport type PanelToolsHeaders = Partial<Record<PanelToolsToolId, PanelToolsHeaderConfig>>;\n",
+      "content": "/** Application-owned tool id for the shell rail and responsive tool views. */\nexport type PanelToolsToolId = string;\n\n/** Canonical Motive shell recipe used when item metadata is omitted. */\nexport type CanonicalPanelToolsToolId =\n  | 'search'\n  | 'messages'\n  | 'agents'\n  | 'stacks'\n  | 'activity'\n  | 'help';\n\nexport const PANEL_TOOLS_TOOL_IDS: CanonicalPanelToolsToolId[] = [\n  'agents',\n  'messages',\n  'activity',\n  'search',\n  'stacks',\n  'help',\n];\n\n/** Rail header slot — mirrors panel-nav M logo row. */\nexport const PANEL_TOOLS_PRIMARY_TOOL_ID: CanonicalPanelToolsToolId = 'agents';\n\n/** Rail footer slot — flush to the bottom of the tools column. */\nexport const PANEL_TOOLS_FOOTER_TOOL_ID: CanonicalPanelToolsToolId = 'help';\n\nexport const PANEL_TOOLS_LABELS: Record<CanonicalPanelToolsToolId, 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<CanonicalPanelToolsToolId, string>> = {\n  search: 'K',\n  agents: 'A',\n  messages: 'M',\n  stacks: 'S',\n  activity: 'N',\n  help: '/',\n};\n\nexport type PanelToolsRailPlacement = 'header' | 'body' | 'footer';\n\nexport interface PanelToolsItem {\n  id: PanelToolsToolId;\n  /** Icon name for <ds-icon>. */\n  icon: string;\n  /** Visible and accessible fallback label for custom tool ids. */\n  label?: string;\n  /** Explicit rail region; canonical Agents/Help placement is the fallback. */\n  railPlacement?: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order?: number;\n  /** Optional shortcut label displayed by the tooltip. */\n  shortcutKey?: string;\n  /** Mobile destination recipe; canonical ids retain their explicit defaults. */\n  mobileDestination?: 'search' | 'inbox' | 'activity' | 'messages' | 'agents' | 'help';\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\nexport type PanelToolsRailAccessoryVisual =\n  | { type: 'icon'; icon: string }\n  | { type: 'initial'; initial: string }\n  | { type: 'image'; src: string };\n\nexport interface PanelToolsRailAccessoryAction {\n  /** Stable application-owned action id emitted with the accessory id. */\n  id: string;\n  /** Overrides the accessory label for the primary action. */\n  ariaLabel?: string;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsRailAccessorySecondaryAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  isInactive?: boolean;\n}\n\nexport type PanelToolsRailTransientTone = 'active' | 'positive';\n\ninterface PanelToolsRailAccessoryBase {\n  /** Stable application-owned identity. Duplicate or blank ids are omitted. */\n  id: string;\n  /** Explicit rail region; accessories never infer placement from their id. */\n  railPlacement: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order: number;\n}\n\n/** Decorative boundary between application-owned rail accessory groups. */\nexport interface PanelToolsRailDividerAccessory extends PanelToolsRailAccessoryBase {\n  type: 'divider';\n}\n\n/**\n * A compact one-action shortcut that matches standard tool-button geometry.\n * PanelTools owns its initial orb, notification dot, and transient interaction paint.\n */\nexport interface PanelToolsRailShortcutAccessory extends PanelToolsRailAccessoryBase {\n  type: 'shortcut';\n  /** Accessible shortcut name and action-label fallback. */\n  ariaLabel: string;\n  /** One or two displayed graphemes. Longer values are truncated visually. */\n  initials: string;\n  /** Supplemental notification dot. Include its meaning in the accessible label when needed. */\n  dot?: boolean;\n  action: PanelToolsRailAccessoryAction;\n}\n\n/**\n * A direct application intent that never selects a tool or changes drawer state.\n * PanelTools owns the two-control-height surface and its focus behavior.\n */\nexport interface PanelToolsRailTransientAccessory extends PanelToolsRailAccessoryBase {\n  type: 'transient';\n  /** Accessible accessory name and primary-action fallback label. */\n  ariaLabel: string;\n  visual: PanelToolsRailAccessoryVisual;\n  /** State announced with the primary action and shown in its tooltip. */\n  statusText: string;\n  /** Bold surface treatment. Active uses brand; positive uses positive semantic color. */\n  statusTone: PanelToolsRailTransientTone;\n  primaryAction: PanelToolsRailAccessoryAction;\n  secondaryAction?: PanelToolsRailAccessorySecondaryAction;\n}\n\nexport type PanelToolsRailAccessory =\n  | PanelToolsRailDividerAccessory\n  | PanelToolsRailShortcutAccessory\n  | PanelToolsRailTransientAccessory;\n\nexport interface PanelToolsRailAccessoryActionDetail {\n  accessoryId: string;\n  actionId: string;\n  /** Rendered action control, suitable for anchoring an application-owned overlay. */\n  anchor: HTMLElement;\n}\n\n/** Canonical shell recipe used by Lab and by managed ShellApp examples. */\nexport const PANEL_TOOLS_DEFAULT_ITEMS: PanelToolsItem[] = [\n  {\n    id: 'agents',\n    icon: 'AI',\n    label: PANEL_TOOLS_LABELS.agents,\n    railPlacement: 'header',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.agents,\n    mobileDestination: 'agents',\n  },\n  {\n    id: 'messages',\n    icon: 'MessageBubbleStack',\n    label: PANEL_TOOLS_LABELS.messages,\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.messages,\n    mobileDestination: 'messages',\n  },\n  {\n    id: 'activity',\n    icon: 'Bell',\n    label: PANEL_TOOLS_LABELS.activity,\n    order: 1,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.activity,\n    mobileDestination: 'activity',\n  },\n  {\n    id: 'search',\n    icon: 'MagnifyingGlass',\n    label: PANEL_TOOLS_LABELS.search,\n    order: 2,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.search,\n    mobileDestination: 'search',\n  },\n  {\n    id: 'help',\n    icon: 'CircleQuestion',\n    label: PANEL_TOOLS_LABELS.help,\n    railPlacement: 'footer',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.help,\n    mobileDestination: 'help',\n  },\n];\n\nexport interface PanelToolsHeaderAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  triggerId?: string;\n  controls?: string;\n  expanded?: boolean;\n  /** Associated surface remains visible, including exit motion. */\n  surfaceOpen?: boolean;\n  haspopup?: 'menu' | 'dialog' | 'listbox' | 'tree' | 'grid';\n  pressed?: boolean;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsHeaderActionDetail {\n  tool: PanelToolsToolId;\n  id: string;\n  /** Rendered header action host. Pass this to an external overlay's element anchor prop. */\n  anchor?: HTMLElement;\n}\n\nexport interface PanelToolHeaderActionDetail {\n  id: string;\n  originalEvent: MouseEvent;\n  /** Rendered action host, suitable for anchoring an external overlay across a shadow boundary. */\n  anchor: HTMLElement;\n}\n\nexport interface PanelToolsHeaderConfig {\n  title?: string;\n  showBack?: boolean;\n  backIcon?: string;\n  backAriaLabel?: string;\n  actions?: PanelToolsHeaderAction[];\n}\n\n/** Per-tool header state. The application replaces the object when a tool changes depth or actions. */\nexport type PanelToolsHeaders = Partial<Record<PanelToolsToolId, PanelToolsHeaderConfig>>;\n",
       "type": "registry:ui"
     },
     {