@mhmo91/schmancy 0.9.16 → 0.9.18

package/custom-elements.json

@@ -754,7 +754,7 @@
     {
       "name": "schmancy-breadcrumb",
       "path": "./src/breadcrumb/breadcrumb.ts",
-      "description": "Breadcrumb navigation container. Wraps a list of `schmancy-breadcrumb-item`\nelements 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.",
       "attributes": [
         {
           "name": "separator",
@@ -788,7 +788,7 @@
     {
       "name": "schmancy-breadcrumb-item",
       "path": "./src/breadcrumb/breadcrumb.ts",
-      "description": "Individual breadcrumb item. Renders as a link when `href` is provided,\notherwise 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.",
       "attributes": [
         {
           "name": "href",
@@ -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,12 +3266,18 @@
           "type": "string",
           "default": "\"all\""
         }
+      ],
+      "events": [
+        {
+          "name": "toggle",
+          "description": "When the open state changes (bubbles from the native `<details>`)."
+        }
       ]
     },
     {
       "name": "schmancy-dialog",
       "path": "./src/dialog/dialog.component.ts",
-      "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.",
       "attributes": [
         {
           "name": "uid",
@@ -3390,10 +3401,15 @@
       ],
       "events": [
         {
-          "name": "yes-dialog-here"
+          "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."
         },
         {
-          "name": "confirm"
+          "name": "yes-dialog-here"
         }
       ],
       "slots": [
@@ -3410,6 +3426,7 @@
     {
       "name": "schmancy-divider",
       "path": "./src/divider/divider.ts",
+      "description": "Thin horizontal (or vertical) separator rule between sections of content.",
       "attributes": [
         {
           "name": "outline",
@@ -3462,14 +3479,8 @@
     {
       "name": "schmancy-dropdown",
       "path": "./src/dropdown/dropdown-component.ts",
-      "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.",
       "attributes": [
-        {
-          "name": "open",
-          "description": "Whether the dropdown is currently open",
-          "type": "boolean",
-          "default": "false"
-        },
         {
           "name": "placement",
           "description": "Placement of the dropdown relative to the trigger",
@@ -3481,16 +3492,15 @@
           "description": "Offset distance in pixels",
           "type": "number",
           "default": "8"
-        }
-      ],
-      "properties": [
+        },
         {
           "name": "open",
-          "attribute": "open",
           "description": "Whether the dropdown is currently open",
           "type": "boolean",
           "default": "false"
-        },
+        }
+      ],
+      "properties": [
         {
           "name": "placement",
           "attribute": "placement",
@@ -3520,6 +3530,23 @@
         {
           "name": "triggerElements",
           "type": "HTMLElement[]"
+        },
+        {
+          "name": "open",
+          "attribute": "open",
+          "description": "Whether the dropdown is currently open",
+          "type": "boolean",
+          "default": "false"
+        }
+      ],
+      "events": [
+        {
+          "name": "open",
+          "description": "When the dropdown opens."
+        },
+        {
+          "name": "close",
+          "description": "When the dropdown closes."
         }
       ],
       "slots": [
@@ -3536,7 +3563,7 @@
     {
       "name": "schmancy-dropdown-content",
       "path": "./src/dropdown/dropdown-content.ts",
-      "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.",
       "attributes": [
         {
           "name": "width",
@@ -3602,13 +3629,14 @@
       "cssParts": [
         {
           "name": "content",
-          "description": "The inner wrapper element; style to override panel\nbackgrounds, shadows, padding, or borders without shadow-root piercing."
+          "description": "The inner wrapper element; style to override panel backgrounds, shadows, padding, or borders without shadow-root piercing."
         }
       ]
     },
     {
       "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 +3661,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 +3753,12 @@
           "type": "boolean",
           "default": "false"
         }
+      ],
+      "events": [
+        {
+          "name": "toggle",
+          "description": "When the open state changes."
+        }
       ]
     },
     {
@@ -5973,7 +6008,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",
@@ -6612,6 +6647,7 @@
     {
       "name": "schmancy-list-item",
       "path": "./src/list/list-item.ts",
+      "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.",
       "attributes": [
         {
           "name": "variant",
@@ -6672,7 +6708,7 @@
     {
       "name": "schmancy-list",
       "path": "./src/list/list.ts",
-      "description": "`<schmancy-list>` component.\n\nA list component that wraps its content within a customizable surface.\nIt allows you to set the surface type and fill style, and can optionally\nenable 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.",
       "attributes": [
         {
           "name": "surface",
@@ -7382,12 +7418,19 @@
     },
     {
       "name": "schmancy-menu-item",
-      "path": "./src/menu/menu-item.ts"
+      "path": "./src/menu/menu-item.ts",
+      "description": "Single item inside a schmancy-menu. Auto-dismisses the menu dialog on click — attach your action handler to `@click` and it just works.",
+      "slots": [
+        {
+          "name": "",
+          "description": "The item label and optional icons."
+        }
+      ]
     },
     {
       "name": "schmancy-menu",
       "path": "./src/menu/menu.ts",
-      "description": "Menu Component\n\nCRITICAL: The dialog ONLY renders the raw menu items passed via the default slot.\nNO <ul> wrapper, NO classes, NO additional markup in the dialog call.\nThe 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.",
       "slots": [
         {
           "name": "trigger",
@@ -7406,6 +7449,7 @@
     {
       "name": "schmancy-nav-drawer-appbar",
       "path": "./src/nav-drawer/appbar.ts",
+      "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.",
       "slots": [
         {
           "name": "",
@@ -7416,6 +7460,7 @@
     {
       "name": "schmancy-nav-drawer-content",
       "path": "./src/nav-drawer/content.ts",
+      "description": "Main content region inside schmancy-nav-drawer — typically hosts the router outlet or the page's body content.",
       "events": [
         {
           "name": "scroll"
@@ -7425,6 +7470,7 @@
     {
       "name": "schmancy-nav-drawer",
       "path": "./src/nav-drawer/drawer.ts",
+      "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).",
       "attributes": [
         {
           "name": "fullscreen",
@@ -7466,6 +7512,12 @@
           "type": "TSchmancyDrawerNavbarState"
         }
       ],
+      "events": [
+        {
+          "name": "schmancy-drawer-state",
+          "description": "When the drawer open/close state changes on mobile."
+        }
+      ],
       "slots": [
         {
           "name": "",
@@ -7476,6 +7528,7 @@
     {
       "name": "schmancy-nav-drawer-navbar",
       "path": "./src/nav-drawer/navbar.ts",
+      "description": "Sidebar region inside schmancy-nav-drawer — the persistent-on-desktop / modal-on-mobile nav rail.",
       "attributes": [
         {
           "name": "width",
@@ -7516,7 +7569,7 @@
     {
       "name": "schmancy-navigation-bar-item",
       "path": "./src/navigation-bar/navigation-bar-item.ts",
-      "description": "`<schmancy-navigation-bar-item>` component\n\nIndividual navigation item for use within a navigation bar.\nRepresents 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.",
       "attributes": [
         {
           "name": "icon",
@@ -7627,7 +7680,7 @@
     {
       "name": "schmancy-navigation-bar",
       "path": "./src/navigation-bar/navigation-bar.ts",
-      "description": "`<schmancy-navigation-bar>` component\n\nA horizontal navigation component following Material Design 3 specifications.\nNavigation bars provide access to between 3-7 primary destinations.\nAutomatically hides in fullscreen mode when triggered via schmancyTheme.next({ fullscreen: true }).\n\n**IMPORTANT**: This component includes `z-10` by default (consistent with navigation-rail).\nThe consumer is responsible for positioning the navigation bar in their layout.\nFor 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.",
       "attributes": [
         {
           "name": "activeIndex",
@@ -7703,7 +7756,7 @@
     {
       "name": "schmancy-navigation-rail-item",
       "path": "./src/navigation-rail/navigation-rail-item.ts",
-      "description": "Material Design 3 Navigation Rail Item Component",
+      "description": "Single destination inside schmancy-navigation-rail — vertically-stacked icon + optional label.",
       "attributes": [
         {
           "name": "icon",
@@ -7897,7 +7950,7 @@
     {
       "name": "schmancy-navigation-rail",
       "path": "./src/navigation-rail/navigation-rail.ts",
-      "description": "Material Design 3 Navigation Rail Component",
+      "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.",
       "attributes": [
         {
           "name": "activeIndex",
@@ -8455,7 +8508,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",
@@ -9145,17 +9198,8 @@
     {
       "name": "schmancy-sheet",
       "path": "./src/sheet/sheet.ts",
+      "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.",
       "attributes": [
-        {
-          "name": "open",
-          "type": "boolean",
-          "default": "false"
-        },
-        {
-          "name": "position",
-          "type": "SchmancySheetPosition",
-          "default": "\"side\""
-        },
         {
           "name": "persist",
           "type": "boolean",
@@ -9170,21 +9214,21 @@
           "name": "handleHistory",
           "type": "boolean",
           "default": "true"
-        }
-      ],
-      "properties": [
-        {
-          "name": "open",
-          "attribute": "open",
-          "type": "boolean",
-          "default": "false"
         },
         {
           "name": "position",
-          "attribute": "position",
+          "description": "`'side' | 'bottom'`. Which edge the sheet docks to.",
           "type": "SchmancySheetPosition",
           "default": "\"side\""
         },
+        {
+          "name": "open",
+          "description": "Boolean; sheet is visible when true.",
+          "type": "boolean",
+          "default": "false"
+        }
+      ],
+      "properties": [
         {
           "name": "persist",
           "attribute": "persist",
@@ -9202,11 +9246,26 @@
           "attribute": "handleHistory",
           "type": "boolean",
           "default": "true"
+        },
+        {
+          "name": "position",
+          "attribute": "position",
+          "description": "`'side' | 'bottom'`. Which edge the sheet docks to.",
+          "type": "SchmancySheetPosition",
+          "default": "\"side\""
+        },
+        {
+          "name": "open",
+          "attribute": "open",
+          "description": "Boolean; sheet is visible when true.",
+          "type": "boolean",
+          "default": "false"
         }
       ],
       "events": [
         {
-          "name": "close"
+          "name": "close",
+          "description": "When the sheet is dismissed (backdrop click, close button, ESC)."
         }
       ]
     },
@@ -9592,7 +9651,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 +10475,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 +10601,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",