@mhmo91/schmancy 0.9.15 → 0.9.17

package/dist/agent/schmancy.manifest.json

@@ -217,7 +217,13 @@
           "kind": "class",
           "name": "SchmancyAutocomplete",
           "tagName": "schmancy-autocomplete",
-          "description": "Autocomplete input component with filtering and multi-select support.",
+          "description": "Combobox with type-ahead filtering over a list of `<schmancy-option>` children. Single or multi-select. Form-associated.",
+          "summary": "Use when users need to pick from a known list of options but the list is too long for a plain select dropdown. Prefer schmancy-select for short static lists.",
+          "platformPrimitive": {
+            "tag": "combobox",
+            "mode": "change",
+            "note": "Composed of a schmancy-input + a floating listbox populated from `<schmancy-option>` children. Multi-select renders selections as schmancy-input-chip chips. Degrades to a datalist-backed native input if the tag never registers."
+          },
           "attributes": [
             {
               "name": "required",
@@ -317,6 +323,15 @@
               },
               "default": "''"
             }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "description": "`SchmancyAutocompleteChangeEvent` with `{ value }` (single) or `{ value, values }` (multi)."
+            }
+          ],
+          "examples": [
+            "<schmancy-autocomplete name=\"country\" label=\"Country\" placeholder=\"Start typing…\">\n  <schmancy-option value=\"US\">United States</schmancy-option>\n  <schmancy-option value=\"CA\">Canada</schmancy-option>\n  <schmancy-option value=\"GB\">United Kingdom</schmancy-option>\n</schmancy-autocomplete>"
           ]
         }
       ]
@@ -631,7 +646,13 @@
           "kind": "class",
           "name": "SchmancyButton",
           "tagName": "schmancy-button",
-          "description": "A button component.",
+          "description": "Material Design button — primary interactive surface for triggering actions or navigation.",
+          "summary": "Trigger actions or navigate. Form-associated; participates in native form submission.",
+          "platformPrimitive": {
+            "tag": "button",
+            "mode": "click",
+            "note": "Schmancy-skinned native `<button type=\"submit\">`. When `href` is set, degrades to `<a href=\"…\">`. Falls back to plain `<button>` styled with Tailwind if the tag never registers."
+          },
           "attributes": [
             {
               "name": "variant",
@@ -741,6 +762,9 @@
               "description": "The underlying native `<button>` (or `<a>` when `href` is set)."
             }
           ],
+          "examples": [
+            "<schmancy-button variant=\"filled\" @click=${() => save()}>Save</schmancy-button>\n<schmancy-button variant=\"outlined\" href=\"/next\">Continue</schmancy-button>"
+          ],
           "contexts": [
             {
               "name": "SchmancyButtonSizeContext",
@@ -758,7 +782,13 @@
           "kind": "class",
           "name": "SchmnacyIconButton",
           "tagName": "schmancy-icon-button",
-          "description": "An icon button component.",
+          "description": "Icon-only button for toolbar actions, close affordances, or overflow menus.",
+          "summary": "Compact round/square button wrapping a single icon glyph. Form-associated like schmancy-button.",
+          "platformPrimitive": {
+            "tag": "button",
+            "mode": "click",
+            "note": "Schmancy-skinned native `<button>` (or `<a>` when `href` is set). aria-label is required for a11y because there's no text content."
+          },
           "attributes": [
             {
               "name": "size",
@@ -859,6 +889,9 @@
               "name": "base",
               "description": "The underlying native `<button>` (or `<a>` when `href` is set)."
             }
+          ],
+          "examples": [
+            "<schmancy-icon-button aria-label=\"Close\" @click=${() => close()}>\n  <schmancy-icon>close</schmancy-icon>\n</schmancy-icon-button>"
           ]
         }
       ]
@@ -871,11 +904,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>"
           ]
         }
       ]
@@ -888,6 +931,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",
@@ -956,6 +1006,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>"
           ]
         }
       ]
@@ -967,7 +1020,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>"
+          ]
         }
       ]
     },
@@ -979,6 +1042,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",
@@ -1008,6 +1078,9 @@
               },
               "default": "''"
             }
+          ],
+          "examples": [
+            "<schmancy-card-media src=\"/thumb.jpg\" alt=\"Product photo\"></schmancy-card-media>"
           ]
         }
       ]
@@ -1222,6 +1295,13 @@
           "kind": "class",
           "name": "SchmancyCheckboxElement",
           "tagName": "schmancy-checkbox",
+          "description": "Binary checkbox for multi-select or boolean form fields. Wraps Material Web's `<md-checkbox>`; form-associated.",
+          "summary": "Use for \"select many from a list\" or any boolean that's part of a form submission. Prefer schmancy-switch for immediate-effect toggles.",
+          "platformPrimitive": {
+            "tag": "checkbox",
+            "mode": "change",
+            "note": "Wraps `<md-checkbox>` from `@material/web`. Degrades to styled native `<input type=\"checkbox\">` if the tag never registers."
+          },
           "attributes": [
             {
               "name": "value",
@@ -1282,7 +1362,7 @@
           "events": [
             {
               "name": "valueChange",
-              "description": "Event fired when the checkbox value changes."
+              "description": "`CustomEvent<{ value: boolean }>` when the checkbox is toggled."
             }
           ],
           "slots": [
@@ -1290,6 +1370,9 @@
               "name": "",
               "description": "The label for the checkbox."
             }
+          ],
+          "examples": [
+            "<schmancy-checkbox name=\"tos\" required>I accept the terms</schmancy-checkbox>"
           ]
         }
       ]
@@ -1364,6 +1447,13 @@
           "kind": "class",
           "name": "SchmancyChips",
           "tagName": "schmancy-chips",
+          "description": "Filter-chip group — container for selectable `<schmancy-chip>` children. Single or multi-select.",
+          "summary": "Use for filtering or choosing from 2–8 mutually-visible options (\"Status: active / paused / archived\"). Prefer schmancy-select when the list gets long or vertical.",
+          "platformPrimitive": {
+            "tag": "chip-group",
+            "mode": "change",
+            "note": "No direct native equivalent. Degrades to a styled schmancy-select with similar semantics if the tag never registers."
+          },
           "attributes": [
             {
               "name": "wrap",
@@ -1391,6 +1481,15 @@
               ],
               "default": "'start'"
             }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "description": "`CustomEvent<{ value: string }>` (single) or `{ values: string[] }` (multi)."
+            }
+          ],
+          "examples": [
+            "<schmancy-chips multi @change=${(e) => this.filters = e.detail.values}>\n  <schmancy-chip value=\"active\">Active</schmancy-chip>\n  <schmancy-chip value=\"paused\">Paused</schmancy-chip>\n  <schmancy-chip value=\"archived\">Archived</schmancy-chip>\n</schmancy-chips>"
           ]
         }
       ]
@@ -1403,7 +1502,13 @@
           "kind": "class",
           "name": "SchmancyInputChip",
           "tagName": "schmancy-input-chip",
-          "description": "Input chip component - represents user-provided information that can be removed.  IMPORTANT: Per Material Design 3 specification, input chips do NOT have selected state. They represent discrete pieces of user input (like entered tags, selections from lists, etc.) that can only be removed, not toggled on/off.  Use cases: - Displaying selected recipients in an email - Showing applied filters that can be removed - Tags or keywords entered by the user - Selected items from a multi-select dropdown",
+          "description": "Input chip — displays user-provided information (tags, recipients, filters) that can be removed but not toggled.  IMPORTANT: Per Material Design 3 specification, input chips do NOT have selected state. They represent discrete pieces of user input (like entered tags, selections from lists, etc.) that can only be removed, not toggled on/off.  Use cases: - Displaying selected recipients in an email - Showing applied filters that can be removed - Tags or keywords entered by the user - Selected items from a multi-select dropdown",
+          "summary": "Removable pill that represents a single user input value. No selected state — use schmancy-chip (filter chip) for toggleable options.",
+          "platformPrimitive": {
+            "tag": "chip",
+            "mode": "remove",
+            "note": "No native equivalent. Composed of a labeled pill + close button. Degrades to a styled `<span>` with a trailing close `<button>` if the tag never registers."
+          },
           "attributes": [
             {
               "name": "value",
@@ -2138,6 +2243,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",
@@ -2199,6 +2311,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>"
           ]
         }
       ]
@@ -2341,6 +2462,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",
@@ -2372,6 +2500,9 @@
               ],
               "default": "'start'"
             }
+          ],
+          "examples": [
+            "<schmancy-list-item>First</schmancy-list-item>\n<schmancy-divider></schmancy-divider>\n<schmancy-list-item>Second</schmancy-list-item>"
           ]
         }
       ]
@@ -2511,6 +2642,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",
@@ -2543,6 +2681,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>"
           ]
         }
       ]
@@ -2555,6 +2696,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",
@@ -2612,6 +2760,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>"
           ]
         }
       ]
@@ -2635,7 +2792,13 @@
           "kind": "class",
           "name": "SchmancyForm",
           "tagName": "schmancy-form",
-          "description": "A thin ergonomic wrapper around a native `<form>` element. Its children are reparented into a `<form>` element in light DOM on connection, so:  - Form-associated custom elements (FACE) resolve their `internals.form`   correctly via native DOM ancestry. - `new FormData(form)` collects values from every FACE + native control   without any manual walking. - `form.reset()` triggers `formResetCallback()` on every FACE. - `form.reportValidity()` runs native validation UI. - `<button type=\"submit\">` and `<schmancy-button type=\"submit\">` both   submit the form via the native submitter pipeline.  This component exists only to translate the native `submit` / `reset` events into the Schmancy event shape (`detail: FormData`). All heavy lifting is the platform's.",
+          "description": "Ergonomic wrapper around a native `<form>`. Children are reparented into a light-DOM `<form>` on connection so form-associated custom elements resolve `internals.form` via native DOM ancestry.  - Form-associated custom elements (FACE) resolve their `internals.form`   correctly via native DOM ancestry. - `new FormData(form)` collects values from every FACE + native control   without any manual walking. - `form.reset()` triggers `formResetCallback()` on every FACE. - `form.reportValidity()` runs native validation UI. - `<button type=\"submit\">` and `<schmancy-button type=\"submit\">` both   submit the form via the native submitter pipeline.  This component exists only to translate the native `submit` / `reset` events into the Schmancy event shape (`detail: FormData`). All heavy lifting is the platform's.",
+          "summary": "Always wrap form-associated schmancy components in schmancy-form (or a native `<form>`) so `new FormData(form)` just works.",
+          "platformPrimitive": {
+            "tag": "form",
+            "mode": "submit",
+            "note": "Light-DOM native `<form>` element. Degrades to a `<form>` if the tag never registers — same semantics, just no CustomEvent translation."
+          },
           "events": [
             {
               "name": "submit",
@@ -2645,6 +2808,9 @@
               "name": "reset",
               "description": "Emitted after the underlying form resets."
             }
+          ],
+          "examples": [
+            "<schmancy-form @submit=${(e) => console.log(Object.fromEntries(e.detail))}>\n  <schmancy-input name=\"email\" type=\"email\" required></schmancy-input>\n  <schmancy-input name=\"password\" type=\"password\" required></schmancy-input>\n  <schmancy-button type=\"submit\" variant=\"filled\">Sign in</schmancy-button>\n</schmancy-form>"
           ]
         }
       ]
@@ -2825,7 +2991,13 @@
           "kind": "class",
           "name": "SchmancyInput",
           "tagName": "schmancy-input",
-          "description": "Enhanced version of the SchmancyInput component with improved form integration and compatibility with legacy API.  This component uses the native form association API and maintains parity with native input behaviors while providing a stylish, accessible interface.",
+          "description": "Single-line text input — the primary form-text primitive. Form-associated via ElementInternals, so it participates in native `<form>` submission, validation, and reset without additional wiring.",
+          "summary": "Text input with Material Design styling, native form integration, and RxJS-debounced input/change/enter events.",
+          "platformPrimitive": {
+            "tag": "input",
+            "mode": "change",
+            "note": "Schmancy-skinned native `<input>`. Degrades to `<input class=\"…\">` styled via Tailwind if the tag never registers."
+          },
           "attributes": [
             {
               "name": "value",
@@ -2994,6 +3166,23 @@
               },
               "description": "For datalist support"
             }
+          ],
+          "events": [
+            {
+              "name": "input",
+              "description": "`CustomEvent<{value: string}>` on every keystroke."
+            },
+            {
+              "name": "change",
+              "description": "`CustomEvent<{value: string}>` on blur/change."
+            },
+            {
+              "name": "enter",
+              "description": "`CustomEvent<{value: string}>` when user presses Enter."
+            }
+          ],
+          "examples": [
+            "<schmancy-form @submit=${onSubmit}>\n  <schmancy-input name=\"email\" type=\"email\" label=\"Email\" required></schmancy-input>\n</schmancy-form>"
           ]
         },
         {
@@ -4589,7 +4778,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",
@@ -4615,7 +4810,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>"
           ]
         }
       ]
@@ -4716,7 +4911,13 @@
           "kind": "class",
           "name": "RadioButton",
           "tagName": "schmancy-radio-button",
-          "description": "Radio button component for use within radio groups.",
+          "description": "Single radio button — always rendered as a child of `<schmancy-radio-group>`, never standalone.",
+          "summary": "Low-level primitive. Use schmancy-radio-group and pass `.options` for the common path; only instantiate schmancy-radio-button directly when you need per-button custom rendering.",
+          "platformPrimitive": {
+            "tag": "radio",
+            "mode": "change",
+            "note": "Schmancy-skinned `<input type=\"radio\">` semantics. Degrades to native radio if the tag never registers."
+          },
           "attributes": [
             {
               "name": "value",
@@ -4746,6 +4947,9 @@
               },
               "default": "''"
             }
+          ],
+          "examples": [
+            "<schmancy-radio-group name=\"plan\">\n  <schmancy-radio-button value=\"free\">Free</schmancy-radio-button>\n  <schmancy-radio-button value=\"pro\" checked>Pro</schmancy-radio-button>\n</schmancy-radio-group>"
           ]
         }
       ]
@@ -4758,6 +4962,13 @@
           "kind": "class",
           "name": "RadioGroup",
           "tagName": "schmancy-radio-group",
+          "description": "Radio-button group — single-select from a static list of mutually-exclusive options. Form-associated.",
+          "summary": "Use for 2–5 mutually-exclusive options where all should stay visible (\"Shipping: standard / express / overnight\"). Prefer schmancy-select when the list grows.",
+          "platformPrimitive": {
+            "tag": "radiogroup",
+            "mode": "change",
+            "note": "Renders schmancy-radio-button children. Degrades to a fieldset with native `<input type=\"radio\" name=\"…\">` siblings if the tag never registers."
+          },
           "attributes": [
             {
               "name": "label",
@@ -4794,6 +5005,15 @@
               },
               "default": "false"
             }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "description": "`SchmancyRadioGroupChangeEvent` with the selected `value`."
+            }
+          ],
+          "examples": [
+            "<schmancy-radio-group\n  name=\"shipping\"\n  label=\"Shipping\"\n  .options=${[\n    { label: 'Standard (5 days)', value: 'standard' },\n    { label: 'Express (2 days)', value: 'express' },\n    { label: 'Overnight', value: 'overnight' },\n  ]}\n></schmancy-radio-group>"
           ]
         }
       ]
@@ -4866,7 +5086,13 @@
           "kind": "class",
           "name": "SchmancySelect",
           "tagName": "schmancy-select",
-          "description": "Select dropdown component with single and multi-select support.",
+          "description": "Dropdown selector — single or multi-select from a list of `<schmancy-option>` children. Form-associated.",
+          "summary": "Material Design dropdown with type-to-filter, keyboard nav, single or multi-select. Options are declared as `<schmancy-option>` children; value / values props sync with selection.",
+          "platformPrimitive": {
+            "tag": "select",
+            "mode": "change",
+            "note": "Floating-UI-positioned listbox. Degrades to native `<select>` styled via Tailwind if the tag never registers, though multi-select UX is lost."
+          },
           "attributes": [
             {
               "name": "name",
@@ -4950,6 +5176,15 @@
               },
               "default": "''"
             }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "description": "`SchmancySelectChangeEvent` with `{ value }` (single) or `{ value: string[] }` (multi)."
+            }
+          ],
+          "examples": [
+            "<schmancy-select name=\"priority\" label=\"Priority\" value=\"medium\">\n  <schmancy-option value=\"low\">Low</schmancy-option>\n  <schmancy-option value=\"medium\">Medium</schmancy-option>\n  <schmancy-option value=\"high\">High</schmancy-option>\n</schmancy-select>"
           ]
         }
       ]
@@ -5340,7 +5575,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",
@@ -5401,7 +5642,13 @@
           "kind": "class",
           "name": "SchmancySwitch",
           "tagName": "schmancy-switch",
-          "description": "Binary on/off control. Form-associated, keyboard-accessible, semantically a switch (ARIA role=\"switch\"). Distinct from `schmancy-checkbox`: a switch represents an immediate state change, a checkbox represents a selection in a form to be submitted.",
+          "description": "Binary on/off control with immediate effect. Form-associated, keyboard-accessible, semantically a switch (ARIA role=\"switch\"). Distinct from `schmancy-checkbox`: a switch represents an immediate state change, a checkbox represents a selection in a form to be submitted.",
+          "summary": "Use when flipping the control takes effect right away (e.g. \"Dark mode\", \"Enable notifications\"). Prefer schmancy-checkbox for form submissions.",
+          "platformPrimitive": {
+            "tag": "switch",
+            "mode": "change",
+            "note": "Accessible native `<button role=\"switch\" aria-checked>` under the hood. No native HTML element exists; falls back to a styled checkbox if the tag never registers."
+          },
           "attributes": [
             {
               "name": "checked",
@@ -5461,6 +5708,9 @@
               "name": "thumb",
               "description": "The moving thumb."
             }
+          ],
+          "examples": [
+            "<schmancy-switch ?checked=${this.darkMode} @change=${(e) => this.darkMode = e.detail.value}>\n  Dark mode\n</schmancy-switch>"
           ]
         }
       ]
@@ -5653,7 +5903,13 @@
           "kind": "class",
           "name": "SchmancyTextarea",
           "tagName": "schmancy-textarea",
-          "description": "Textarea component with auto-resize and form integration.",
+          "description": "Multi-line text input with auto-resize and form integration. Form-associated.",
+          "summary": "Textarea for freeform text — notes, descriptions, messages. Auto-grows with content up to a maxlength.",
+          "platformPrimitive": {
+            "tag": "textarea",
+            "mode": "change",
+            "note": "Schmancy-skinned native `<textarea>`. Degrades to styled native `<textarea>` if the tag never registers."
+          },
           "attributes": [
             {
               "name": "label",
@@ -5832,6 +6088,19 @@
               },
               "default": "false"
             }
+          ],
+          "events": [
+            {
+              "name": "input",
+              "description": "On every keystroke."
+            },
+            {
+              "name": "change",
+              "description": "On blur."
+            }
+          ],
+          "examples": [
+            "<schmancy-textarea name=\"description\" label=\"Description\" rows=\"4\" maxlength=\"500\"></schmancy-textarea>"
           ]
         }
       ]
@@ -5894,7 +6163,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",
@@ -5949,7 +6224,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": [
             {
@@ -6005,6 +6281,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",
@@ -6024,6 +6307,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>"
           ]
         }
       ]
@@ -6393,6 +6679,13 @@
           "kind": "class",
           "name": "SchmancyCountriesSelect",
           "tagName": "schmancy-select-countries",
+          "description": "Country picker — type-ahead autocomplete over the ISO 3166-1 country list. Form-associated.",
+          "summary": "Drop-in replacement for schmancy-autocomplete when the options are specifically \"every country\". Pre-seeds the list from countries.data.",
+          "platformPrimitive": {
+            "tag": "combobox",
+            "mode": "change",
+            "note": "Composes schmancy-autocomplete with a static options list. Value is the 2-letter ISO code."
+          },
           "attributes": [
             {
               "name": "value",
@@ -6435,6 +6728,15 @@
               },
               "default": "''"
             }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "description": "`SchmancyAutocompleteChangeEvent` with `{ value: string }` (the ISO code)."
+            }
+          ],
+          "examples": [
+            "<schmancy-select-countries name=\"country\" label=\"Shipping country\" required></schmancy-select-countries>"
           ]
         }
       ]
@@ -6447,7 +6749,13 @@
           "kind": "class",
           "name": "SchmancyTimezonesSelect",
           "tagName": "schmancy-select-timezones",
-          "description": "Timezone selector component with autocomplete filtering.",
+          "description": "Timezone picker — type-ahead autocomplete over the IANA tz database. Form-associated.",
+          "summary": "Drop-in replacement for schmancy-autocomplete when the options are IANA timezone names. Value is the IANA identifier (\"America/Los_Angeles\").",
+          "platformPrimitive": {
+            "tag": "combobox",
+            "mode": "change",
+            "note": "Composes schmancy-autocomplete with a static IANA timezones list."
+          },
           "attributes": [
             {
               "name": "value",
@@ -6490,6 +6798,15 @@
               },
               "default": "''"
             }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "description": "`SchmancyAutocompleteChangeEvent` with `{ value: string }` (the IANA tz name)."
+            }
+          ],
+          "examples": [
+            "<schmancy-select-timezones name=\"tz\" label=\"Timezone\" value=\"America/New_York\"></schmancy-select-timezones>"
           ]
         }
       ]
@@ -6690,7 +7007,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",