@mhmo91/schmancy 0.9.16 → 0.9.18

package/src/navigation-rail/navigation-rail-item.ts

@@ -13,15 +13,11 @@ export type NavigationRailItemClickEvent = CustomEvent<{
 }>
 
 /**
- * Material Design 3 Navigation Rail Item Component
- * @see https://m3.material.io/components/navigation-rail/overview
- *
- * `<schmancy-navigation-rail-item>` component
- *
- * Individual navigation item for use within a navigation rail.
- * Represents a single destination or action with an icon and optional label.
+ * Single destination inside schmancy-navigation-rail — vertically-stacked icon + optional label. @see https://m3.material.io/components/navigation-rail/overview
  *
  * @element schmancy-navigation-rail-item
+ * @summary Always nested inside schmancy-navigation-rail. Use `icon` attr for a Material Symbols glyph, or slot=icon for custom content. Supports a `badge` slot for notification dots / counts.
+ * @platform button click - Styled vertical navigation target. Degrades to a plain `<button>` if the tag never registers.
  * @slot icon - Slot for the navigation item icon (e.g., schmancy-icon)
  * @slot - Default slot for custom content
  * @slot badge - Custom badge content

package/src/navigation-rail/navigation-rail.ts

@@ -15,16 +15,20 @@ export type NavigationRailFabClickEvent = CustomEvent<void>
 export type LabelVisibility = 'all' | 'selected' | 'none'
 
 /**
- * Material Design 3 Navigation Rail Component
- * @see https://m3.material.io/components/navigation-rail/overview
- *
- * `<schmancy-navigation-rail>` component
- *
- * A Material Design 3 vertical navigation component positioned on the left side of an application.
- * Navigation rails provide access to between 3-7 primary destinations with a compact footprint.
- * Automatically hides in fullscreen mode when triggered via schmancyTheme.next({ fullscreen: true }).
+ * Vertical navigation rail — Material Design 3 compact left-side nav for desktop / tablet layouts with 3–7 primary destinations. Auto-hides in fullscreen mode. @see https://m3.material.io/components/navigation-rail/overview
  *
  * @element schmancy-navigation-rail
+ * @summary Use as the desktop counterpart of schmancy-navigation-bar: same destinations, different form factor. Prefer schmancy-nav-drawer when you also want a drawer + app-bar combo.
+ * @example
+ * <schmancy-navigation-rail activeIndex="0">
+ *   <schmancy-icon-button slot="fab" variant="filled">
+ *     <schmancy-icon>add</schmancy-icon>
+ *   </schmancy-icon-button>
+ *   <schmancy-navigation-rail-item icon="home" label="Home"></schmancy-navigation-rail-item>
+ *   <schmancy-navigation-rail-item icon="search" label="Search"></schmancy-navigation-rail-item>
+ *   <schmancy-navigation-rail-item icon="settings" label="Settings"></schmancy-navigation-rail-item>
+ * </schmancy-navigation-rail>
+ * @platform nav - Vertical styled nav. Degrades to a plain vertical flex container if the tag never registers.
  * @slot fab - Slot for a floating action button at the top
  * @slot menu - Slot for a menu icon or button below the FAB
  * @slot header - Custom header content slot

package/src/page/page.ts

@@ -8,20 +8,17 @@ import { theme } from '../theme/theme.service'
 import { fromResizeObserver } from '../directives/layout'
 
 /**
- * Native mobile-like page container.
- * Prevents double-tap zoom, pull-to-refresh, rubber-banding.
- * Automatically fills remaining viewport height.
+ * 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`.
  *
  * @element schmancy-page
- *
+ * @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.
  * @example
- * html`
- *   <schmancy-page rows="1fr_2fr_auto">
- *     <header>App Bar</header>
- *     <main>Scrollable content</main>
- *     <footer>Navigation</footer>
- *   </schmancy-page>
- * `
+ * <schmancy-page rows="auto_1fr_auto">
+ *   <schmancy-nav-drawer-appbar>Title</schmancy-nav-drawer-appbar>
+ *   <main>Scrollable content</main>
+ *   <schmancy-navigation-bar></schmancy-navigation-bar>
+ * </schmancy-page>
+ * @platform div - 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.
  */
 @customElement('schmancy-page')
 export class SchmancyPage extends $LitElement(css`

package/src/sheet/sheet.ts

@@ -7,6 +7,23 @@ import { on } from './hook'
 import { SchmancySheetPosition, sheet } from './sheet.service'
 import { BLACKBIRD_EASING, DURATION_ENTER, DURATION_EXIT, DURATION_BACKDROP, EASE_OUT, EASE_IN } from '../utils/animation'
 
+/**
+ * Side-docked or bottom-docked panel — a dialog variant that slides in from an edge. Driven imperatively by the `sheet` service; rarely instantiated directly.
+ *
+ * @element schmancy-sheet
+ * @summary Prefer `sheet.open({ component, position })` over placing this element declaratively — the service handles stacking, focus, close on outside-click, ESC, and router integration.
+ * @example
+ * import { sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
+ * sheet.open({
+ *   component: new MyEditorElement(),
+ *   position: SchmancySheetPosition.Side,
+ *   title: 'Edit item',
+ * })
+ * @platform dialog close - Positioned-fixed panel with backdrop. Degrades to a `<dialog>` if the tag never registers — loses slide animation, keeps focus trap + dismiss.
+ * @attr position - `'side' | 'bottom'`. Which edge the sheet docks to.
+ * @attr open - Boolean; sheet is visible when true.
+ * @fires close - When the sheet is dismissed (backdrop click, close button, ESC).
+ */
 @customElement('schmancy-sheet')
 export default class SchmancySheet extends $LitElement(css`
 	:host {

package/src/surface/surface.ts

@@ -11,22 +11,16 @@ export const SchmancySurfaceTypeContext = createContext<TSurfaceColor>('surface'
 export type { SchmancySurfaceFill, SchmancySurfaceRounded, SchmancySurfaceElevation } from '@mixins/surface.mixin'
 
 /**
- * `<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.
+ * 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.
  *
  * @element schmancy-surface
- * @slot - Default slot for projecting child content.
- *
+ * @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.
  * @example
  * <schmancy-surface fill="all" rounded="all" elevation="3" type="surfaceBright" scroller>
  *   <p>Your scrollable content here</p>
  * </schmancy-surface>
+ * @platform div - Styled `<div>` with theme-driven background/color/elevation. Degrades to a plain `<div>` if the tag never registers — text stays readable, just loses theming.
+ * @slot - Default slot for projecting child content.
  */
 @customElement('schmancy-surface')
 export class SchmancySurface extends SurfaceMixin(

package/src/theme/theme.component.ts

@@ -27,28 +27,23 @@ const $colorScheme = new Observable<string>(subscriber => {
 })
 
 /**
- * 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.
+ * 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-…)).
  *
  * @element schmancy-theme
- *
+ * @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.
  * @example
- * ```html
  * <!-- Root theme provider -->
- * <schmancy-theme color="#6200ee" scheme="auto" root>
+ * <schmancy-theme root scheme="auto" color="#6200ee">
  *   <your-app></your-app>
  * </schmancy-theme>
- *
- * <!-- Nested theme for specific section -->
- * <schmancy-theme color="#2196f3" scheme="dark">
- *   <div class="dark-section">
- *     <!-- Components here will use blue dark theme -->
- *   </div>
+ * @example
+ * <!-- Nested theme for a specific section -->
+ * <schmancy-theme scheme="dark" color="#2196f3">
+ *   <schmancy-surface fill="all">
+ *     <!-- Components here use the blue dark theme -->
+ *   </schmancy-surface>
  * </schmancy-theme>
- * ```
+ * @platform div - 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.
  */
 @customElement('schmancy-theme')
 export class SchmancyThemeComponent extends $LitElement(tailwindStyles) {

package/src/tree/tree.ts

@@ -4,7 +4,19 @@ import { customElement, property, query } from 'lit/decorators.js'
 import { fromEvent, merge, switchMap, takeUntil, tap, zip } from 'rxjs'
 
 /**
+ * Expandable tree node — a recursive disclosure widget. One root slot, one default slot for child nodes. Each node can itself contain schmancy-tree children.
+ *
  * @element schmancy-tree
+ * @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).
+ * @example
+ * <schmancy-tree>
+ *   <schmancy-list-item slot="root">src/</schmancy-list-item>
+ *   <schmancy-tree>
+ *     <schmancy-list-item slot="root">components/</schmancy-list-item>
+ *     <schmancy-list-item>button.ts</schmancy-list-item>
+ *   </schmancy-tree>
+ * </schmancy-tree>
+ * @platform details toggle - Recursive `<details>`-like disclosure. Degrades to a plain nested list if the tag never registers — loses expand/collapse but stays navigable.
  * @slot root - The root element of the tree
  * @slot - The children of the tree
  */

package/types/src/breadcrumb/breadcrumb.d.ts

@@ -1,9 +1,16 @@
 declare const SchmancyBreadcrumb_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Breadcrumb navigation container. Wraps a list of `schmancy-breadcrumb-item`
- * elements with the correct ARIA landmark and semantics.
+ * Breadcrumb trail — navigation history from root to current page. Renders schmancy-breadcrumb-item children with separators between.
  *
  * @element schmancy-breadcrumb
+ * @summary Use for deep hierarchical navigation (file explorer paths, e-commerce category chains, admin settings trees). Last item is styled as the current page automatically.
+ * @example
+ * <schmancy-breadcrumb separator="›">
+ *   <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+ *   <schmancy-breadcrumb-item href="/docs">Docs</schmancy-breadcrumb-item>
+ *   <schmancy-breadcrumb-item>Getting started</schmancy-breadcrumb-item>
+ * </schmancy-breadcrumb>
+ * @platform nav - Styled `<nav aria-label="Breadcrumb">`. Degrades to a plain nav if the tag never registers.
  * @slot - Default slot for `<schmancy-breadcrumb-item>` children.
  * @attr separator - Character or string rendered between items. Default `/`.
  * @csspart separator - The separator element.
@@ -16,10 +23,13 @@ export declare class SchmancyBreadcrumb extends SchmancyBreadcrumb_base {
 }
 declare const SchmancyBreadcrumbItem_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Individual breadcrumb item. Renders as a link when `href` is provided,
- * otherwise as a plain span (represents the current page).
+ * Single segment in a schmancy-breadcrumb trail — a link when `href` is set, or a plain span (the current page) when omitted.
  *
  * @element schmancy-breadcrumb-item
+ * @summary Always nested inside schmancy-breadcrumb. Omit `href` on the current page — it gets aria-current="page" automatically.
+ * @example
+ * <schmancy-breadcrumb-item href="/products">Products</schmancy-breadcrumb-item>
+ * @platform a - Renders an `<a>` or `<span>` depending on href. Degrades to a plain anchor/span if the tag never registers.
  * @slot - Label content.
  * @attr href - If set, renders as an anchor.
  * @attr current - Marks as `aria-current="page"`.

package/types/src/card/actions.d.ts

@@ -1,6 +1,15 @@
 declare const SchmancyCardAction_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
+ * Action row of a schmancy-card — holds the card's buttons / links (typically aligned bottom-right).
+ *
  * @element schmancy-card-action
+ * @summary Always nested inside schmancy-card. Holds the primary + secondary CTAs for the card.
+ * @example
+ * <schmancy-card-action>
+ *   <schmancy-button variant="text">Cancel</schmancy-button>
+ *   <schmancy-button variant="filled">Save</schmancy-button>
+ * </schmancy-card-action>
+ * @platform div - Styled flex container. Degrades to a plain div if the tag never registers.
  * @slot - The content of the action
  */
 export default class SchmancyCardAction extends SchmancyCardAction_base {

package/types/src/card/card.d.ts

@@ -1,5 +1,23 @@
 import { LitElement } from 'lit';
 declare const SchmancyCard_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Material Design card — a surface-level container for grouping related content with media / content / actions slots.
+ *
+ * @element schmancy-card
+ * @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.
+ * @example
+ * <schmancy-card type="elevated" href="/items/42">
+ *   <schmancy-card-media src="/thumb.jpg" alt="Thumbnail"></schmancy-card-media>
+ *   <schmancy-card-content>
+ *     <h3>Title</h3>
+ *     <p>One-line description of the card's content.</p>
+ *   </schmancy-card-content>
+ *   <schmancy-card-action>
+ *     <schmancy-button variant="text">Open</schmancy-button>
+ *   </schmancy-card-action>
+ * </schmancy-card>
+ * @platform div - 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.
+ */
 export default class SchmancyCard extends SchmancyCard_base {
     protected static shadowRootOptions: {
         mode: string;

package/types/src/card/content.d.ts

@@ -1,6 +1,15 @@
 declare const SchmancyCardContent_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
+ * Content region of a schmancy-card — holds the card's headline, supporting text, and inline controls.
+ *
  * @element schmancy-card-content
+ * @summary Always nested inside schmancy-card. The padded content block between the media and action rows.
+ * @example
+ * <schmancy-card-content>
+ *   <h3>Card title</h3>
+ *   <p>Supporting text that describes the card's subject.</p>
+ * </schmancy-card-content>
+ * @platform div - Styled `<div>` with padding. Degrades to a plain div if the tag never registers.
  */
 export default class SchmancyCardContent extends SchmancyCardContent_base {
     protected render(): unknown;

package/types/src/card/media.d.ts

@@ -1,6 +1,12 @@
 declare const SchmancyCardMedia_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
+ * Media region of a schmancy-card — the image / thumbnail at the top of the card.
+ *
  * @element schmancy-card-media
+ * @summary Always nested inside schmancy-card. Pass `src` + `alt` props or slot an `<img>` / `<video>` for custom media.
+ * @example
+ * <schmancy-card-media src="/thumb.jpg" alt="Product photo"></schmancy-card-media>
+ * @platform img - Renders an `<img>` (or wraps a slotted media element). Degrades to a styled `<img>` if the tag never registers.
  */
 export default class SchmancyCardMedia extends SchmancyCardMedia_base {
     src: string;

package/types/src/details/details.d.ts

@@ -1,5 +1,17 @@
 import { LitElement } from 'lit';
 declare const SchmancyDetails_base: import("@mixins/index").Constructor<import("@mixins/index").ISurfaceMixin> & import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Expandable disclosure panel — a styled `<details>` / `<summary>` pair with animated expand + overlay options.
+ *
+ * @element schmancy-details
+ * @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.
+ * @example
+ * <schmancy-details summary="Shipping details">
+ *   <p>Order ships in 2 business days.</p>
+ * </schmancy-details>
+ * @platform details toggle - Wraps native `<details>`/`<summary>`. Degrades to the native element if the tag never registers — same keyboard accessibility, just no animation.
+ * @fires toggle - When the open state changes (bubbles from the native `<details>`).
+ */
 export default class SchmancyDetails extends SchmancyDetails_base {
     protected static shadowRootOptions: {
         mode: "open";

package/types/src/dialog/dialog.component.d.ts

@@ -1,27 +1,27 @@
 declare const SchmancyDialog_base: import("@mixins/index").Constructor<import("./dialog-base.mixin").IDialogBaseMixin> & CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Unified dialog component that handles both content-only and confirm modes.
+ * 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.
  *
  * @element schmancy-dialog
+ * @summary Blocks interaction with the rest of the page until dismissed. For quick confirmations, prefer `$dialog.confirm({ ... })` over this element. For arbitrary dialog content driven imperatively, prefer `$dialog.component(MyComponent)`.
+ * @platform dialog close - Positioned overlay in light DOM. Degrades to a styled `<dialog>` if the tag never registers — loses custom animations but keeps focus trap + ESC close.
  * @slot default - Content slot for dialog body (used in content mode)
  * @slot content - Named slot for custom content in confirm mode
+ * @fires confirm - In confirm mode, when the confirm button is clicked.
+ * @fires cancel - In confirm mode, when the cancel button or ESC is activated.
  *
  * @example Content mode (no buttons):
- * ```html
  * <schmancy-dialog>
  *   <my-custom-content></my-custom-content>
  * </schmancy-dialog>
- * ```
  *
  * @example Confirm mode (with buttons):
- * ```html
  * <schmancy-dialog
- *   title="Confirm Action"
- *   message="Are you sure?"
- *   confirm-text="Yes"
- *   cancel-text="No"
+ *   title="Delete item?"
+ *   message="This action cannot be undone."
+ *   confirm-text="Delete"
+ *   cancel-text="Keep"
  * ></schmancy-dialog>
- * ```
  */
 export declare class SchmancyDialog extends SchmancyDialog_base {
     /**

package/types/src/divider/divider.d.ts

@@ -1,4 +1,15 @@
 declare const SchmancyDivider_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Thin horizontal (or vertical) separator rule between sections of content.
+ *
+ * @element schmancy-divider
+ * @summary Semantic separator between groups — list items, menu sections, content blocks. Uses outline theme token.
+ * @example
+ * <schmancy-list-item>First</schmancy-list-item>
+ * <schmancy-divider></schmancy-divider>
+ * <schmancy-list-item>Second</schmancy-list-item>
+ * @platform hr - Styled horizontal rule. Degrades to a native `<hr>` if the tag never registers.
+ */
 export default class SchmancyDivider extends SchmancyDivider_base {
     outline: 'default' | 'variant';
     vertical: boolean;

package/types/src/dropdown/dropdown-component.d.ts

@@ -1,8 +1,20 @@
 declare const SchmancyDropdown_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * A dropdown component that displays content when triggered.
+ * 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.
  *
  * @element schmancy-dropdown
+ * @summary Prefer schmancy-menu for action lists, schmancy-autocomplete for type-ahead, schmancy-tooltip for hover hints. Reach for schmancy-dropdown when none of those fit — custom filters, color pickers, inline forms anchored to a trigger.
+ * @example
+ * <schmancy-dropdown>
+ *   <schmancy-button slot="trigger">Filters</schmancy-button>
+ *   <schmancy-dropdown-content>
+ *     <schmancy-form>…</schmancy-form>
+ *   </schmancy-dropdown-content>
+ * </schmancy-dropdown>
+ * @platform div - Anchored via Floating UI (autoUpdate, flip, shift). Degrades to inline content if the tag never registers — loses positioning but content stays accessible.
+ * @attr open - Boolean; whether the dropdown is visible.
+ * @fires open - When the dropdown opens.
+ * @fires close - When the dropdown closes.
  * @slot trigger - The element that triggers the dropdown
  * @slot - Default slot for the dropdown content
  */

package/types/src/dropdown/dropdown-content.d.ts

@@ -1,11 +1,19 @@
 declare const SchmancyDropdownContent_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Content container for the schmancy-dropdown component.
+ * Content panel for a schmancy-dropdown — a styled positioned surface. Always nested inside schmancy-dropdown and placed alongside the trigger slot.
  *
  * @element schmancy-dropdown-content
+ * @summary Nest this inside schmancy-dropdown (not in the trigger slot). Use the `content` CSS part to customize backgrounds / shadows / padding without shadow-root piercing.
+ * @example
+ * <schmancy-dropdown>
+ *   <schmancy-button slot="trigger">Open</schmancy-button>
+ *   <schmancy-dropdown-content>
+ *     Panel contents…
+ *   </schmancy-dropdown-content>
+ * </schmancy-dropdown>
+ * @platform div - Positioned panel with theme-aware styling. Degrades to an inline div if the tag never registers.
  * @slot - Default slot for dropdown content.
- * @csspart content - The inner wrapper element; style to override panel
- *   backgrounds, shadows, padding, or borders without shadow-root piercing.
+ * @csspart content - The inner wrapper element; style to override panel backgrounds, shadows, padding, or borders without shadow-root piercing.
  */
 export declare class SchmancyDropdownContent extends SchmancyDropdownContent_base {
     /**

package/types/src/expand/expand-root.component.d.ts

@@ -2,6 +2,18 @@ import { nothing } from 'lit';
 import type { TSurfaceColor } from '@schmancy/types';
 import '../surface/surface.js';
 declare const SchmancyExpandRoot_base: import("@mixins/index").Constructor<import("@mixins/index").ISurfaceMixin> & import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * 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.
+ *
+ * @element schmancy-expand-root
+ * @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).
+ * @example
+ * <schmancy-expand-root>
+ *   <schmancy-expand summary="Step 1">…</schmancy-expand>
+ *   <schmancy-expand summary="Step 2">…</schmancy-expand>
+ * </schmancy-expand-root>
+ * @platform div - Coordinating wrapper. Degrades to a plain div if the tag never registers — children fall back to independent `<details>` behavior.
+ */
 export declare class SchmancyExpandRoot extends SchmancyExpandRoot_base {
     type: TSurfaceColor;
     isOpen: boolean;

package/types/src/expand/expand.component.d.ts

@@ -1,6 +1,20 @@
 /** Dispatch this event on window to close whichever schmancy-expand is currently open */
 export declare const SCHMANCY_EXPAND_REQUEST_CLOSE = "schmancy-expand-request-close";
 declare const SchmancyExpand_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * 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.
+ *
+ * @element schmancy-expand
+ * @summary Use for grouped progressive-disclosure where only one section should be open at a time. Prefer schmancy-details when sections should be independent.
+ * @example
+ * <schmancy-expand-root>
+ *   <schmancy-expand summary="Billing">Billing form…</schmancy-expand>
+ *   <schmancy-expand summary="Shipping">Shipping form…</schmancy-expand>
+ *   <schmancy-expand summary="Review">Order review…</schmancy-expand>
+ * </schmancy-expand-root>
+ * @platform details toggle - Schmancy-skinned accordion section. Degrades to `<details>` if the tag never registers — loses mutual-exclusion behavior but stays functional.
+ * @fires toggle - When the open state changes.
+ */
 export default class SchmancyExpand extends SchmancyExpand_base {
     summary: string;
     open: boolean;

package/types/src/layout/scroll/scroll.d.ts

@@ -41,7 +41,11 @@ declare global {
 }
 declare const SchmancyScroll_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * A custom scrollable container with enhanced features.
+ * Scrollable container with debounced scroll events, horizontal/vertical direction, optional hidden scrollbar, and programmatic scrollTo via command events or refs.
+ *
+ * @element schmancy-scroll
+ * @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.
+ * @platform div - Styled scrollable `<div>`. Degrades to a plain scrollable div if the tag never registers — loses the debounced scroll event and the command-bus integration.
  *
  * @fires {SchmancyScrollEvent} scroll - Fired when scrolling occurs (with a configurable debounce)
  * @slot - Default slot for content to be scrolled

package/types/src/list/list-item.d.ts

@@ -1,7 +1,17 @@
 import { TSurfaceColor } from '@schmancy/types/surface';
 declare const SchmancyListItem_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
+ * 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.
+ *
  * @element schmancy-list-item
+ * @summary Prefer nesting inside schmancy-list for consistent spacing/surface. Use `href` to make the row a navigation target (renders as `<a>`), or a click handler for in-app actions.
+ * @example
+ * <schmancy-list-item href="/profile">
+ *   <schmancy-icon slot="leading">person</schmancy-icon>
+ *   Profile
+ *   <schmancy-icon slot="trailing">chevron_right</schmancy-icon>
+ * </schmancy-list-item>
+ * @platform li click - Styled `<li>` or `<a>` depending on `href`. Degrades to a plain list item if the tag never registers.
  * @slot leading - leading content
  * @slot trailing - trailing content
  * @slot - default content

package/types/src/list/list.d.ts

@@ -2,19 +2,18 @@ import { SchmancySurfaceFill } from '@schmancy/surface';
 import { TSurfaceColor } from '@schmancy/types/surface';
 declare const List_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * `<schmancy-list>` component.
- *
- * A list component that wraps its content within a customizable surface.
- * It allows you to set the surface type and fill style, and can optionally
- * enable scrolling behavior by delegating the scroller attribute to the surface.
+ * Wrapped list container — holds schmancy-list-item children on a themed surface. Optionally scrollable.
  *
  * @element schmancy-list
- * @slot - The default slot for list items.
- *
+ * @summary Use for vertical lists of similarly-shaped items: settings entries, menu items, contact lists, notification lists. Pair with schmancy-list-item children.
  * @example
  * <schmancy-list surface="container" scroller>
- *   <schmancy-list-item>List Item 1</schmancy-list-item>
+ *   <schmancy-list-item>First</schmancy-list-item>
+ *   <schmancy-list-item>Second</schmancy-list-item>
+ *   <schmancy-list-item>Third</schmancy-list-item>
  * </schmancy-list>
+ * @platform ul - Styled list container. Degrades to a plain ul/div if the tag never registers.
+ * @slot - The default slot for list items.
  */
 export declare class List extends List_base {
     /**

package/types/src/menu/menu-item.d.ts

@@ -1,4 +1,17 @@
 declare const SchmancyMenuItem_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Single item inside a schmancy-menu. Auto-dismisses the menu dialog on click — attach your action handler to `@click` and it just works.
+ *
+ * @element schmancy-menu-item
+ * @summary Always nested inside schmancy-menu. The click handler runs before the dialog closes, so `@click=${() => doThing()}` is the full pattern.
+ * @example
+ * <schmancy-menu-item @click=${() => archive()}>
+ *   <schmancy-icon slot="leading">archive</schmancy-icon>
+ *   Archive
+ * </schmancy-menu-item>
+ * @platform menuitem click - Wraps schmancy-list-item with auto-dismiss. Degrades to a styled `<button role="menuitem">` if the tag never registers.
+ * @slot - The item label and optional icons.
+ */
 export default class SchmancyMenuItem extends SchmancyMenuItem_base {
     protected render(): unknown;
 }

package/types/src/menu/menu.d.ts

@@ -1,30 +1,18 @@
 declare const SchmancyMenu_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Menu Component
+ * Floating menu — a trigger button + a list of schmancy-menu-item children that open as a positioned dialog on click.
  *
- * CRITICAL: The dialog ONLY renders the raw menu items passed via the default slot.
- * NO <ul> wrapper, NO classes, NO additional markup in the dialog call.
- * The dialog service handles positioning and display - we just pass the pure content.
- *
- * @example Basic menu with auto-dismiss
- * ```typescript
+ * @element schmancy-menu
+ * @summary Use for dropdown menus attached to a button or icon — "More actions", "Account", row overflow menus in tables. Clicking a schmancy-menu-item inside auto-dismisses; custom components slotted inside must call `$dialog.dismiss()` themselves.
+ * @example
  * <schmancy-menu>
- *   <schmancy-button slot="trigger">Actions</schmancy-button>
- *   <schmancy-menu-item @click=${() => editItem()}>Edit</schmancy-menu-item>
- *   <schmancy-menu-item @click=${() => deleteItem()}>Delete</schmancy-menu-item>
+ *   <schmancy-icon-button slot="trigger" aria-label="Actions">
+ *     <schmancy-icon>more_vert</schmancy-icon>
+ *   </schmancy-icon-button>
+ *   <schmancy-menu-item @click=${() => edit()}>Edit</schmancy-menu-item>
+ *   <schmancy-menu-item @click=${() => remove()}>Delete</schmancy-menu-item>
  * </schmancy-menu>
- * ```
- * Note: Dialog auto-dismisses when schmancy-menu-item is clicked
- *
- * @example Custom component (manual dismiss)
- * ```typescript
- * <schmancy-menu>
- *   <schmancy-icon-button slot="trigger">settings</schmancy-icon-button>
- *   <my-settings-form @submit=${() => $dialog.dismiss()}></my-settings-form>
- * </schmancy-menu>
- * ```
- * Note: Custom components must call $dialog.dismiss() manually
- *
+ * @platform menu close - Trigger + floating listbox dialog. Degrades to a native `<select>` or inline list if the tag never registers.
  * @slot trigger - Button to open menu (new naming)
  * @slot button - Button to open menu (backward compatible)
  * @slot default - Menu items or any custom component to display in dialog

package/types/src/nav-drawer/appbar.d.ts

@@ -1,6 +1,17 @@
 declare const SchmancyDrawerAppbar_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
+ * 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.
+ *
  * @element schmancy-nav-drawer-appbar
+ * @summary Always nested inside schmancy-nav-drawer. Holds the page-level title + top-right actions. On mobile, the drawer's hamburger button renders inside this region.
+ * @example
+ * <schmancy-nav-drawer-appbar>
+ *   <schmancy-typography type="title" token="lg">Dashboard</schmancy-typography>
+ *   <schmancy-icon-button slot="trailing" aria-label="Notifications">
+ *     <schmancy-icon>notifications</schmancy-icon>
+ *   </schmancy-icon-button>
+ * </schmancy-nav-drawer-appbar>
+ * @platform header - Styled horizontal bar. Degrades to a plain header element if the tag never registers.
  * @slot - The default slot
  */
 export declare class SchmancyDrawerAppbar extends SchmancyDrawerAppbar_base {