@mhmo91/schmancy 0.9.15 → 0.9.17

package/custom-elements.json

@@ -126,7 +126,7 @@
     {
       "name": "schmancy-autocomplete",
       "path": "./src/autocomplete/autocomplete.ts",
-      "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.",
       "attributes": [
         {
           "name": "maxHeight",
@@ -321,7 +321,8 @@
       ],
       "events": [
         {
-          "name": "change"
+          "name": "change",
+          "description": "`SchmancyAutocompleteChangeEvent` with `{ value }` (single) or `{ value, values }` (multi)."
         }
       ]
     },
@@ -873,7 +874,7 @@
     {
       "name": "schmancy-button",
       "path": "./src/button/button.ts",
-      "description": "A button component.",
+      "description": "Material Design button — primary interactive surface for triggering actions or navigation.",
       "attributes": [
         {
           "name": "variant",
@@ -1015,7 +1016,7 @@
     {
       "name": "schmancy-icon-button",
       "path": "./src/button/icon-button.ts",
-      "description": "An icon button component.",
+      "description": "Icon-only button for toolbar actions, close affordances, or overflow menus.",
       "attributes": [
         {
           "name": "size",
@@ -1150,6 +1151,7 @@
     {
       "name": "schmancy-card-action",
       "path": "./src/card/actions.ts",
+      "description": "Action row of a schmancy-card — holds the card's buttons / links (typically aligned bottom-right).",
       "slots": [
         {
           "name": "",
@@ -1160,6 +1162,7 @@
     {
       "name": "schmancy-card",
       "path": "./src/card/card.ts",
+      "description": "Material Design card — a surface-level container for grouping related content with media / content / actions slots.",
       "attributes": [
         {
           "name": "type",
@@ -1277,11 +1280,13 @@
     },
     {
       "name": "schmancy-card-content",
-      "path": "./src/card/content.ts"
+      "path": "./src/card/content.ts",
+      "description": "Content region of a schmancy-card — holds the card's headline, supporting text, and inline controls."
     },
     {
       "name": "schmancy-card-media",
       "path": "./src/card/media.ts",
+      "description": "Media region of a schmancy-card — the image / thumbnail at the top of the card.",
       "attributes": [
         {
           "name": "src",
@@ -1625,6 +1630,7 @@
     {
       "name": "schmancy-checkbox",
       "path": "./src/checkbox/checkbox.ts",
+      "description": "Binary checkbox for multi-select or boolean form fields. Wraps Material Web's `<md-checkbox>`; form-associated.",
       "attributes": [
         {
           "name": "value",
@@ -1729,7 +1735,7 @@
       "events": [
         {
           "name": "valueChange",
-          "description": "Event fired when the checkbox value changes."
+          "description": "`CustomEvent<{ value: boolean }>` when the checkbox is toggled."
         },
         {
           "name": "change"
@@ -1840,6 +1846,7 @@
     {
       "name": "schmancy-chips",
       "path": "./src/chips/chips.ts",
+      "description": "Filter-chip group — container for selectable `<schmancy-chip>` children. Single or multi-select.",
       "attributes": [
         {
           "name": "multi",
@@ -1912,7 +1919,8 @@
       ],
       "events": [
         {
-          "name": "change"
+          "name": "change",
+          "description": "`CustomEvent<{ value: string }>` (single) or `{ values: string[] }` (multi)."
         }
       ]
     },
@@ -2104,7 +2112,7 @@
     {
       "name": "schmancy-input-chip",
       "path": "./src/chips/input-chip.ts",
-      "description": "Input chip component - represents user-provided information that can be removed.\n\nIMPORTANT: Per Material Design 3 specification, input chips do NOT have selected state.\nThey represent discrete pieces of user input (like entered tags, selections from lists, etc.)\nthat can only be removed, not toggled on/off.\n\nUse cases:\n- Displaying selected recipients in an email\n- Showing applied filters that can be removed\n- Tags or keywords entered by the user\n- Selected items from a multi-select dropdown",
+      "description": "Input chip — displays user-provided information (tags, recipients, filters) that can be removed but not toggled.\n\nIMPORTANT: Per Material Design 3 specification, input chips do NOT have selected state.\nThey represent discrete pieces of user input (like entered tags, selections from lists, etc.)\nthat can only be removed, not toggled on/off.\n\nUse cases:\n- Displaying selected recipients in an email\n- Showing applied filters that can be removed\n- Tags or keywords entered by the user\n- Selected items from a multi-select dropdown",
       "attributes": [
         {
           "name": "value",
@@ -3147,6 +3155,7 @@
     {
       "name": "schmancy-details",
       "path": "./src/details/details.ts",
+      "description": "Expandable disclosure panel — a styled `<details>` / `<summary>` pair with animated expand + overlay options.",
       "attributes": [
         {
           "name": "summary",
@@ -3257,6 +3266,12 @@
           "type": "string",
           "default": "\"all\""
         }
+      ],
+      "events": [
+        {
+          "name": "toggle",
+          "description": "When the open state changes (bubbles from the native `<details>`)."
+        }
       ]
     },
     {
@@ -3406,6 +3421,7 @@
     {
       "name": "schmancy-divider",
       "path": "./src/divider/divider.ts",
+      "description": "Thin horizontal (or vertical) separator rule between sections of content.",
       "attributes": [
         {
           "name": "outline",
@@ -3605,6 +3621,7 @@
     {
       "name": "schmancy-expand-root",
       "path": "./src/expand/expand-root.component.ts",
+      "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.",
       "attributes": [
         {
           "name": "type",
@@ -3629,6 +3646,7 @@
     {
       "name": "schmancy-expand",
       "path": "./src/expand/expand.component.ts",
+      "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.",
       "attributes": [
         {
           "name": "summary",
@@ -3720,11 +3738,18 @@
           "type": "boolean",
           "default": "false"
         }
+      ],
+      "events": [
+        {
+          "name": "toggle",
+          "description": "When the open state changes."
+        }
       ]
     },
     {
       "name": "schmancy-select-countries",
       "path": "./src/extra/countries/countries.ts",
+      "description": "Country picker — type-ahead autocomplete over the ISO 3166-1 country list. Form-associated.",
       "attributes": [
         {
           "name": "value",
@@ -3809,14 +3834,15 @@
       ],
       "events": [
         {
-          "name": "change"
+          "name": "change",
+          "description": "`SchmancyAutocompleteChangeEvent` with `{ value: string }` (the ISO code)."
         }
       ]
     },
     {
       "name": "schmancy-select-timezones",
       "path": "./src/extra/timezone/timezone.ts",
-      "description": "Timezone selector component with autocomplete filtering.",
+      "description": "Timezone picker — type-ahead autocomplete over the IANA tz database. Form-associated.",
       "attributes": [
         {
           "name": "hint",
@@ -3909,7 +3935,8 @@
       ],
       "events": [
         {
-          "name": "change"
+          "name": "change",
+          "description": "`SchmancyAutocompleteChangeEvent` with `{ value: string }` (the IANA tz name)."
         }
       ]
     },
@@ -4061,7 +4088,7 @@
     {
       "name": "schmancy-form",
       "path": "./src/form/form.ts",
-      "description": "A thin ergonomic wrapper around a native `<form>` element. Its children are\nreparented into a `<form>` element in light DOM on connection, so:\n\n- Form-associated custom elements (FACE) resolve their `internals.form`\n  correctly via native DOM ancestry.\n- `new FormData(form)` collects values from every FACE + native control\n  without any manual walking.\n- `form.reset()` triggers `formResetCallback()` on every FACE.\n- `form.reportValidity()` runs native validation UI.\n- `<button type=\"submit\">` and `<schmancy-button type=\"submit\">` both\n  submit the form via the native submitter pipeline.\n\nThis component exists only to translate the native `submit` / `reset`\nevents into the Schmancy event shape (`detail: FormData`). All heavy\nlifting 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.\n\n- Form-associated custom elements (FACE) resolve their `internals.form`\n  correctly via native DOM ancestry.\n- `new FormData(form)` collects values from every FACE + native control\n  without any manual walking.\n- `form.reset()` triggers `formResetCallback()` on every FACE.\n- `form.reportValidity()` runs native validation UI.\n- `<button type=\"submit\">` and `<schmancy-button type=\"submit\">` both\n  submit the form via the native submitter pipeline.\n\nThis component exists only to translate the native `submit` / `reset`\nevents into the Schmancy event shape (`detail: FormData`). All heavy\nlifting is the platform's.",
       "properties": [
         {
           "name": "tagName",
@@ -4291,7 +4318,7 @@
     {
       "name": "schmancy-input",
       "path": "./src/input/input.ts",
-      "description": "Enhanced version of the SchmancyInput component with improved form integration\nand compatibility with legacy API.\n\nThis component uses the native form association API and maintains parity with\nnative 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.",
       "attributes": [
         {
           "name": "value",
@@ -4574,10 +4601,19 @@
       ],
       "events": [
         {
-          "name": "reset"
+          "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."
         },
         {
-          "name": "input"
+          "name": "reset"
         },
         {
           "name": "focus"
@@ -4588,9 +4624,6 @@
         {
           "name": "autofill"
         },
-        {
-          "name": "enter"
-        },
         {
           "name": "click"
         }
@@ -4599,7 +4632,7 @@
     {
       "name": "sch-input",
       "path": "./src/input/input.ts",
-      "description": "Enhanced version of the SchmancyInput component with improved form integration\nand compatibility with legacy API.\n\nThis component uses the native form association API and maintains parity with\nnative 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.",
       "attributes": [
         {
           "name": "value",
@@ -4882,10 +4915,19 @@
       ],
       "events": [
         {
-          "name": "reset"
+          "name": "input",
+          "description": "`CustomEvent<{value: string}>` on every keystroke."
         },
         {
-          "name": "input"
+          "name": "change",
+          "description": "`CustomEvent<{value: string}>` on blur/change."
+        },
+        {
+          "name": "enter",
+          "description": "`CustomEvent<{value: string}>` when user presses Enter."
+        },
+        {
+          "name": "reset"
         },
         {
           "name": "focus"
@@ -4896,9 +4938,6 @@
         {
           "name": "autofill"
         },
-        {
-          "name": "enter"
-        },
         {
           "name": "click"
         }
@@ -5954,7 +5993,7 @@
     {
       "name": "schmancy-scroll",
       "path": "./src/layout/scroll/scroll.ts",
-      "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.",
       "attributes": [
         {
           "name": "hide",
@@ -8436,7 +8475,7 @@
     {
       "name": "schmancy-page",
       "path": "./src/page/page.ts",
-      "description": "Native mobile-like page container.\nPrevents double-tap zoom, pull-to-refresh, rubber-banding.\nAutomatically 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`.",
       "attributes": [
         {
           "name": "rows",
@@ -8578,7 +8617,7 @@
     {
       "name": "schmancy-radio-button",
       "path": "./src/radio-group/radio-button.ts",
-      "description": "Radio button component for use within radio groups.",
+      "description": "Single radio button — always rendered as a child of `<schmancy-radio-group>`, never standalone.",
       "attributes": [
         {
           "name": "checked",
@@ -8736,6 +8775,7 @@
     {
       "name": "schmancy-radio-group",
       "path": "./src/radio-group/radio-group.ts",
+      "description": "Radio-button group — single-select from a static list of mutually-exclusive options. Form-associated.",
       "attributes": [
         {
           "name": "options",
@@ -8875,7 +8915,8 @@
       ],
       "events": [
         {
-          "name": "change"
+          "name": "change",
+          "description": "`SchmancyRadioGroupChangeEvent` with the selected `value`."
         }
       ]
     },
@@ -8960,7 +9001,7 @@
     {
       "name": "schmancy-select",
       "path": "./src/select/select.ts",
-      "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.",
       "attributes": [
         {
           "name": "disabled",
@@ -9116,7 +9157,8 @@
       ],
       "events": [
         {
-          "name": "change"
+          "name": "change",
+          "description": "`SchmancySelectChangeEvent` with `{ value }` (single) or `{ value: string[] }` (multi)."
         }
       ]
     },
@@ -9570,7 +9612,7 @@
     {
       "name": "schmancy-surface",
       "path": "./src/surface/surface.ts",
-      "description": "`<schmancy-surface>` component\n\nThis component renders a styled container that adapts its dimensions based on the `fill` property.\nIt supports various rounding options, elevation levels, and applies background and text color classes\nbased on the specified surface variant. Additionally, when the `scroller` property is true, the component\nenables internal scrolling by applying overflow and scroll-behavior styles.\n\nSurfaceMixin 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.",
       "attributes": [
         {
           "name": "type",
@@ -9598,7 +9640,7 @@
     {
       "name": "schmancy-switch",
       "path": "./src/switch/switch.ts",
-      "description": "Binary on/off control. Form-associated, keyboard-accessible, semantically a\nswitch (ARIA role=\"switch\"). Distinct from `schmancy-checkbox`: a switch\nrepresents an immediate state change, a checkbox represents a selection in\na 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.",
       "attributes": [
         {
           "name": "value",
@@ -10003,7 +10045,7 @@
     {
       "name": "schmancy-textarea",
       "path": "./src/textarea/textarea.ts",
-      "description": "Textarea component with auto-resize and form integration.",
+      "description": "Multi-line text input with auto-resize and form integration. Form-associated.",
       "attributes": [
         {
           "name": "label",
@@ -10315,7 +10357,12 @@
       ],
       "events": [
         {
-          "name": "change"
+          "name": "input",
+          "description": "On every keystroke."
+        },
+        {
+          "name": "change",
+          "description": "On blur."
         },
         {
           "name": "enter"
@@ -10389,7 +10436,7 @@
     {
       "name": "schmancy-theme",
       "path": "./src/theme/theme.component.ts",
-      "description": "SchmancyThemeComponent - Provides theming capabilities for Schmancy components.\n\nThis component manages color schemes, primary colors, and theme distribution\nthroughout the component tree. It can be used at the root level or nested\nto 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-…)).",
       "attributes": [
         {
           "name": "color",
@@ -10515,6 +10562,7 @@
     {
       "name": "schmancy-tree",
       "path": "./src/tree/tree.ts",
+      "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.",
       "attributes": [
         {
           "name": "open",