@mhmo91/schmancy 0.9.17 → 0.9.18

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 {

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

@@ -1,4 +1,15 @@
 declare const SchmancyNavigationDrawerContent_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Main content region inside schmancy-nav-drawer — typically hosts the router outlet or the page's body content.
+ *
+ * @element schmancy-nav-drawer-content
+ * @summary Always nested inside schmancy-nav-drawer. Scrollable by default; propagates scroll events up so the drawer can collapse app-bar on scroll.
+ * @example
+ * <schmancy-nav-drawer-content>
+ *   <schmancy-area name="main"></schmancy-area>
+ * </schmancy-nav-drawer-content>
+ * @platform main scroll - Scrollable `<main>`. Degrades to a plain scrollable div if the tag never registers.
+ */
 export declare class SchmancyNavigationDrawerContent extends SchmancyNavigationDrawerContent_base {
     connectedCallback(): void;
     render(): import("lit-html").TemplateResult<1>;

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

@@ -1,8 +1,23 @@
 import { TSchmancyDrawerNavbarMode, TSchmancyDrawerNavbarState } from './context';
 declare const SchmancyNavigationDrawer_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
+ * 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).
+ *
  * @element schmancy-nav-drawer
+ * @summary The app-shell layout primitive. Wrap your whole app in this when you want "persistent sidebar on desktop, drawer on mobile" behavior. Mode auto-switches at the breakpoint.
+ * @example
+ * <schmancy-nav-drawer>
+ *   <schmancy-nav-drawer-navbar>
+ *     <!-- nav items, typically schmancy-list-item links -->
+ *   </schmancy-nav-drawer-navbar>
+ *   <schmancy-nav-drawer-appbar>App title</schmancy-nav-drawer-appbar>
+ *   <schmancy-nav-drawer-content>
+ *     <!-- router outlet / page content -->
+ *   </schmancy-nav-drawer-content>
+ * </schmancy-nav-drawer>
+ * @platform div - Flex layout with viewport-width mode switching. Degrades to a stack of plain divs if the tag never registers.
  * @slot - The content slot
+ * @fires schmancy-drawer-state - When the drawer open/close state changes on mobile.
  */
 export declare class SchmancyNavigationDrawer extends SchmancyNavigationDrawer_base {
     fullscreen: boolean;

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

@@ -1,5 +1,19 @@
 import { TSchmancyDrawerNavbarMode, TSchmancyDrawerNavbarState } from './context';
 declare const SchmancyNavigationDrawerSidebar_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Sidebar region inside schmancy-nav-drawer — the persistent-on-desktop / modal-on-mobile nav rail.
+ *
+ * @element schmancy-nav-drawer-navbar
+ * @summary Always nested inside schmancy-nav-drawer. On desktop: pinned left sidebar. On mobile: modal overlay triggered by the hamburger button in schmancy-nav-drawer-appbar.
+ * @example
+ * <schmancy-nav-drawer-navbar>
+ *   <schmancy-list>
+ *     <schmancy-list-item href="/dashboard">Dashboard</schmancy-list-item>
+ *     <schmancy-list-item href="/settings">Settings</schmancy-list-item>
+ *   </schmancy-list>
+ * </schmancy-nav-drawer-navbar>
+ * @platform nav - Sidebar `<nav>` with responsive open/close behavior. Degrades to a plain sidebar div if the tag never registers.
+ */
 export declare class SchmancyNavigationDrawerSidebar extends SchmancyNavigationDrawerSidebar_base {
     mode: TSchmancyDrawerNavbarMode;
     drawerState: TSchmancyDrawerNavbarState;

package/types/src/navigation-bar/navigation-bar-item.d.ts

@@ -1,11 +1,10 @@
 declare const SchmancyNavigationBarItem_base: import("../../mixins").Constructor<CustomElementConstructor> & import("../../mixins").Constructor<import("@mixins/tailwind.mixin").ITailwindElementMixin> & import("../../mixins").Constructor<import("lit").LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 /**
- * `<schmancy-navigation-bar-item>` component
- *
- * Individual navigation item for use within a navigation bar.
- * Represents a single destination with an icon and optional label following Material Design 3 specifications.
+ * Single destination inside schmancy-navigation-bar — an icon + optional label representing one primary app destination.
  *
  * @element schmancy-navigation-bar-item
+ * @summary Always nested inside schmancy-navigation-bar. Use `icon` attr for a Material Symbols glyph or slot=icon for custom content.
+ * @platform button click - Styled navigation target. Degrades to a plain `<button>` if the tag never registers.
  * @slot icon - Slot for custom icon content
  * @slot - Default slot for custom content
  *

package/types/src/navigation-bar/navigation-bar.d.ts

@@ -1,16 +1,10 @@
 declare const SchmancyNavigationBar_base: import("../../mixins").Constructor<CustomElementConstructor> & import("../../mixins").Constructor<import("@mixins/tailwind.mixin").ITailwindElementMixin> & import("../../mixins").Constructor<import("lit").LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 /**
- * `<schmancy-navigation-bar>` component
- *
- * A horizontal navigation component following Material Design 3 specifications.
- * Navigation bars provide access to between 3-7 primary destinations.
- * Automatically hides in fullscreen mode when triggered via schmancyTheme.next({ fullscreen: true }).
- *
- * **IMPORTANT**: This component includes `z-10` by default (consistent with navigation-rail).
- * The consumer is responsible for positioning the navigation bar in their layout.
- * For typical bottom-fixed positioning, add: `class="fixed bottom-0 left-0 right-0"`.
+ * Bottom navigation bar — Material Design 3 horizontal nav for mobile primary destinations (3–7 items). Auto-hides in fullscreen mode.
  *
  * @element schmancy-navigation-bar
+ * @summary Use for mobile primary navigation (home, search, favorites, settings). For persistent desktop nav, prefer schmancy-navigation-rail or schmancy-nav-drawer. Consumer is responsible for fixed-bottom positioning via class.
+ * @platform nav - Styled horizontal nav with schmancy-navigation-bar-item children. Degrades to a plain flex container if the tag never registers.
  * @slot - Default slot for navigation bar items
  *
  * @fires navigation-change - When an item is selected

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

@@ -7,15 +7,11 @@ export type NavigationRailItemClickEvent = CustomEvent<{
 }>;
 declare const SchmancyNavigationRailItem_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * 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/types/src/navigation-rail/navigation-rail.d.ts

@@ -5,16 +5,20 @@ export type NavigationRailFabClickEvent = CustomEvent<void>;
 export type LabelVisibility = 'all' | 'selected' | 'none';
 declare const SchmancyNavigationRail_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * 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/types/src/sheet/sheet.d.ts

@@ -1,5 +1,22 @@
 import { SchmancySheetPosition } from './sheet.service';
 declare const SchmancySheet_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * 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).
+ */
 export default class SchmancySheet extends SchmancySheet_base {
     open: boolean;
     position: SchmancySheetPosition;