@mhmo91/schmancy 0.9.16 → 0.9.18

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/page/page.d.ts

@@ -1,20 +1,17 @@
 import '../layout/scroll/scroll';
 declare const SchmancyPage_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * 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.
  */
 export declare class SchmancyPage extends SchmancyPage_base {
     /** Custom grid-template-rows using underscores (e.g. "1fr_2fr_auto") */

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;

package/types/src/surface/surface.d.ts

@@ -5,22 +5,16 @@ export declare const SchmancySurfaceTypeContext: {
 export type { SchmancySurfaceFill, SchmancySurfaceRounded, SchmancySurfaceElevation } from '@mixins/surface.mixin';
 declare const SchmancySurface_base: import("../../mixins").Constructor<import("@mixins/surface.mixin").ISurfaceMixin> & 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-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.
  */
 export declare class SchmancySurface extends SchmancySurface_base {
     /**

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

@@ -2,28 +2,23 @@ import { TSchmancyTheme } from './theme.interface';
 export declare const tailwindStyles: import("lit").CSSResult;
 declare const SchmancyThemeComponent_base: CustomElementConstructor & import("../../mixins/constructor").Constructor<import("lit").LitElement> & import("../../mixins/constructor").Constructor<import("../../mixins/baseElement").IBaseMixin>;
 /**
- * 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.
  */
 export declare class SchmancyThemeComponent extends SchmancyThemeComponent_base {
     /**

package/types/src/tree/tree.d.ts

@@ -1,6 +1,18 @@
 declare const SchmancyTree_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>;
 /**
+ * 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
  */