@mhmo91/schmancy 0.9.16 → 0.9.18

package/dist/agent/schmancy.manifest.json

@@ -524,7 +524,13 @@
           "kind": "class",
           "name": "SchmancyBreadcrumb",
           "tagName": "schmancy-breadcrumb",
-          "description": "Breadcrumb navigation container. Wraps a list of `schmancy-breadcrumb-item` elements with the correct ARIA landmark and semantics.",
+          "description": "Breadcrumb trail — navigation history from root to current page. Renders schmancy-breadcrumb-item children with separators between.",
+          "summary": "Use for deep hierarchical navigation (file explorer paths, e-commerce category chains, admin settings trees). Last item is styled as the current page automatically.",
+          "platformPrimitive": {
+            "tag": "nav",
+            "mode": "-",
+            "note": "Styled `<nav aria-label=\"Breadcrumb\">`. Degrades to a plain nav if the tag never registers."
+          },
           "attributes": [
             {
               "name": "separator",
@@ -545,13 +551,22 @@
               "name": "separator",
               "description": "The separator element."
             }
+          ],
+          "examples": [
+            "<schmancy-breadcrumb separator=\"›\">\n  <schmancy-breadcrumb-item href=\"/\">Home</schmancy-breadcrumb-item>\n  <schmancy-breadcrumb-item href=\"/docs\">Docs</schmancy-breadcrumb-item>\n  <schmancy-breadcrumb-item>Getting started</schmancy-breadcrumb-item>\n</schmancy-breadcrumb>"
           ]
         },
         {
           "kind": "class",
           "name": "SchmancyBreadcrumbItem",
           "tagName": "schmancy-breadcrumb-item",
-          "description": "Individual breadcrumb item. Renders as a link when `href` is provided, otherwise as a plain span (represents the current page).",
+          "description": "Single segment in a schmancy-breadcrumb trail — a link when `href` is set, or a plain span (the current page) when omitted.",
+          "summary": "Always nested inside schmancy-breadcrumb. Omit `href` on the current page — it gets aria-current=\"page\" automatically.",
+          "platformPrimitive": {
+            "tag": "a",
+            "mode": "-",
+            "note": "Renders an `<a>` or `<span>` depending on href. Degrades to a plain anchor/span if the tag never registers."
+          },
           "attributes": [
             {
               "name": "href",
@@ -573,6 +588,9 @@
               "name": "",
               "description": "Label content."
             }
+          ],
+          "examples": [
+            "<schmancy-breadcrumb-item href=\"/products\">Products</schmancy-breadcrumb-item>"
           ]
         }
       ]
@@ -904,11 +922,21 @@
           "kind": "class",
           "name": "SchmancyCardAction",
           "tagName": "schmancy-card-action",
+          "description": "Action row of a schmancy-card — holds the card's buttons / links (typically aligned bottom-right).",
+          "summary": "Always nested inside schmancy-card. Holds the primary + secondary CTAs for the card.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Styled flex container. Degrades to a plain div if the tag never registers."
+          },
           "slots": [
             {
               "name": "",
               "description": "The content of the action"
             }
+          ],
+          "examples": [
+            "<schmancy-card-action>\n  <schmancy-button variant=\"text\">Cancel</schmancy-button>\n  <schmancy-button variant=\"filled\">Save</schmancy-button>\n</schmancy-card-action>"
           ]
         }
       ]
@@ -921,6 +949,13 @@
           "kind": "class",
           "name": "SchmancyCard",
           "tagName": "schmancy-card",
+          "description": "Material Design card — a surface-level container for grouping related content with media / content / actions slots.",
+          "summary": "Use for discrete pieces of content that appear in a list (a product, a note, a message). Combine with schmancy-card-media / schmancy-card-content / schmancy-card-action children.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Styled `<div>`; becomes an `<a>` when `href` is set so the whole card is a single interactive surface. Degrades to a plain div/a if the tag never registers."
+          },
           "attributes": [
             {
               "name": "type",
@@ -989,6 +1024,9 @@
               "default": "''",
               "description": "ARIA label for accessibility."
             }
+          ],
+          "examples": [
+            "<schmancy-card type=\"elevated\" href=\"/items/42\">\n  <schmancy-card-media src=\"/thumb.jpg\" alt=\"Thumbnail\"></schmancy-card-media>\n  <schmancy-card-content>\n    <h3>Title</h3>\n    <p>One-line description of the card's content.</p>\n  </schmancy-card-content>\n  <schmancy-card-action>\n    <schmancy-button variant=\"text\">Open</schmancy-button>\n  </schmancy-card-action>\n</schmancy-card>"
           ]
         }
       ]
@@ -1000,7 +1038,17 @@
         {
           "kind": "class",
           "name": "SchmancyCardContent",
-          "tagName": "schmancy-card-content"
+          "tagName": "schmancy-card-content",
+          "description": "Content region of a schmancy-card — holds the card's headline, supporting text, and inline controls.",
+          "summary": "Always nested inside schmancy-card. The padded content block between the media and action rows.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Styled `<div>` with padding. Degrades to a plain div if the tag never registers."
+          },
+          "examples": [
+            "<schmancy-card-content>\n  <h3>Card title</h3>\n  <p>Supporting text that describes the card's subject.</p>\n</schmancy-card-content>"
+          ]
         }
       ]
     },
@@ -1012,6 +1060,13 @@
           "kind": "class",
           "name": "SchmancyCardMedia",
           "tagName": "schmancy-card-media",
+          "description": "Media region of a schmancy-card — the image / thumbnail at the top of the card.",
+          "summary": "Always nested inside schmancy-card. Pass `src` + `alt` props or slot an `<img>` / `<video>` for custom media.",
+          "platformPrimitive": {
+            "tag": "img",
+            "mode": "-",
+            "note": "Renders an `<img>` (or wraps a slotted media element). Degrades to a styled `<img>` if the tag never registers."
+          },
           "attributes": [
             {
               "name": "src",
@@ -1041,6 +1096,9 @@
               },
               "default": "''"
             }
+          ],
+          "examples": [
+            "<schmancy-card-media src=\"/thumb.jpg\" alt=\"Product photo\"></schmancy-card-media>"
           ]
         }
       ]
@@ -2203,6 +2261,13 @@
           "kind": "class",
           "name": "SchmancyDetails",
           "tagName": "schmancy-details",
+          "description": "Expandable disclosure panel — a styled `<details>` / `<summary>` pair with animated expand + overlay options.",
+          "summary": "Use for progressive-disclosure content: FAQs, collapsible settings sections, accordion-style lists. Prefer schmancy-expand for full-page accordions where only one section can be open at a time.",
+          "platformPrimitive": {
+            "tag": "details",
+            "mode": "toggle",
+            "note": "Wraps native `<details>`/`<summary>`. Degrades to the native element if the tag never registers — same keyboard accessibility, just no animation."
+          },
           "attributes": [
             {
               "name": "summary",
@@ -2264,6 +2329,15 @@
               },
               "default": "'p-3'"
             }
+          ],
+          "events": [
+            {
+              "name": "toggle",
+              "description": "When the open state changes (bubbles from the native `<details>`)."
+            }
+          ],
+          "examples": [
+            "<schmancy-details summary=\"Shipping details\">\n  <p>Order ships in 2 business days.</p>\n</schmancy-details>"
           ]
         }
       ]
@@ -2311,7 +2385,13 @@
           "kind": "class",
           "name": "SchmancyDialog",
           "tagName": "schmancy-dialog",
-          "description": "Unified dialog component that handles both content-only and confirm modes.",
+          "description": "Modal dialog — content-only (just a styled panel) or confirm mode (title + message + confirm/cancel buttons). Prefer the imperative `$dialog` service for most use cases; use the element directly only when you want a declaratively-positioned dialog.",
+          "summary": "Blocks interaction with the rest of the page until dismissed. For quick confirmations, prefer `$dialog.confirm({ ... })` over this element. For arbitrary dialog content driven imperatively, prefer `$dialog.component(MyComponent)`.",
+          "platformPrimitive": {
+            "tag": "dialog",
+            "mode": "close",
+            "note": "Positioned overlay in light DOM. Degrades to a styled `<dialog>` if the tag never registers — loses custom animations but keeps focus trap + ESC close."
+          },
           "attributes": [
             {
               "name": "uid",
@@ -2381,6 +2461,16 @@
               "description": "Whether to hide action buttons (force content mode)"
             }
           ],
+          "events": [
+            {
+              "name": "confirm",
+              "description": "In confirm mode, when the confirm button is clicked."
+            },
+            {
+              "name": "cancel",
+              "description": "In confirm mode, when the cancel button or ESC is activated."
+            }
+          ],
           "slots": [
             {
               "name": "default",
@@ -2392,8 +2482,8 @@
             }
           ],
           "examples": [
-            "Content mode (no buttons):\n\n<schmancy-dialog>\n  <my-custom-content></my-custom-content>\n</schmancy-dialog>",
-            "Confirm mode (with buttons):\n\n<schmancy-dialog\n  title=\"Confirm Action\"\n  message=\"Are you sure?\"\n  confirm-text=\"Yes\"\n  cancel-text=\"No\"\n></schmancy-dialog>"
+            "Content mode (no buttons):\n<schmancy-dialog>\n  <my-custom-content></my-custom-content>\n</schmancy-dialog>",
+            "Confirm mode (with buttons):\n<schmancy-dialog\n  title=\"Delete item?\"\n  message=\"This action cannot be undone.\"\n  confirm-text=\"Delete\"\n  cancel-text=\"Keep\"\n></schmancy-dialog>"
           ]
         }
       ]
@@ -2406,6 +2496,13 @@
           "kind": "class",
           "name": "SchmancyDivider",
           "tagName": "schmancy-divider",
+          "description": "Thin horizontal (or vertical) separator rule between sections of content.",
+          "summary": "Semantic separator between groups — list items, menu sections, content blocks. Uses outline theme token.",
+          "platformPrimitive": {
+            "tag": "hr",
+            "mode": "-",
+            "note": "Styled horizontal rule. Degrades to a native `<hr>` if the tag never registers."
+          },
           "attributes": [
             {
               "name": "outline",
@@ -2437,6 +2534,9 @@
               ],
               "default": "'start'"
             }
+          ],
+          "examples": [
+            "<schmancy-list-item>First</schmancy-list-item>\n<schmancy-divider></schmancy-divider>\n<schmancy-list-item>Second</schmancy-list-item>"
           ]
         }
       ]
@@ -2449,7 +2549,13 @@
           "kind": "class",
           "name": "SchmancyDropdown",
           "tagName": "schmancy-dropdown",
-          "description": "A dropdown component that displays content when triggered.",
+          "description": "Anchored floating dropdown — a generic \"show this content relative to that trigger\" primitive. Unlike schmancy-menu (which uses the dialog service and is list-shaped), dropdown is a low-level popover anchored with Floating UI. Use when you want a custom-shaped overlay tied to a specific trigger element without the menu semantics.",
+          "summary": "Prefer schmancy-menu for action lists, schmancy-autocomplete for type-ahead, schmancy-tooltip for hover hints. Reach for schmancy-dropdown when none of those fit — custom filters, color pickers, inline forms anchored to a trigger.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Anchored via Floating UI (autoUpdate, flip, shift). Degrades to inline content if the tag never registers — loses positioning but content stays accessible."
+          },
           "attributes": [
             {
               "name": "open",
@@ -2490,6 +2596,16 @@
               "description": "Offset distance in pixels"
             }
           ],
+          "events": [
+            {
+              "name": "open",
+              "description": "When the dropdown opens."
+            },
+            {
+              "name": "close",
+              "description": "When the dropdown closes."
+            }
+          ],
           "slots": [
             {
               "name": "trigger",
@@ -2499,6 +2615,9 @@
               "name": "",
               "description": "Default slot for the dropdown content"
             }
+          ],
+          "examples": [
+            "<schmancy-dropdown>\n  <schmancy-button slot=\"trigger\">Filters</schmancy-button>\n  <schmancy-dropdown-content>\n    <schmancy-form>…</schmancy-form>\n  </schmancy-dropdown-content>\n</schmancy-dropdown>"
           ]
         }
       ]
@@ -2511,7 +2630,13 @@
           "kind": "class",
           "name": "SchmancyDropdownContent",
           "tagName": "schmancy-dropdown-content",
-          "description": "Content container for the schmancy-dropdown component.",
+          "description": "Content panel for a schmancy-dropdown — a styled positioned surface. Always nested inside schmancy-dropdown and placed alongside the trigger slot.",
+          "summary": "Nest this inside schmancy-dropdown (not in the trigger slot). Use the `content` CSS part to customize backgrounds / shadows / padding without shadow-root piercing.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Positioned panel with theme-aware styling. Degrades to an inline div if the tag never registers."
+          },
           "attributes": [
             {
               "name": "width",
@@ -2564,6 +2689,9 @@
               "name": "content",
               "description": "The inner wrapper element; style to override panel backgrounds, shadows, padding, or borders without shadow-root piercing."
             }
+          ],
+          "examples": [
+            "<schmancy-dropdown>\n  <schmancy-button slot=\"trigger\">Open</schmancy-button>\n  <schmancy-dropdown-content>\n    Panel contents…\n  </schmancy-dropdown-content>\n</schmancy-dropdown>"
           ]
         }
       ]
@@ -2576,6 +2704,13 @@
           "kind": "class",
           "name": "SchmancyExpandRoot",
           "tagName": "schmancy-expand-root",
+          "description": "Container for schmancy-expand children — coordinates mutual-exclusion so only one child is open at a time. Also renders the portal panel that the active child expands into.",
+          "summary": "Always wrap a group of schmancy-expand children. Without a root, each schmancy-expand behaves independently (which is usually not what you want — prefer schmancy-details for that).",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Coordinating wrapper. Degrades to a plain div if the tag never registers — children fall back to independent `<details>` behavior."
+          },
           "attributes": [
             {
               "name": "type",
@@ -2608,6 +2743,9 @@
               ],
               "default": "'solid'"
             }
+          ],
+          "examples": [
+            "<schmancy-expand-root>\n  <schmancy-expand summary=\"Step 1\">…</schmancy-expand>\n  <schmancy-expand summary=\"Step 2\">…</schmancy-expand>\n</schmancy-expand-root>"
           ]
         }
       ]
@@ -2620,6 +2758,13 @@
           "kind": "class",
           "name": "SchmancyExpand",
           "tagName": "schmancy-expand",
+          "description": "Accordion-style section — expands on click, coordinates with siblings via schmancy-expand-root to close any sibling when a new one opens. Only one schmancy-expand can be open at a time within the same root.",
+          "summary": "Use for grouped progressive-disclosure where only one section should be open at a time. Prefer schmancy-details when sections should be independent.",
+          "platformPrimitive": {
+            "tag": "details",
+            "mode": "toggle",
+            "note": "Schmancy-skinned accordion section. Degrades to `<details>` if the tag never registers — loses mutual-exclusion behavior but stays functional."
+          },
           "attributes": [
             {
               "name": "summary",
@@ -2677,6 +2822,15 @@
               },
               "default": "false"
             }
+          ],
+          "events": [
+            {
+              "name": "toggle",
+              "description": "When the open state changes."
+            }
+          ],
+          "examples": [
+            "<schmancy-expand-root>\n  <schmancy-expand summary=\"Billing\">Billing form…</schmancy-expand>\n  <schmancy-expand summary=\"Shipping\">Shipping form…</schmancy-expand>\n  <schmancy-expand summary=\"Review\">Order review…</schmancy-expand>\n</schmancy-expand-root>"
           ]
         }
       ]
@@ -3221,6 +3375,13 @@
           "kind": "class",
           "name": "SchmancyListItem",
           "tagName": "schmancy-list-item",
+          "description": "Single row in a schmancy-list — supports leading icon/avatar, main content, trailing actions. Clickable via click event, or used as a schmancy-menu-item's visual base.",
+          "summary": "Prefer nesting inside schmancy-list for consistent spacing/surface. Use `href` to make the row a navigation target (renders as `<a>`), or a click handler for in-app actions.",
+          "platformPrimitive": {
+            "tag": "li",
+            "mode": "click",
+            "note": "Styled `<li>` or `<a>` depending on `href`. Degrades to a plain list item if the tag never registers."
+          },
           "attributes": [
             {
               "name": "variant",
@@ -3286,6 +3447,9 @@
               "description": "default content"
             }
           ],
+          "examples": [
+            "<schmancy-list-item href=\"/profile\">\n  <schmancy-icon slot=\"leading\">person</schmancy-icon>\n  Profile\n  <schmancy-icon slot=\"trailing\">chevron_right</schmancy-icon>\n</schmancy-list-item>"
+          ],
           "contexts": [
             {
               "name": "SchmancySurfaceTypeContext",
@@ -3303,7 +3467,13 @@
           "kind": "class",
           "name": "List",
           "tagName": "schmancy-list",
-          "description": "`<schmancy-list>` component.  A list component that wraps its content within a customizable surface. It allows you to set the surface type and fill style, and can optionally enable scrolling behavior by delegating the scroller attribute to the surface.",
+          "description": "Wrapped list container — holds schmancy-list-item children on a themed surface. Optionally scrollable.",
+          "summary": "Use for vertical lists of similarly-shaped items: settings entries, menu items, contact lists, notification lists. Pair with schmancy-list-item children.",
+          "platformPrimitive": {
+            "tag": "ul",
+            "mode": "-",
+            "note": "Styled list container. Degrades to a plain ul/div if the tag never registers."
+          },
           "attributes": [
             {
               "name": "surface",
@@ -3366,7 +3536,7 @@
             }
           ],
           "examples": [
-            "<schmancy-list surface=\"container\" scroller>\n  <schmancy-list-item>List Item 1</schmancy-list-item>\n</schmancy-list>"
+            "<schmancy-list surface=\"container\" scroller>\n  <schmancy-list-item>First</schmancy-list-item>\n  <schmancy-list-item>Second</schmancy-list-item>\n  <schmancy-list-item>Third</schmancy-list-item>\n</schmancy-list>"
           ],
           "contexts": [
             {
@@ -3846,7 +4016,23 @@
         {
           "kind": "class",
           "name": "SchmancyMenuItem",
-          "tagName": "schmancy-menu-item"
+          "tagName": "schmancy-menu-item",
+          "description": "Single item inside a schmancy-menu. Auto-dismisses the menu dialog on click — attach your action handler to `@click` and it just works.",
+          "summary": "Always nested inside schmancy-menu. The click handler runs before the dialog closes, so `@click=${() => doThing()}` is the full pattern.",
+          "platformPrimitive": {
+            "tag": "menuitem",
+            "mode": "click",
+            "note": "Wraps schmancy-list-item with auto-dismiss. Degrades to a styled `<button role=\"menuitem\">` if the tag never registers."
+          },
+          "slots": [
+            {
+              "name": "",
+              "description": "The item label and optional icons."
+            }
+          ],
+          "examples": [
+            "<schmancy-menu-item @click=${() => archive()}>\n  <schmancy-icon slot=\"leading\">archive</schmancy-icon>\n  Archive\n</schmancy-menu-item>"
+          ]
         }
       ]
     },
@@ -3858,7 +4044,13 @@
           "kind": "class",
           "name": "SchmancyMenu",
           "tagName": "schmancy-menu",
-          "description": "Menu Component  CRITICAL: The dialog ONLY renders the raw menu items passed via the default slot. NO <ul> wrapper, NO classes, NO additional markup in the dialog call. The dialog service handles positioning and display - we just pass the pure content.",
+          "description": "Floating menu — a trigger button + a list of schmancy-menu-item children that open as a positioned dialog on click.",
+          "summary": "Use for dropdown menus attached to a button or icon — \"More actions\", \"Account\", row overflow menus in tables. Clicking a schmancy-menu-item inside auto-dismisses; custom components slotted inside must call `$dialog.dismiss()` themselves.",
+          "platformPrimitive": {
+            "tag": "menu",
+            "mode": "close",
+            "note": "Trigger + floating listbox dialog. Degrades to a native `<select>` or inline list if the tag never registers."
+          },
           "slots": [
             {
               "name": "trigger",
@@ -3874,8 +4066,7 @@
             }
           ],
           "examples": [
-            "Basic menu with auto-dismiss\n\n<schmancy-menu>\n  <schmancy-button slot=\"trigger\">Actions</schmancy-button>\n  <schmancy-menu-item @click=${() => editItem()}>Edit</schmancy-menu-item>\n  <schmancy-menu-item @click=${() => deleteItem()}>Delete</schmancy-menu-item>\n</schmancy-menu>\n\nNote: Dialog auto-dismisses when schmancy-menu-item is clicked",
-            "Custom component (manual dismiss)\n\n<schmancy-menu>\n  <schmancy-icon-button slot=\"trigger\">settings</schmancy-icon-button>\n  <my-settings-form @submit=${() => $dialog.dismiss()}></my-settings-form>\n</schmancy-menu>\n\nNote: Custom components must call $dialog.dismiss() manually"
+            "<schmancy-menu>\n  <schmancy-icon-button slot=\"trigger\" aria-label=\"Actions\">\n    <schmancy-icon>more_vert</schmancy-icon>\n  </schmancy-icon-button>\n  <schmancy-menu-item @click=${() => edit()}>Edit</schmancy-menu-item>\n  <schmancy-menu-item @click=${() => remove()}>Delete</schmancy-menu-item>\n</schmancy-menu>"
           ]
         }
       ]
@@ -3888,11 +4079,21 @@
           "kind": "class",
           "name": "SchmancyDrawerAppbar",
           "tagName": "schmancy-nav-drawer-appbar",
+          "description": "Top app bar region inside schmancy-nav-drawer — the horizontal strip above the content area that typically holds the page title, hamburger trigger, and contextual actions.",
+          "summary": "Always nested inside schmancy-nav-drawer. Holds the page-level title + top-right actions. On mobile, the drawer's hamburger button renders inside this region.",
+          "platformPrimitive": {
+            "tag": "header",
+            "mode": "-",
+            "note": "Styled horizontal bar. Degrades to a plain header element if the tag never registers."
+          },
           "slots": [
             {
               "name": "",
               "description": "The default slot"
             }
+          ],
+          "examples": [
+            "<schmancy-nav-drawer-appbar>\n  <schmancy-typography type=\"title\" token=\"lg\">Dashboard</schmancy-typography>\n  <schmancy-icon-button slot=\"trailing\" aria-label=\"Notifications\">\n    <schmancy-icon>notifications</schmancy-icon>\n  </schmancy-icon-button>\n</schmancy-nav-drawer-appbar>"
           ]
         }
       ]
@@ -3904,7 +4105,17 @@
         {
           "kind": "class",
           "name": "SchmancyNavigationDrawerContent",
-          "tagName": "schmancy-nav-drawer-content"
+          "tagName": "schmancy-nav-drawer-content",
+          "description": "Main content region inside schmancy-nav-drawer — typically hosts the router outlet or the page's body content.",
+          "summary": "Always nested inside schmancy-nav-drawer. Scrollable by default; propagates scroll events up so the drawer can collapse app-bar on scroll.",
+          "platformPrimitive": {
+            "tag": "main",
+            "mode": "scroll",
+            "note": "Scrollable `<main>`. Degrades to a plain scrollable div if the tag never registers."
+          },
+          "examples": [
+            "<schmancy-nav-drawer-content>\n  <schmancy-area name=\"main\"></schmancy-area>\n</schmancy-nav-drawer-content>"
+          ]
         }
       ]
     },
@@ -3916,6 +4127,13 @@
           "kind": "class",
           "name": "SchmancyNavigationDrawer",
           "tagName": "schmancy-nav-drawer",
+          "description": "Responsive navigation drawer — a left sidebar that becomes a hamburger-triggered modal overlay on narrow viewports. Composes schmancy-nav-drawer-navbar (the nav rail), schmancy-nav-drawer-appbar (the top bar), and schmancy-nav-drawer-content (the main region).",
+          "summary": "The app-shell layout primitive. Wrap your whole app in this when you want \"persistent sidebar on desktop, drawer on mobile\" behavior. Mode auto-switches at the breakpoint.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Flex layout with viewport-width mode switching. Degrades to a stack of plain divs if the tag never registers."
+          },
           "attributes": [
             {
               "name": "fullscreen",
@@ -3949,12 +4167,21 @@
               ]
             }
           ],
+          "events": [
+            {
+              "name": "schmancy-drawer-state",
+              "description": "When the drawer open/close state changes on mobile."
+            }
+          ],
           "slots": [
             {
               "name": "",
               "description": "The content slot"
             }
           ],
+          "examples": [
+            "<schmancy-nav-drawer>\n  <schmancy-nav-drawer-navbar>\n    <!-- nav items, typically schmancy-list-item links -->\n  </schmancy-nav-drawer-navbar>\n  <schmancy-nav-drawer-appbar>App title</schmancy-nav-drawer-appbar>\n  <schmancy-nav-drawer-content>\n    <!-- router outlet / page content -->\n  </schmancy-nav-drawer-content>\n</schmancy-nav-drawer>"
+          ],
           "contexts": [
             {
               "name": "SchmancyDrawerNavbarMode",
@@ -3976,6 +4203,13 @@
           "kind": "class",
           "name": "SchmancyNavigationDrawerSidebar",
           "tagName": "schmancy-nav-drawer-navbar",
+          "description": "Sidebar region inside schmancy-nav-drawer — the persistent-on-desktop / modal-on-mobile nav rail.",
+          "summary": "Always nested inside schmancy-nav-drawer. On desktop: pinned left sidebar. On mobile: modal overlay triggered by the hamburger button in schmancy-nav-drawer-appbar.",
+          "platformPrimitive": {
+            "tag": "nav",
+            "mode": "-",
+            "note": "Sidebar `<nav>` with responsive open/close behavior. Degrades to a plain sidebar div if the tag never registers."
+          },
           "attributes": [
             {
               "name": "width",
@@ -3985,6 +4219,9 @@
               "default": "'220px'"
             }
           ],
+          "examples": [
+            "<schmancy-nav-drawer-navbar>\n  <schmancy-list>\n    <schmancy-list-item href=\"/dashboard\">Dashboard</schmancy-list-item>\n    <schmancy-list-item href=\"/settings\">Settings</schmancy-list-item>\n  </schmancy-list>\n</schmancy-nav-drawer-navbar>"
+          ],
           "contexts": [
             {
               "name": "SchmancyDrawerNavbarMode",
@@ -4006,7 +4243,13 @@
           "kind": "class",
           "name": "SchmancyNavigationBarItem",
           "tagName": "schmancy-navigation-bar-item",
-          "description": "`<schmancy-navigation-bar-item>` component  Individual navigation item for use within a navigation bar. Represents a single destination with an icon and optional label following Material Design 3 specifications.",
+          "description": "Single destination inside schmancy-navigation-bar — an icon + optional label representing one primary app destination.",
+          "summary": "Always nested inside schmancy-navigation-bar. Use `icon` attr for a Material Symbols glyph or slot=icon for custom content.",
+          "platformPrimitive": {
+            "tag": "button",
+            "mode": "click",
+            "note": "Styled navigation target. Degrades to a plain `<button>` if the tag never registers."
+          },
           "attributes": [
             {
               "name": "icon",
@@ -4088,7 +4331,13 @@
           "kind": "class",
           "name": "SchmancyNavigationBar",
           "tagName": "schmancy-navigation-bar",
-          "description": "`<schmancy-navigation-bar>` component  A horizontal navigation component following Material Design 3 specifications. Navigation bars provide access to between 3-7 primary destinations. Automatically hides in fullscreen mode when triggered via schmancyTheme.next({ fullscreen: true }).  **IMPORTANT**: This component includes `z-10` by default (consistent with navigation-rail). The consumer is responsible for positioning the navigation bar in their layout. For typical bottom-fixed positioning, add: `class=\"fixed bottom-0 left-0 right-0\"`.",
+          "description": "Bottom navigation bar — Material Design 3 horizontal nav for mobile primary destinations (3–7 items). Auto-hides in fullscreen mode.",
+          "summary": "Use for mobile primary navigation (home, search, favorites, settings). For persistent desktop nav, prefer schmancy-navigation-rail or schmancy-nav-drawer. Consumer is responsible for fixed-bottom positioning via class.",
+          "platformPrimitive": {
+            "tag": "nav",
+            "mode": "-",
+            "note": "Styled horizontal nav with schmancy-navigation-bar-item children. Degrades to a plain flex container if the tag never registers."
+          },
           "attributes": [
             {
               "name": "hideLabels",
@@ -4142,7 +4391,13 @@
           "kind": "class",
           "name": "SchmancyNavigationRailItem",
           "tagName": "schmancy-navigation-rail-item",
-          "description": "Material Design 3 Navigation Rail Item Component",
+          "description": "Single destination inside schmancy-navigation-rail — vertically-stacked icon + optional label. @see https://m3.material.io/components/navigation-rail/overview",
+          "summary": "Always nested inside schmancy-navigation-rail. Use `icon` attr for a Material Symbols glyph, or slot=icon for custom content. Supports a `badge` slot for notification dots / counts.",
+          "platformPrimitive": {
+            "tag": "button",
+            "mode": "click",
+            "note": "Styled vertical navigation target. Degrades to a plain `<button>` if the tag never registers."
+          },
           "attributes": [
             {
               "name": "icon",
@@ -4280,7 +4535,7 @@
           "kind": "class",
           "name": "SchmancyNavigationRail",
           "tagName": "schmancy-navigation-rail",
-          "description": "Material Design 3 Navigation Rail Component\r @see https://m3.material.io/components/navigation-rail/overview\r  `<schmancy-navigation-rail>` component\r  A Material Design 3 vertical navigation component positioned on the left side of an application.\r Navigation rails provide access to between 3-7 primary destinations with a compact footprint.\r Automatically hides in fullscreen mode when triggered via schmancyTheme.next({ fullscreen: true }).\r  @element schmancy-navigation-rail\r @slot fab - Slot for a floating action button at the top\r @slot menu - Slot for a menu icon or button below the FAB\r @slot header - Custom header content slot\r @slot footer - Custom footer content slot\r @slot - Default slot for navigation rail items\r  @fires navigate - When a navigation item is selected\r @fires menu-click - When the menu button is clicked\r @fires fab-click - When the FAB is clicked\r  @csspart rail - The main rail container\r @csspart header - The header section\r @csspart nav - The navigation items container\r @csspart footer - The footer section",
+          "description": "Vertical navigation rail — Material Design 3 compact left-side nav for desktop / tablet layouts with 3–7 primary destinations. Auto-hides in fullscreen mode. @see https://m3.material.io/components/navigation-rail/overview\r  @element schmancy-navigation-rail\r @summary Use as the desktop counterpart of schmancy-navigation-bar: same destinations, different form factor. Prefer schmancy-nav-drawer when you also want a drawer + app-bar combo.",
           "attributes": [
             {
               "name": "label-visibility",
@@ -4334,6 +4589,7 @@
             }
           ],
           "examples": [
+            "<schmancy-navigation-rail activeIndex=\"0\">\r\n  <schmancy-icon-button slot=\"fab\" variant=\"filled\">\r\n    <schmancy-icon>add</schmancy-icon>\r\n  </schmancy-icon-button>\r\n  <schmancy-navigation-rail-item icon=\"home\" label=\"Home\"></schmancy-navigation-rail-item>\r\n  <schmancy-navigation-rail-item icon=\"search\" label=\"Search\"></schmancy-navigation-rail-item>\r\n  <schmancy-navigation-rail-item icon=\"settings\" label=\"Settings\"></schmancy-navigation-rail-item>\r\n</schmancy-navigation-rail>\r\n@platform nav - Vertical styled nav. Degrades to a plain vertical flex container if the tag never registers.\r\n@slot fab - Slot for a floating action button at the top\r\n@slot menu - Slot for a menu icon or button below the FAB\r\n@slot header - Custom header content slot\r\n@slot footer - Custom footer content slot\r\n@slot - Default slot for navigation rail items\r\n\n@fires navigate - When a navigation item is selected\r\n@fires menu-click - When the menu button is clicked\r\n@fires fab-click - When the FAB is clicked\r\n\n@csspart rail - The main rail container\r\n@csspart header - The header section\r\n@csspart nav - The navigation items container\r\n@csspart footer - The footer section",
             "<schmancy-navigation-rail activeIndex=\"0\">\r\n  <schmancy-button slot=\"fab\" variant=\"filled\" aria-label=\"Compose\">\r\n    <schmancy-icon>add</schmancy-icon>\r\n  </schmancy-button>\r\n  <schmancy-button slot=\"menu\" variant=\"text\" aria-label=\"Menu\">\r\n    <schmancy-icon>menu</schmancy-icon>\r\n  </schmancy-button>\r\n  <schmancy-navigation-rail-item icon=\"home\" label=\"Home\"></schmancy-navigation-rail-item>\r\n  <schmancy-navigation-rail-item icon=\"search\" label=\"Search\"></schmancy-navigation-rail-item>\r\n  <schmancy-navigation-rail-item icon=\"favorite\" label=\"Favorites\" badge=\"3\"></schmancy-navigation-rail-item>\r\n  <schmancy-navigation-rail-item icon=\"settings\" label=\"Settings\"></schmancy-navigation-rail-item>\r\n</schmancy-navigation-rail>"
           ]
         }
@@ -4686,7 +4942,13 @@
           "kind": "class",
           "name": "SchmancyPage",
           "tagName": "schmancy-page",
-          "description": "Native mobile-like page container. Prevents double-tap zoom, pull-to-refresh, rubber-banding. Automatically fills remaining viewport height.",
+          "description": "Mobile-first page container — fills remaining viewport height, suppresses double-tap zoom / pull-to-refresh / rubber-banding. Lays children in a CSS grid whose row template is `rows`.",
+          "summary": "The root of any app view — wraps header / main / footer children in a full-viewport grid. Use rows=\"auto_1fr_auto\" to make the middle child scroll while header/footer stay pinned.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Full-height CSS-grid container. Degrades to a plain div if the tag never registers — children still flow vertically but without the height fill and gesture suppression."
+          },
           "attributes": [
             {
               "name": "rows",
@@ -4712,7 +4974,7 @@
             }
           ],
           "examples": [
-            "html`\n  <schmancy-page rows=\"1fr_2fr_auto\">\n    <header>App Bar</header>\n    <main>Scrollable content</main>\n    <footer>Navigation</footer>\n  </schmancy-page>\n`"
+            "<schmancy-page rows=\"auto_1fr_auto\">\n  <schmancy-nav-drawer-appbar>Title</schmancy-nav-drawer-appbar>\n  <main>Scrollable content</main>\n  <schmancy-navigation-bar></schmancy-navigation-bar>\n</schmancy-page>"
           ]
         }
       ]
@@ -5122,6 +5384,13 @@
           "kind": "class",
           "name": "SchmancySheet",
           "tagName": "schmancy-sheet",
+          "description": "Side-docked or bottom-docked panel — a dialog variant that slides in from an edge. Driven imperatively by the `sheet` service; rarely instantiated directly.",
+          "summary": "Prefer `sheet.open({ component, position })` over placing this element declaratively — the service handles stacking, focus, close on outside-click, ESC, and router integration.",
+          "platformPrimitive": {
+            "tag": "dialog",
+            "mode": "close",
+            "note": "Positioned-fixed panel with backdrop. Degrades to a `<dialog>` if the tag never registers — loses slide animation, keeps focus trap + dismiss."
+          },
           "attributes": [
             {
               "name": "open",
@@ -5162,6 +5431,15 @@
               },
               "default": "true"
             }
+          ],
+          "events": [
+            {
+              "name": "close",
+              "description": "When the sheet is dismissed (backdrop click, close button, ESC)."
+            }
+          ],
+          "examples": [
+            "import { sheet, SchmancySheetPosition } from '@mhmo91/schmancy'\nsheet.open({\n  component: new MyEditorElement(),\n  position: SchmancySheetPosition.Side,\n  title: 'Edit item',\n})"
           ]
         }
       ]
@@ -5477,7 +5755,13 @@
           "kind": "class",
           "name": "SchmancySurface",
           "tagName": "schmancy-surface",
-          "description": "`<schmancy-surface>` component  This component renders a styled container that adapts its dimensions based on the `fill` property. It supports various rounding options, elevation levels, and applies background and text color classes based on the specified surface variant. Additionally, when the `scroller` property is true, the component enables internal scrolling by applying overflow and scroll-behavior styles.  SurfaceMixin automatically provides surfaceStyles CSS.",
+          "description": "Themed container — the root surface primitive. Sets background, text color, rounding, elevation, and (optionally) internal scroll. Provides a `SchmancySurfaceTypeContext` so descendants can adapt to the enclosing surface variant.",
+          "summary": "Wrap a region of a page when you need it to pick up theme tokens (background + on-color + elevation). Nest surfaces to express Material Design's hierarchical color stacking.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Styled `<div>` with theme-driven background/color/elevation. Degrades to a plain `<div>` if the tag never registers — text stays readable, just loses theming."
+          },
           "attributes": [
             {
               "name": "type",
@@ -6059,7 +6343,13 @@
           "kind": "class",
           "name": "SchmancyThemeComponent",
           "tagName": "schmancy-theme",
-          "description": "SchmancyThemeComponent - Provides theming capabilities for Schmancy components.  This component manages color schemes, primary colors, and theme distribution throughout the component tree. It can be used at the root level or nested to provide different themes to different parts of the application.",
+          "description": "Theme provider — generates a Material 3 palette from a seed color, resolves light/dark scheme, and publishes the token set to descendants as CSS custom properties (var(--schmancy-sys-color-…)).",
+          "summary": "Always wrap your app root in a `<schmancy-theme root scheme=\"auto\" color=\"#…\">`. Nest additional `<schmancy-theme>` blocks to override theming for a subtree.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Styled `<div>` that publishes theme tokens via inline `--schmancy-sys-color-*` custom properties. Degrades to a plain div if the tag never registers — children lose theming and fall back to browser defaults."
+          },
           "attributes": [
             {
               "name": "color",
@@ -6114,7 +6404,8 @@
             }
           ],
           "examples": [
-            "<!-- Root theme provider -->\n<schmancy-theme color=\"#6200ee\" scheme=\"auto\" root>\n  <your-app></your-app>\n</schmancy-theme>\n\n<!-- Nested theme for specific section -->\n<schmancy-theme color=\"#2196f3\" scheme=\"dark\">\n  <div class=\"dark-section\">\n    <!-- Components here will use blue dark theme -->\n  </div>\n</schmancy-theme>"
+            "<!-- Root theme provider -->\n<schmancy-theme root scheme=\"auto\" color=\"#6200ee\">\n  <your-app></your-app>\n</schmancy-theme>",
+            "<!-- Nested theme for a specific section -->\n<schmancy-theme scheme=\"dark\" color=\"#2196f3\">\n  <schmancy-surface fill=\"all\">\n    <!-- Components here use the blue dark theme -->\n  </schmancy-surface>\n</schmancy-theme>"
           ],
           "contexts": [
             {
@@ -6170,6 +6461,13 @@
           "kind": "class",
           "name": "SchmancyTree",
           "tagName": "schmancy-tree",
+          "description": "Expandable tree node — a recursive disclosure widget. One root slot, one default slot for child nodes. Each node can itself contain schmancy-tree children.",
+          "summary": "Use for hierarchical navigation / file-explorer layouts. Each level is a schmancy-tree with a `root` slot (the parent label) and default slot (the children, which may be more schmancy-trees).",
+          "platformPrimitive": {
+            "tag": "details",
+            "mode": "toggle",
+            "note": "Recursive `<details>`-like disclosure. Degrades to a plain nested list if the tag never registers — loses expand/collapse but stays navigable."
+          },
           "attributes": [
             {
               "name": "open",
@@ -6189,6 +6487,9 @@
               "name": "",
               "description": "The children of the tree"
             }
+          ],
+          "examples": [
+            "<schmancy-tree>\n  <schmancy-list-item slot=\"root\">src/</schmancy-list-item>\n  <schmancy-tree>\n    <schmancy-list-item slot=\"root\">components/</schmancy-list-item>\n    <schmancy-list-item>button.ts</schmancy-list-item>\n  </schmancy-tree>\n</schmancy-tree>"
           ]
         }
       ]
@@ -6886,7 +7187,13 @@
           "kind": "class",
           "name": "SchmancyScroll",
           "tagName": "schmancy-scroll",
-          "description": "A custom scrollable container with enhanced features.",
+          "description": "Scrollable container with debounced scroll events, horizontal/vertical direction, optional hidden scrollbar, and programmatic scrollTo via command events or refs.",
+          "summary": "Use anywhere you'd reach for `overflow: auto` but also need debounced scroll events (for sticky headers, scroll spies, virtualization triggers) or the ability to drive scroll from elsewhere in the app by dispatching a schmancy-scroll-command event.",
+          "platformPrimitive": {
+            "tag": "div",
+            "mode": "-",
+            "note": "Styled scrollable `<div>`. Degrades to a plain scrollable div if the tag never registers — loses the debounced scroll event and the command-bus integration."
+          },
           "attributes": [
             {
               "name": "hide",