@mhmo91/schmancy 0.9.16 → 0.9.17

package/custom-elements.json

@@ -1151,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": "",
@@ -1161,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",
@@ -1278,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",
@@ -3151,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",
@@ -3261,6 +3266,12 @@
           "type": "string",
           "default": "\"all\""
         }
+      ],
+      "events": [
+        {
+          "name": "toggle",
+          "description": "When the open state changes (bubbles from the native `<details>`)."
+        }
       ]
     },
     {
@@ -3410,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",
@@ -3609,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",
@@ -3633,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",
@@ -3724,6 +3738,12 @@
           "type": "boolean",
           "default": "false"
         }
+      ],
+      "events": [
+        {
+          "name": "toggle",
+          "description": "When the open state changes."
+        }
       ]
     },
     {
@@ -5973,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",
@@ -8455,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",
@@ -9592,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",
@@ -10416,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",
@@ -10542,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",

package/dist/agent/schmancy.agent.js

@@ -31767,10 +31767,18 @@ var qp = {
 				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>"]
 			}]
 		},
 		{
@@ -31780,6 +31788,13 @@ var qp = {
 				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",
@@ -31832,7 +31847,8 @@ var qp = {
 						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>"]
 			}]
 		},
 		{
@@ -31841,7 +31857,15 @@ var qp = {
 			declarations: [{
 				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>"]
 			}]
 		},
 		{
@@ -31851,6 +31875,13 @@ var qp = {
 				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",
@@ -31874,7 +31905,8 @@ var qp = {
 						type: { text: "string" },
 						default: "''"
 					}
-				]
+				],
+				examples: ["<schmancy-card-media src=\"/thumb.jpg\" alt=\"Product photo\"></schmancy-card-media>"]
 			}]
 		},
 		{
@@ -32755,6 +32787,13 @@ var qp = {
 				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",
@@ -32797,7 +32836,12 @@ var qp = {
 						type: { text: "string" },
 						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>"]
 			}]
 		},
 		{
@@ -32908,6 +32952,13 @@ var qp = {
 				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",
@@ -32930,7 +32981,8 @@ var qp = {
 						],
 						default: "'start'"
 					}
-				]
+				],
+				examples: ["<schmancy-list-item>First</schmancy-list-item>\n<schmancy-divider></schmancy-divider>\n<schmancy-list-item>Second</schmancy-list-item>"]
 			}]
 		},
 		{
@@ -33042,6 +33094,13 @@ var qp = {
 				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",
 					type: { text: "TSurfaceColor" },
@@ -33070,7 +33129,8 @@ var qp = {
 						"glassOforim"
 					],
 					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>"]
 			}]
 		},
 		{
@@ -33080,6 +33140,13 @@ var qp = {
 				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",
@@ -33121,7 +33188,12 @@ var qp = {
 						type: { text: "boolean" },
 						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>"]
 			}]
 		},
 		{
@@ -34682,7 +34754,13 @@ var qp = {
 				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",
@@ -34701,7 +34779,7 @@ var qp = {
 						default: "false"
 					}
 				],
-				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`"]
+				examples: ["<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>"]
 			}]
 		},
 		{
@@ -35280,7 +35358,13 @@ var qp = {
 				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",
 					type: { text: "TSurfaceColor" },
@@ -35712,7 +35796,13 @@ var qp = {
 				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",
@@ -35754,7 +35844,7 @@ var qp = {
 						description: "Theme configuration object containing all theme variables."
 					}
 				],
-				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>"],
+				examples: ["<!-- 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: [{
 					name: "themeContext",
 					kind: "provide"
@@ -35799,6 +35889,13 @@ var qp = {
 				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",
 					type: { text: "boolean" },
@@ -35811,7 +35908,8 @@ var qp = {
 				}, {
 					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>"]
 			}]
 		},
 		{
@@ -36358,7 +36456,13 @@ var qp = {
 				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",