@ds-mo/ui 9.0.0 → 9.1.0

package/dist/mcp-data/registry/app-shell.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "app-shell",
+  "title": "AppShell",
+  "description": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/app-shell",
+    "source": "src/wc/components/AppShell/AppShell.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "specialized",
+      "status": "stable",
+      "summary": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
+      "useWhen": [
+        "Building any standard authenticated product or workspace page with CompoMo.",
+        "PanelNav, BarNav, PanelTools, page content, shared chrome, responsive behavior, and shell shortcuts must be composed as one application frame.",
+        "Future application templates need the supported base-page composition boundary."
+      ],
+      "avoidWhen": [
+        "Building authentication, onboarding, public, marketing, print, error, or intentionally focused full-screen experiences that require a different layout.",
+        "Another AppShell already exists in the page; applications must render exactly one and must never nest AppShells.",
+        "Building content inside an existing AppShell; render the page content rather than another shell."
+      ],
+      "commonlyComposedWith": [
+        "component:ds-panel-nav",
+        "component:ds-bar-nav",
+        "component:ds-panel-tools",
+        "component:ds-swatch-picker"
+      ],
+      "patterns": [
+        "pattern:application-shell"
+      ],
+      "accessibility": [
+        "Keep primary destinations in PanelNav and secondary route sections in BarNav.",
+        "Ensure the default content region contains the page's single main landmark.",
+        "Keep PanelNav, BarNav, and PanelTools chrome available in the shell's supported desktop and tablet compositions.",
+        "Do not override browser keyboard chords when enabling shell shortcuts.",
+        "Require Search and Help as the minimum PanelTools actions and provide accessible labels for every tool.",
+        "Preserve focus and accessible names across navigation, collapse, overflow, and responsive presentation changes."
+      ],
+      "states": [
+        "Render exactly one AppShell as the workspace root and never nest it.",
+        "PanelNav, BarNav, and PanelTools are required shell regions; PanelTools contains at least Search and Help even when no additional product tools apply.",
+        "The application router owns the current route, authorization filtering, Dashboard or Settings context, destination collections, section collections, and localized content labels.",
+        "AppShell propagates navStyle and coordinates layout, gradient alignment, transitions, metrics, shortcuts, and responsive composition.",
+        "Set gradientPreset to the single resolved global chrome preference: neutral by default, none for solid chrome, or cool, neutral, warm, and fresh for token-based washes.",
+        "The application owns gradient preference persistence, cross-tab synchronization, and server or account precedence; AppShell owns rendering the resolved preset across authenticated routes.",
+        "Dashboard represents day-to-day operational work while Settings represents administrative and configuration work; route state selects the context.",
+        "Update PanelNav groups, BarNav tabs and heading, navStyle, basePath, and currentUrl atomically from one resolved route state.",
+        "BarNav remains present: it shows route-section tabs when available and the active PanelNav destination label as heading otherwise.",
+        "The application filters unauthorized destinations, sections, and tools before passing them into shell components."
+      ],
+      "responsiveBehavior": [
+        "AppShell owns the fixed system breakpoints and resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
+        "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
+        "On tablet, AppShell keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
+        "On mobile, AppShell remains the page root but replaces PanelNav and desktop navigation composition with a future dedicated mobile navigation design.",
+        "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
+        "The current runtime does not yet implement the complete desktop, tablet, and mobile composition contract; consuming applications must enforce missing breakpoint behavior until AppShell provides it."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Assign complex navigation and tool collections as JavaScript properties on the slotted components.",
+          "Stamp route-derived nav-style before components connect when deterministic first paint is required."
+        ],
+        "react": [
+          "Use generated wrappers and preserve native slot names for PanelNav, BarNav, PanelTools, and main content.",
+          "Resolve all shell inputs from one router state before rendering the composition."
+        ],
+        "angular": [
+          "Use generated standalone adapters and preserve slot attributes in templates.",
+          "Bind complex inputs as properties and update navigation inputs atomically from one resolved router state.",
+          "Bind both nav-style attributes and properties when deterministic first paint is required."
+        ]
+      },
+      "references": [
+        {
+          "label": "Component guide",
+          "path": "src/wc/components/AppShell/AppShell.mdx"
+        },
+        {
+          "label": "Executable Storybook composition",
+          "path": "src/wc/components/AppShell/AppShell.stories.ts"
+        },
+        {
+          "label": "Framework integration",
+          "path": "docs/framework-integration.md"
+        },
+        {
+          "label": "Application shell contract",
+          "path": "agent/patterns/application-shell/pattern.agent.json"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "gradientPreset": {
+          "type": "ShellGradientPreset",
+          "resolvedType": "\"cool\" | \"fresh\" | \"neutral\" | \"none\" | \"warm\"",
+          "attribute": "gradient-preset",
+          "default": "'neutral'",
+          "required": false,
+          "mutable": false,
+          "description": "Shell chrome wash preset. `none` renders solid chrome; the remaining\npresets use token-based washes that adapt to the active color theme."
+        },
+        "navStyle": {
+          "type": "NavChromeStyle",
+          "resolvedType": "\"dashboard\" | \"settings\"",
+          "attribute": "nav-style",
+          "default": "'dashboard'",
+          "required": false,
+          "mutable": false,
+          "description": "Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`."
+        },
+        "shortcutsEnabled": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "shortcuts-enabled",
+          "default": "true",
+          "required": false,
+          "mutable": false,
+          "description": "When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K/A/S/M/N/? toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "gradientPreset": {
+        "type": "ShellGradientPreset",
+        "resolvedType": "\"cool\" | \"fresh\" | \"neutral\" | \"none\" | \"warm\"",
+        "attribute": "gradient-preset",
+        "default": "'neutral'",
+        "required": false,
+        "mutable": false,
+        "description": "Shell chrome wash preset. `none` renders solid chrome; the remaining\npresets use token-based washes that adapt to the active color theme."
+      },
+      "navStyle": {
+        "type": "NavChromeStyle",
+        "resolvedType": "\"dashboard\" | \"settings\"",
+        "attribute": "nav-style",
+        "default": "'dashboard'",
+        "required": false,
+        "mutable": false,
+        "description": "Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`."
+      },
+      "shortcutsEnabled": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "shortcuts-enabled",
+        "default": "true",
+        "required": false,
+        "mutable": false,
+        "description": "When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K/A/S/M/N/? toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-app-shell",
+      "react": "DsAppShell",
+      "angular": "DsAppShell"
+    },
+    "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-app-shell.js';",
+        "example": "<ds-app-shell></ds-app-shell>"
+      },
+      "react": {
+        "import": "import { DsAppShell } from '@ds-mo/ui/react';",
+        "example": "<DsAppShell />"
+      },
+      "angular": {
+        "import": "import { DsAppShell } from '@ds-mo/ui/angular/ds-app-shell';",
+        "example": "<ds-app-shell></ds-app-shell>"
+      },
+      "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": [],
+  "files": [
+    {
+      "path": "src/wc/components/AppShell/AppShell.css",
+      "content": ":host {\n  display: block;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  --ds-shell-panel-tools-width: var(--dimension-panel-width-sm);\n}\n\n@media (min-width: 768px) and (max-width: 1199px) {\n  :host {\n    --ds-shell-panel-tools-width: var(--dimension-panel-width-xs);\n  }\n}\n\n.app-shell {\n  display: flex;\n  flex-direction: column;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  font-family: var(--typography-font-family, system-ui);\n}\n\n:host {\n  --_shell-chrome-bg: var(--color-background-secondary);\n}\n\n.app-shell__row {\n  display: flex;\n  flex: 1 1 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n/*\n * One chrome layer behind the shell row. Wash uses background-attachment: fixed\n * so the pattern is locked to the viewport — panel/tools collapse only changes the\n * transparent window, not the pattern phase. JS sets wash background-size from\n * readShellViewportDimensions(), not the shell element box.\n */\n.app-shell__chrome {\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  z-index: 0;\n  background-color: var(--_shell-chrome-bg);\n}\n\n:host(.app-shell--gradient) .app-shell__chrome::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  background-position: 0 0;\n  background-attachment: fixed;\n  z-index: 1;\n  opacity: var(--ds-shell-gradient-opacity, 1);\n  background-image: var(--ds-shell-gradient-image, none);\n  background-size: var(--ds-shell-gradient-size, auto);\n  background-repeat: no-repeat;\n}\n\n.app-shell__panel {\n  flex: 0 0 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n  /* Above main so resize handle line can paint over the workspace edge */\n  z-index: 2;\n}\n\n.app-shell__panel ::slotted(ds-panel-nav) {\n  display: block;\n  height: 100%;\n}\n\n.app-shell__main {\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  display: grid;\n  grid-template-columns: minmax(0, 1fr) auto;\n  grid-template-rows: auto minmax(0, 1fr);\n  grid-template-areas:\n    'bar tools'\n    'content tools';\n  position: relative;\n  z-index: 1;\n}\n\n.app-shell__bar {\n  grid-area: bar;\n  flex: 0 0 auto;\n  min-width: 0;\n}\n\n.app-shell__bar ::slotted(ds-bar-nav) {\n  display: block;\n}\n\n.app-shell__content {\n  grid-area: content;\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  overflow: auto;\n  /* Limit reflow to the page column — not on __main (breaks tools flex shrink). */\n  contain: layout;\n}\n\n/* Opaque page surface — masks the fixed chrome layer in the content column. */\n.app-shell__content {\n  position: relative;\n  z-index: 1;\n  background-color: var(--color-background-primary);\n}\n\n.app-shell__tools {\n  grid-area: tools;\n  flex: 0 0 auto;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  display: flex;\n  position: relative;\n  z-index: 0;\n  overflow: hidden;\n}\n\n.app-shell__tools ::slotted(ds-panel-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/AppShell/AppShell.tsx",
+      "content": "import { Component, Prop, Element, Watch, Listen, h, Host } from '@stencil/core';\nimport type { NavChromeStyle } from '../../shell/nav-chrome';\nimport {\n  isEditableShortcutTarget,\n  resolveShellShortcut,\n} from '../../shell/shell-shortcuts';\nimport type { PanelToolsToolId } from '../PanelTools/panel-tools-types';\nimport {\n  DEFAULT_SHELL_GRADIENT_PRESET,\n  normalizeShellGradientPreset,\n  type ShellGradientPreset,\n} from '../../shell/shell-gradient-presets';\nimport {\n  CHROME_TRANSITION_END,\n  CHROME_TRANSITION_START,\n  ChromeTransitionDepth,\n  createRafCoalescer,\n  readChromeTransitionSource,\n} from '../../shell/chrome-transition';\nimport {\n  isPanelNavCollapsed,\n  panelWidthPxFromTokens,\n  readPanelNavWidthTokens,\n  type PanelNavWidthTokens,\n} from '../../shell/shell-chrome-metrics';\nimport {\n  SHELL_GRADIENT_IMAGE_VAR,\n  SHELL_GRADIENT_OPACITY_VAR,\n  SHELL_GRADIENT_POSITION_BAR_VAR,\n  SHELL_GRADIENT_POSITION_PANEL_VAR,\n  SHELL_GRADIENT_SIZE_VAR,\n  buildShellRadialGradient,\n  readShellViewportDimensions,\n  shellGradientPositionBar,\n  shellGradientPositionPanel,\n  shellGradientPresetOpacity,\n  shellGradientSize,\n} from '../../shell/shell-gradient';\n\n@Component({\n  tag: 'ds-app-shell',\n  styleUrl: 'AppShell.css',\n  scoped: true,\n})\nexport class AppShell {\n  /** Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`. */\n  @Prop({ attribute: 'nav-style', reflect: true }) navStyle: NavChromeStyle = 'dashboard';\n\n  /**\n   * Shell chrome wash preset. `none` renders solid chrome; the remaining\n   * presets use token-based washes that adapt to the active color theme.\n   */\n  @Prop({ attribute: 'gradient-preset', reflect: true }) gradientPreset: ShellGradientPreset =\n    DEFAULT_SHELL_GRADIENT_PRESET;\n\n  /** When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K/A/S/M/N/? toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native. */\n  @Prop({ attribute: 'shortcuts-enabled' }) shortcutsEnabled: boolean = true;\n\n  @Element() el!: HTMLElement;\n\n  private resizeObserver: ResizeObserver | null = null;\n  private readonly panelNavTransition = new ChromeTransitionDepth();\n  private readonly chromeSyncCoalescer = createRafCoalescer(() => this.syncChrome());\n  private panelWidthTokens: PanelNavWidthTokens = { expandedPx: 0, collapsedPx: 0 };\n  private cachedViewportWidth = 0;\n  private cachedViewportHeight = 0;\n  private onWindowResize = () => {\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n  private onVisualViewportChange = () => {\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n\n  componentDidLoad() {\n    this.syncSlottedNavStyle();\n    this.connectMetricsObserver();\n    this.connectViewportListeners();\n    this.el.addEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.addEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n    requestAnimationFrame(() => {\n      this.cachePanelWidthTokens();\n      this.scheduleChromeSync();\n    });\n  }\n\n  disconnectedCallback() {\n    this.resizeObserver?.disconnect();\n    this.resizeObserver = null;\n    this.disconnectViewportListeners();\n    this.chromeSyncCoalescer.cancel();\n    this.el.removeEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.removeEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n  }\n\n  @Watch('navStyle')\n  @Watch('gradientPreset')\n  onShellPropsChange() {\n    this.syncSlottedNavStyle();\n    this.scheduleChromeSync();\n  }\n\n  private onChromeTransitionStart = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.enter();\n    const viewport = readShellViewportDimensions();\n    this.cachedViewportWidth = viewport.width;\n    this.cachedViewportHeight = viewport.height;\n    this.syncChrome();\n  };\n\n  private onChromeTransitionEnd = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.exit();\n    if (!this.panelNavTransition.isActive) {\n      this.scheduleChromeSync();\n    }\n  };\n\n  /** Coalesce ResizeObserver bursts to one layout read per frame. */\n  private scheduleChromeSync() {\n    this.chromeSyncCoalescer.schedule();\n  }\n\n  private syncSlottedNavStyle() {\n    const panel = this.el.querySelector('ds-panel-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    const bar = this.el.querySelector('ds-bar-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    if (panel) {\n      panel.setAttribute('nav-style', this.navStyle);\n      panel.navStyle = this.navStyle;\n    }\n    if (bar) {\n      bar.setAttribute('nav-style', this.navStyle);\n      bar.navStyle = this.navStyle;\n    }\n  }\n\n  private connectMetricsObserver() {\n    this.resizeObserver = new ResizeObserver(() => {\n      if (this.panelNavTransition.isActive) return;\n      this.scheduleChromeSync();\n    });\n    this.resizeObserver.observe(this.el);\n    const panelWrap = this.el.querySelector('.app-shell__panel');\n    if (panelWrap) this.resizeObserver.observe(panelWrap);\n  }\n\n  private connectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.addEventListener('resize', this.onWindowResize, { passive: true });\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.addEventListener('resize', this.onVisualViewportChange, { passive: true });\n      visual.addEventListener('scroll', this.onVisualViewportChange, { passive: true });\n    }\n  }\n\n  private disconnectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.removeEventListener('resize', this.onWindowResize);\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.removeEventListener('resize', this.onVisualViewportChange);\n      visual.removeEventListener('scroll', this.onVisualViewportChange);\n    }\n  }\n\n  private cachePanelWidthTokens() {\n    const navRoot = this.el.querySelector('ds-panel-nav .panel-nav') as HTMLElement | null;\n    if (!navRoot) return;\n    this.panelWidthTokens = readPanelNavWidthTokens(navRoot);\n  }\n\n  private applyGradientVars(target: HTMLElement, vars: Record<string, string | null>) {\n    const style = target.style;\n    for (const [name, value] of Object.entries(vars)) {\n      if (value === null) style.removeProperty(name);\n      else style.setProperty(name, value);\n    }\n  }\n\n  private clearGradientPaintVars(targets: HTMLElement[]) {\n    const keys = [\n      SHELL_GRADIENT_IMAGE_VAR,\n      SHELL_GRADIENT_SIZE_VAR,\n      SHELL_GRADIENT_OPACITY_VAR,\n    ];\n    for (const target of targets) {\n      for (const key of keys) target.style.removeProperty(key);\n    }\n  }\n\n  /** Panel/bar wash offsets for scroll fades and badge rings. */\n  private syncChromeLayoutVars(\n    panel: HTMLElement | null,\n    bar: HTMLElement | null,\n    panelPosition: string,\n    barPosition: string,\n  ) {\n    if (panel) {\n      panel.style.setProperty(SHELL_GRADIENT_POSITION_PANEL_VAR, panelPosition);\n    }\n    if (bar) {\n      bar.style.setProperty(SHELL_GRADIENT_POSITION_BAR_VAR, barPosition);\n    }\n  }\n\n  private resolvePanelWidthPx(panelNav: HTMLElement | null): number {\n    const navRoot = panelNav?.querySelector('.panel-nav') as HTMLElement | null;\n\n    if (this.panelNavTransition.isActive && this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    const panelWrap = this.el.querySelector('.app-shell__panel') as HTMLElement | null;\n    const measured = panelWrap?.getBoundingClientRect().width ?? 0;\n    if (measured > 0) return measured;\n\n    if (this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    return 0;\n  }\n\n  /** Fixed-attachment wash/grid size — always the viewport, never the shell element box. */\n  private resolveViewportDimensions(): { width: number; height: number } {\n    if (this.panelNavTransition.isActive && this.cachedViewportWidth > 0) {\n      return {\n        width: this.cachedViewportWidth,\n        height: this.cachedViewportHeight,\n      };\n    }\n\n    return readShellViewportDimensions();\n  }\n\n  private chromeLayerActive(): boolean {\n    return normalizeShellGradientPreset(this.gradientPreset) !== 'none';\n  }\n\n  @Listen('keydown', { target: 'window', capture: true })\n  handleWindowKeyDown(e: KeyboardEvent) {\n    if (!this.shortcutsEnabled) return;\n    if (isEditableShortcutTarget(e.target)) return;\n\n    const action = resolveShellShortcut(e);\n    if (!action) return;\n\n    e.preventDefault();\n\n    const panel = this.el.querySelector('ds-panel-nav') as HTMLDsPanelNavElement | null;\n    const tools = this.el.querySelector('ds-panel-tools') as HTMLDsPanelToolsElement | null;\n\n    if (action === 'toggle-panel-nav') {\n      void panel?.toggleCollapsed();\n      return;\n    }\n\n    if (action === 'close-panel-tools') {\n      void tools?.closeDrawer();\n      return;\n    }\n\n    if (action.startsWith('open-tool:') && tools) {\n      const toolId = action.slice('open-tool:'.length) as PanelToolsToolId;\n      void tools.activateTool(toolId);\n    }\n  }\n\n  private syncChrome() {\n    const panelNav = this.el.querySelector('ds-panel-nav') as HTMLElement | null;\n    const bar = this.el.querySelector('ds-bar-nav') as HTMLElement | null;\n    const targets = [this.el, panelNav, bar].filter((el): el is HTMLElement => el !== null);\n\n    const clearLayoutVars = () => {\n      if (panelNav) panelNav.style.removeProperty(SHELL_GRADIENT_POSITION_PANEL_VAR);\n      if (bar) bar.style.removeProperty(SHELL_GRADIENT_POSITION_BAR_VAR);\n    };\n\n    const preset = normalizeShellGradientPreset(this.gradientPreset);\n    if (preset === 'none') {\n      this.clearGradientPaintVars(targets);\n      clearLayoutVars();\n      return;\n    }\n\n    const viewport = this.resolveViewportDimensions();\n    const panelWidth = this.resolvePanelWidthPx(panelNav);\n\n    const panelPosition = shellGradientPositionPanel();\n    const barPosition = shellGradientPositionBar(panelWidth);\n\n    this.syncChromeLayoutVars(panelNav, bar, panelPosition, barPosition);\n\n    const image = buildShellRadialGradient(preset);\n\n    const size = shellGradientSize({\n      width: viewport.width,\n      height: viewport.height,\n    });\n    const opacity = shellGradientPresetOpacity(preset);\n\n    for (const target of targets) {\n      if (target === this.el) {\n        this.applyGradientVars(target, {\n          [SHELL_GRADIENT_IMAGE_VAR]: image,\n          [SHELL_GRADIENT_SIZE_VAR]: size,\n          [SHELL_GRADIENT_POSITION_PANEL_VAR]: panelPosition,\n          [SHELL_GRADIENT_POSITION_BAR_VAR]: barPosition,\n          [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        });\n        continue;\n      }\n\n      const isBar = target.tagName.toLowerCase() === 'ds-bar-nav';\n      this.applyGradientVars(target, {\n        [SHELL_GRADIENT_IMAGE_VAR]: image,\n        [SHELL_GRADIENT_SIZE_VAR]: size,\n        [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        [SHELL_GRADIENT_POSITION_PANEL_VAR]: isBar ? null : panelPosition,\n        [SHELL_GRADIENT_POSITION_BAR_VAR]: isBar ? barPosition : null,\n      });\n    }\n  }\n\n  render() {\n    const chromeActive = this.chromeLayerActive();\n    const shellCls: Record<string, boolean> = {\n      'app-shell': true,\n      'app-shell--gradient': chromeActive,\n      [`app-shell--${this.navStyle}`]: true,\n    };\n\n    return (\n      <Host class={shellCls}>\n        <div class=\"app-shell__row\">\n          <div class=\"app-shell__chrome\" aria-hidden=\"true\" />\n          <div class=\"app-shell__panel\">\n            <slot name=\"panel\" />\n          </div>\n          <div class=\"app-shell__main\">\n            <div class=\"app-shell__bar\">\n              <slot name=\"bar\" />\n            </div>\n            <div class=\"app-shell__tools\">\n              <slot name=\"tools\" />\n            </div>\n            <div class=\"app-shell__content\">\n              <slot />\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}

package/dist/mcp-data/registry/badge.json

@@ -0,0 +1,289 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "badge",
+  "title": "Badge",
+  "description": "Non-interactive brand counter or dot that supplements an owning control or label with unread notification information.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/badge",
+    "source": "src/wc/components/Badge/Badge.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "stable",
+      "summary": "Non-interactive brand counter or dot that supplements an owning control or label with unread notification information.",
+      "useWhen": [
+        "An existing control, navigation item, or label needs a compact unread notification count.",
+        "An owning element needs a small visual dot indicating that supplemental notification information exists.",
+        "When the badge overlaps an icon or content, the immediate backing surface can be identified so its separation ring matches."
+      ],
+      "avoidWhen": [
+        "The status must stand alone without an owning label or control.",
+        "The mark needs semantic positive, caution, negative, or neutral color; Badge intentionally uses one brand treatment.",
+        "The compact content is metadata or taxonomy; use Tag or Chip according to whether it is removable.",
+        "The badge itself would receive pointer or keyboard interaction; put interaction on the owning control."
+      ],
+      "alternatives": [
+        {
+          "when": "A compact static label communicates taxonomy or a semantic status.",
+          "component": "component:ds-tag",
+          "reason": "Tag owns static metadata labels and semantic intent coloring."
+        },
+        {
+          "when": "A metadata value must be individually removable.",
+          "component": "component:ds-chip",
+          "reason": "Chip owns dismissible metadata values."
+        },
+        {
+          "when": "The count is primary content rather than supplemental notification chrome.",
+          "component": "component:ds-text",
+          "reason": "Text preserves the quantity as normal readable content."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-button-unfilled",
+        "component:ds-bar-nav",
+        "component:ds-panel-nav",
+        "component:ds-menu"
+      ],
+      "accessibility": [
+        "The owning control or content provides the primary accessible name; Badge contributes only supplemental unread or notification meaning.",
+        "When a dot is announced, provide contextual text that explains its meaning. Otherwise mark it aria-hidden from the owning composition.",
+        "When a counter is announced, provide contextual text such as “5 unread notifications”; a bare number is insufficient.",
+        "Avoid duplicating information already included in the owning control's accessible name.",
+        "Badge never receives focus and never owns an interaction."
+      ],
+      "states": [
+        "Counter represents an unread or notification count, while dot communicates presence without quantity.",
+        "Non-positive counter values hide the badge.",
+        "Counts above the configured compact limit display the limit with a plus suffix while accessible text retains meaningful context.",
+        "Badge keeps one brand treatment; semantic severity belongs to another component or adjacent content.",
+        "Use the ring only when Badge overlaps an icon or other content. Disable it in a reserved safe-area slot.",
+        "When enabled, the ring matches the immediate backing surface for both variants. Use a direct ring override only for a component-local fill that no surface preset represents.",
+        "Enabled shell gradient rings align automatically inside active AppShell gradient chrome and may be explicitly enabled or disabled when composition requires it."
+      ],
+      "responsiveBehavior": [
+        "The owning control or layout positions Badge and decides whether notification indicators remain visible, condense, or move at responsive breakpoints.",
+        "Badge does not anchor itself or automatically switch between counter and dot variants."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Position Badge from the owning element's layout and synchronize its contextual accessibility text with the owner."
+        ],
+        "react": [
+          "Keep count, visibility, and contextual accessibility text derived from the same unread-notification state as the owning control."
+        ],
+        "angular": [
+          "Keep count, visibility, and contextual accessibility text derived from the same unread-notification state as the owning control."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook examples",
+          "path": "src/wc/components/Badge/Badge.stories.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "background": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "background",
+          "required": false,
+          "mutable": false,
+          "description": "Direct ring background override for component-local surfaces."
+        },
+        "count": {
+          "type": "number",
+          "resolvedType": "number",
+          "attribute": "count",
+          "default": "0",
+          "required": false,
+          "mutable": false,
+          "description": "Count shown for counter badges. Count 0 hides the badge."
+        },
+        "gradientBackground": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "gradient-background",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Ring samples the shell gradient stack (base fill + wash) instead of a flat\n`box-shadow`. Auto-enabled under an AppShell with an active gradient preset;\nset `gradient-background` to opt in/out explicitly.\n\nThe attribute must NOT start with `on` — Stencil's setAccessor routes any\nunknown `on*` member down the event-listener path during attribute\nreflection, calling addEventListener with a non-listener and throwing."
+        },
+        "hasRing": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "has-ring",
+          "default": "true",
+          "required": false,
+          "mutable": false,
+          "description": "Show the separation ring when the badge overlaps an icon or other content."
+        },
+        "label": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "label",
+          "required": false,
+          "mutable": false,
+          "description": "Contextual supplemental text. Omit when the owner hides the badge from assistive technology."
+        },
+        "max": {
+          "type": "number",
+          "resolvedType": "number",
+          "attribute": "max",
+          "default": "9",
+          "required": false,
+          "mutable": false,
+          "description": "Highest count shown before compacting to \"{max}+\"."
+        },
+        "surface": {
+          "type": "BadgeSurface",
+          "resolvedType": "\"always-dark\" | \"bold\" | \"faint\" | \"inverted\" | \"media\" | \"medium\" | \"navigation\" | \"primary\" | \"secondary\" | \"strong\" | \"translucent\"",
+          "attribute": "surface",
+          "default": "'primary'",
+          "required": false,
+          "mutable": false,
+          "description": "Immediate backing surface matched by the ring around either variant."
+        },
+        "variant": {
+          "type": "BadgeVariant",
+          "resolvedType": "\"counter\" | \"dot\"",
+          "attribute": "variant",
+          "default": "'counter'",
+          "required": false,
+          "mutable": false,
+          "description": "Render as a compact counter or notification dot."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "background": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "background",
+        "required": false,
+        "mutable": false,
+        "description": "Direct ring background override for component-local surfaces."
+      },
+      "count": {
+        "type": "number",
+        "resolvedType": "number",
+        "attribute": "count",
+        "default": "0",
+        "required": false,
+        "mutable": false,
+        "description": "Count shown for counter badges. Count 0 hides the badge."
+      },
+      "gradientBackground": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "gradient-background",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Ring samples the shell gradient stack (base fill + wash) instead of a flat\n`box-shadow`. Auto-enabled under an AppShell with an active gradient preset;\nset `gradient-background` to opt in/out explicitly.\n\nThe attribute must NOT start with `on` — Stencil's setAccessor routes any\nunknown `on*` member down the event-listener path during attribute\nreflection, calling addEventListener with a non-listener and throwing."
+      },
+      "hasRing": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "has-ring",
+        "default": "true",
+        "required": false,
+        "mutable": false,
+        "description": "Show the separation ring when the badge overlaps an icon or other content."
+      },
+      "label": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "label",
+        "required": false,
+        "mutable": false,
+        "description": "Contextual supplemental text. Omit when the owner hides the badge from assistive technology."
+      },
+      "max": {
+        "type": "number",
+        "resolvedType": "number",
+        "attribute": "max",
+        "default": "9",
+        "required": false,
+        "mutable": false,
+        "description": "Highest count shown before compacting to \"{max}+\"."
+      },
+      "surface": {
+        "type": "BadgeSurface",
+        "resolvedType": "\"always-dark\" | \"bold\" | \"faint\" | \"inverted\" | \"media\" | \"medium\" | \"navigation\" | \"primary\" | \"secondary\" | \"strong\" | \"translucent\"",
+        "attribute": "surface",
+        "default": "'primary'",
+        "required": false,
+        "mutable": false,
+        "description": "Immediate backing surface matched by the ring around either variant."
+      },
+      "variant": {
+        "type": "BadgeVariant",
+        "resolvedType": "\"counter\" | \"dot\"",
+        "attribute": "variant",
+        "default": "'counter'",
+        "required": false,
+        "mutable": false,
+        "description": "Render as a compact counter or notification dot."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-badge",
+      "react": "DsBadge",
+      "angular": "DsBadge"
+    },
+    "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-badge.js';",
+        "example": "<ds-badge></ds-badge>"
+      },
+      "react": {
+        "import": "import { DsBadge } from '@ds-mo/ui/react';",
+        "example": "<DsBadge />"
+      },
+      "angular": {
+        "import": "import { DsBadge } from '@ds-mo/ui/angular/ds-badge';",
+        "example": "<ds-badge></ds-badge>"
+      },
+      "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": [
+    "text"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/Badge/Badge.css",
+      "content": ":host {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  pointer-events: none;\n  vertical-align: middle;\n\n  --_badge-bg: var(--color-background-bold-brand);\n  --_badge-fg: var(--color-foreground-on-bold-background-primary);\n  --_badge-ring: var(--color-background-secondary);\n  --_badge-ring-width: var(--dimension-stroke-width-018);\n}\n\n.badge__mark {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  box-sizing: border-box;\n  color: var(--_badge-fg);\n  background: var(--_badge-bg);\n  box-shadow: 0 0 0 var(--_badge-ring-width) var(--_badge-ring);\n  white-space: nowrap;\n}\n\n:host(.badge--no-ring) {\n  --_badge-ring-width: 0;\n}\n\n.badge__a11y {\n  position: absolute;\n  /* stylelint-disable declaration-property-value-disallowed-list -- classic visually-hidden clip pattern */\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border: 0;\n  /* stylelint-enable declaration-property-value-disallowed-list */\n}\n\n:host(.badge--dot) .badge__mark {\n  width: var(--dimension-size-075);\n  height: var(--dimension-size-075);\n  border-radius: var(--dimension-radius-half);\n}\n\n:host(.badge--counter) .badge__mark {\n  width: auto;\n  min-width: var(--dimension-size-150);\n  height: var(--dimension-size-150);\n  padding: 0 var(--dimension-space-025);\n  border-radius: var(--dimension-radius-half);\n}\n\n/* Shell gradient ring — base fill + wash donut (option 3). */\n:host(.badge--on-gradient-background) .badge__mark {\n  position: relative;\n  z-index: 0;\n  box-shadow: none;\n  isolation: isolate;\n}\n\n:host(.badge--on-gradient-background) .badge__mark::before,\n:host(.badge--on-gradient-background) .badge__mark::after {\n  content: '';\n  position: absolute;\n  inset: calc(-1 * var(--_badge-ring-width));\n  border-radius: inherit;\n  box-sizing: border-box;\n  padding: var(--_badge-ring-width);\n  pointer-events: none;\n  /* stylelint-disable color-no-hex -- mask luminance stops for ring cutout, not theme colors */\n  -webkit-mask:\n    linear-gradient(#fff 0 0) content-box,\n    linear-gradient(#fff 0 0);\n  -webkit-mask-composite: xor;\n  mask:\n    linear-gradient(#fff 0 0) content-box,\n    linear-gradient(#fff 0 0);\n  /* stylelint-enable color-no-hex */\n  mask-composite: exclude;\n}\n\n:host(.badge--on-gradient-background) .badge__mark::before {\n  z-index: -2;\n  background-color: var(--_badge-ring);\n}\n\n:host(.badge--on-gradient-background) .badge__mark::after {\n  z-index: -1;\n  background-image: var(--ds-shell-gradient-image, none);\n  background-size: var(--ds-shell-gradient-size, auto);\n  background-position: 0 0;\n  background-repeat: no-repeat;\n  background-attachment: fixed;\n  opacity: var(--ds-shell-gradient-opacity, 1);\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Badge/Badge.tsx",
+      "content": "import { Component, Prop, Element, State, Watch, h, Host } from '@stencil/core';\nimport {\n  BADGE_GRADIENT_POSITION_VAR,\n  isShellGradientActive,\n} from '../../shell/badge-gradient-ring';\n\nexport type BadgeVariant = 'counter' | 'dot';\nexport type BadgeSurface =\n  | 'primary'\n  | 'secondary'\n  | 'faint'\n  | 'medium'\n  | 'bold'\n  | 'strong'\n  | 'translucent'\n  | 'inverted'\n  | 'media'\n  | 'navigation'\n  | 'always-dark';\n\nconst SURFACE_RING: Record<BadgeSurface, string> = {\n  primary: 'var(--color-background-primary)',\n  secondary: 'var(--color-background-secondary)',\n  faint: 'var(--color-background-faint-neutral)',\n  medium: 'var(--color-background-medium-neutral)',\n  bold: 'var(--color-background-bold-neutral)',\n  strong: 'var(--color-background-strong-neutral)',\n  translucent: 'var(--color-translucent-translucent)',\n  inverted: 'var(--color-inverted-background)',\n  media: 'var(--color-media-background)',\n  navigation: 'var(--color-navigation-background)',\n  'always-dark': 'var(--color-always-dark-background)',\n};\n\n@Component({\n  tag: 'ds-badge',\n  styleUrl: 'Badge.css',\n  scoped: true,\n})\nexport class Badge {\n  @Element() el!: HTMLElement;\n\n  /** Render as a compact counter or notification dot. */\n  @Prop() variant: BadgeVariant = 'counter';\n\n  /** Count shown for counter badges. Count 0 hides the badge. */\n  @Prop() count: number = 0;\n\n  /** Highest count shown before compacting to \"{max}+\". */\n  @Prop() max: number = 9;\n\n  /** Immediate backing surface matched by the ring around either variant. */\n  @Prop() surface: BadgeSurface = 'primary';\n\n  /** Direct ring background override for component-local surfaces. */\n  @Prop() background: string | undefined;\n\n  /** Show the separation ring when the badge overlaps an icon or other content. */\n  @Prop() hasRing: boolean = true;\n\n  /**\n   * Ring samples the shell gradient stack (base fill + wash) instead of a flat\n   * `box-shadow`. Auto-enabled under an AppShell with an active gradient preset;\n   * set `gradient-background` to opt in/out explicitly.\n   *\n   * The attribute must NOT start with `on` — Stencil's setAccessor routes any\n   * unknown `on*` member down the event-listener path during attribute\n   * reflection, calling addEventListener with a non-listener and throwing.\n   */\n  @Prop({ attribute: 'gradient-background', reflect: true }) gradientBackground: boolean = false;\n\n  /** Contextual supplemental text. Omit when the owner hides the badge from assistive technology. */\n  @Prop() label: string | undefined;\n\n  /** Bumps on resize/layout so render recomputes gradient ring position. */\n  @State() private gradientLayoutVersion = 0;\n\n  private gradientObserver: ResizeObserver | null = null;\n  private gradientWindowListener: (() => void) | null = null;\n\n  componentDidLoad() {\n    this.enableShellGradientRingIfNeeded();\n  }\n\n  disconnectedCallback() {\n    this.unbindGradientRingSync();\n  }\n\n  @Watch('gradientBackground')\n  @Watch('hasRing')\n  gradientBackgroundChanged() {\n    if (!this.hasRing) {\n      this.unbindGradientRingSync();\n      return;\n    }\n    if (!this.gradientBackground && isShellGradientActive(this.el)) {\n      this.gradientBackground = true;\n      return;\n    }\n    this.bindGradientRingSync();\n  }\n\n  /** Imperative opt-in avoids Stencil aborting parent render for nested badges. */\n  private enableShellGradientRingIfNeeded() {\n    if (!this.hasRing) return;\n\n    if (!this.gradientBackground && isShellGradientActive(this.el)) {\n      this.gradientBackground = true;\n    }\n\n    if (this.gradientBackground) {\n      this.bindGradientRingSync();\n    }\n  }\n\n  private bindGradientRingSync() {\n    this.unbindGradientRingSync();\n\n    if (!this.gradientBackground) return;\n\n    const update = () => {\n      this.gradientLayoutVersion += 1;\n    };\n    update();\n\n    this.gradientWindowListener = update;\n    window.addEventListener('resize', update);\n\n    if (typeof ResizeObserver !== 'undefined') {\n      this.gradientObserver = new ResizeObserver(update);\n      this.gradientObserver.observe(this.el);\n\n      const shell = this.el.closest('ds-app-shell');\n      if (shell) this.gradientObserver.observe(shell);\n\n      const bar = this.el.closest('ds-bar-nav');\n      if (bar) this.gradientObserver.observe(bar);\n\n      const panel = this.el.closest('ds-panel-nav');\n      if (panel) this.gradientObserver.observe(panel);\n    }\n  }\n\n  private unbindGradientRingSync() {\n    if (this.gradientWindowListener) {\n      window.removeEventListener('resize', this.gradientWindowListener);\n      this.gradientWindowListener = null;\n    }\n\n    this.gradientObserver?.disconnect();\n    this.gradientObserver = null;\n  }\n\n  private ringHostStyle(ring: string): Record<string, string> {\n    void this.gradientLayoutVersion;\n\n    const style: Record<string, string> = { '--_badge-ring': ring };\n    if (!this.gradientBackground || !isShellGradientActive(this.el)) return style;\n\n    /* Shell chrome wash uses background-attachment: fixed at viewport origin. */\n    style[BADGE_GRADIENT_POSITION_VAR] = '0 0';\n    return style;\n  }\n\n  render() {\n    const isDot = this.variant === 'dot';\n\n    if (!isDot && this.count <= 0) return <Host style={{ display: 'none' }} />;\n\n    const display = this.count > this.max ? `${this.max}+` : String(this.count);\n    const ring = this.background ?? SURFACE_RING[this.surface];\n\n    return (\n      <Host\n        class={{\n          badge: true,\n          'badge--counter': !isDot,\n          'badge--dot': isDot,\n          'badge--no-ring': !this.hasRing,\n          'badge--on-gradient-background': this.hasRing && this.gradientBackground,\n        }}\n        style={this.ringHostStyle(ring)}\n      >\n        <span class=\"badge__mark\" aria-hidden=\"true\">\n          {!isDot && (\n            <ds-text as=\"span\" variant=\"text-caption\" emphasis color=\"inherit\">\n              {display}\n            </ds-text>\n          )}\n        </span>\n        {this.label && <span class=\"badge__a11y\">{this.label}</span>}\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}