@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/_base/shared-styles.js

@@ -1,24 +1,49 @@
+/**
+ * @file components/_base/shared-styles.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { css } from 'lit';
 /**
- * Shared baseline injected into every Moni Web Component shadow root.
+ * Baseline CSS injected into the shadow root of **every** Moni Web Component.
+ *
+ * This stylesheet is the foundational layer of the Moni design system. It serves
+ * four distinct responsibilities:
+ *
+ * **1. Box-sizing reset**
+ * Applies `box-sizing: border-box` to `:host`, all descendants, and slotted
+ * elements so every component has predictable sizing without override surprises.
+ *
+ * **2. CSS custom property bridge (Token namespace)**
+ * The component library uses short "bare" variable names internally (e.g.
+ * `var(--primary)`) for concise CSS. Because shadow DOM isolates custom
+ * properties by default, this sheet creates a bridge that resolves these
+ * internal names from the global token namespaces in the following priority:
  *
- * Provides:
- *  1. Box-sizing reset on the host and its descendants.
- *  2. CSS custom property bridge: exposes the **BeerCSS token namespace**
- *     (`--primary`, `--on-primary`, `--surface`, `--elevate1`, …) inside the
- *     shadow root, falling back to sensible Material 3 defaults if the host
- *     document has not provided the alias yet.
- *  3. The `--md-sys-color-*` and `--color-*` aliases kept for backward
- *     compatibility with the MD3 theme engine that the rest of the Moni apps
- *     (MoniAuth-Client, MoniAuth-Yo, Moni-Labs) still rely on.
- *  4. Helper utility classes (`.truncate`, `.visually-hidden`).
+ *   `--moni-*` (Moni namespace) → `--md-sys-color-*` (MD3 spec) → hardcoded M3 default
  *
- * The MD3 → BeerCSS mapping is intentionally *inverted* with respect to the
- * previous design: BeerCSS variables are the primary, MD3 ones are aliases.
- * Components authored against `var(--primary)` will work in any environment
- * that ships the MD3 scheme because the alias resolves upstream.
+ * This lets a host document use any of the three namespaces to theme components.
+ *
+ * **3. MD3 `--color-*` aliases**
+ * A second `:host` block maps the older `--color-<role>` prefix to the primary
+ * bare tokens. These aliases ensure backward compatibility with Moni apps
+ * (MoniAuth-Client, MoniAuth-Yo) that still reference `--color-primary`, etc.
+ *
+ * **4. Utility classes**
+ * Provides `.truncate` (single-line text clipping) and `.visually-hidden`
+ * (screen-reader-only content) for use inside component shadow trees.
+ *
+ * **Usage:**
+ * ```ts
+ * static override styles = [sharedStyles, css`/* component-specific styles *\/`];
+ * ```
+ *
+ * @see {@link fieldStyles}       — Additional styles for input field components.
+ * @see {@link interactionStyles} — M3 state layer system for interactive elements.
  */
 export const sharedStyles = css `
+	/* ─── 1. Box-sizing reset ─────────────────────────────────────────────── */
 	:host {
 		box-sizing: border-box;
 		font-family: var(--font);
@@ -38,15 +63,67 @@ export const sharedStyles = css `
 		font-style: normal;
 	}
 
-	/* ─── BeerCSS primary tokens (with MD3 fallbacks) ─── */
+	/* ─── 2. CSS custom property bridge ──────────────────────────────────── */
+	/* Each token resolves in order: Moni namespace → MD3 spec → M3 default.   */
 	:host {
-		/* ─── BeerCSS structural tokens ─── */
+		/* ─── Primary palette ─── */
+		--primary: var(--moni-primary, var(--md-sys-color-primary, #6750A4));
+		--on-primary: var(--moni-on-primary, var(--md-sys-color-on-primary, #ffffff));
+		--primary-container: var(--moni-primary-container, var(--md-sys-color-primary-container, #eaddff));
+		--on-primary-container: var(--moni-on-primary-container, var(--md-sys-color-on-primary-container, #21005d));
+
+		/* ─── Secondary palette ─── */
+		--secondary: var(--moni-secondary, var(--md-sys-color-secondary, #625b71));
+		--on-secondary: var(--moni-on-secondary, var(--md-sys-color-on-secondary, #ffffff));
+		--secondary-container: var(--moni-secondary-container, var(--md-sys-color-secondary-container, #e8def8));
+		--on-secondary-container: var(--moni-on-secondary-container, var(--md-sys-color-on-secondary-container, #1d192b));
+
+		/* ─── Tertiary palette ─── */
+		--tertiary: var(--moni-tertiary, var(--md-sys-color-tertiary, #7d5260));
+		--on-tertiary: var(--moni-on-tertiary, var(--md-sys-color-on-tertiary, #ffffff));
+		--tertiary-container: var(--moni-tertiary-container, var(--md-sys-color-tertiary-container, #ffd8e4));
+		--on-tertiary-container: var(--moni-on-tertiary-container, var(--md-sys-color-on-tertiary-container, #31111d));
+
+		/* ─── Error palette ─── */
+		--error: var(--moni-error, var(--md-sys-color-error, #b3261e));
+		--on-error: var(--moni-on-error, var(--md-sys-color-on-error, #ffffff));
+		--error-container: var(--moni-error-container, var(--md-sys-color-error-container, #f9dedc));
+		--on-error-container: var(--moni-on-error-container, var(--md-sys-color-on-error-container, #410e0b));
+
+		/* ─── Background & surface ─── */
+		--background: var(--moni-background, var(--md-sys-color-background, #fef7ff));
+		--on-background: var(--moni-on-background, var(--md-sys-color-on-background, #1d1b20));
+		--surface: var(--moni-surface, var(--md-sys-color-surface, #fef7ff));
+		--on-surface: var(--moni-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+		--surface-variant: var(--moni-surface-variant, var(--md-sys-color-surface-variant, #e7e0ec));
+		--on-surface-variant: var(--moni-on-surface-variant, var(--md-sys-color-on-surface-variant, #49454f));
+
+		/* ─── Outline ─── */
+		--outline: var(--moni-outline, var(--md-sys-color-outline, #79747e));
+		--outline-variant: var(--moni-outline-variant, var(--md-sys-color-outline-variant, #cac4d0));
+
+		/* ─── Surface container hierarchy (5-level elevation tones) ─── */
+		--surface-container-lowest: var(--moni-surface-container-lowest, var(--md-sys-color-surface-container-lowest, #ffffff));
+		--surface-container-low: var(--moni-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+		--surface-container: var(--moni-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+		--surface-container-high: var(--moni-surface-container-high, var(--md-sys-color-surface-container-high, #ece6f0));
+		--surface-container-highest: var(--moni-surface-container-highest, var(--md-sys-color-surface-container-highest, #e6e1e5));
+
+		/* ─── Inverse surfaces (snackbar, tooltip) ─── */
+		--inverse-surface: var(--moni-inverse-surface, var(--md-sys-color-inverse-surface, #313033));
+		--inverse-on-surface: var(--moni-inverse-on-surface, var(--md-sys-color-inverse-on-surface, #f4f0f4));
+		--inverse-primary: var(--moni-inverse-primary, var(--md-sys-color-inverse-primary, #d0bcff));
+
+		/* ─── Structural / non-color tokens ─── */
+		/* Scrim overlay used in modals, bottom sheets, dialogs. */
 		--shadow: 0 0 0 0 transparent;
 		--scrim: rgb(0 0 0 / 0.5);
+		/* State layer color for hover/pressed overlays. */
 		--active: color-mix(in srgb, currentColor 10%, transparent);
 		--overlay: rgb(0 0 0 / 0.5);
 		--image: linear-gradient(currentColor 0 0);
 
+		/* ─── Typography tokens ─── */
 		--font: var(--moni-font-sans, 'Geist', system-ui, -apple-system, sans-serif);
 		--font-title: var(
 			--moni-font-title,
@@ -55,19 +132,25 @@ export const sharedStyles = css `
 			serif
 		);
 		--font-mono: 'Geist Mono', 'Fira Code', monospace;
+		/* Icon font: override via --font-icon-override to use a different icon set. */
 		--font-icon: var(--font-icon-override, 'Material Symbols Rounded');
 
+		/* ─── Elevation shadows (MD3 tonal levels 1–3) ─── */
 		--elevate1: 0 0.125rem 0.125rem 0 rgb(0 0 0 / 0.32);
 		--elevate2: 0 0.25rem 0.5rem 0 rgb(0 0 0 / 0.4);
 		--elevate3: 0 0.375rem 0.75rem 0 rgb(0 0 0 / 0.48);
 
+		/* ─── Transition speed scale ─── */
+		/* speed1 = fastest micro-interactions; speed4 = slowest page transitions. */
 		--speed1: 100ms;
 		--speed2: 200ms;
 		--speed3: 300ms;
 		--speed4: 400ms;
 	}
 
-	/* ─── MD3 aliases (kept for backward compatibility) ─── */
+	/* ─── 3. MD3 --color-* backward-compatibility aliases ─────────────── */
+	/* These map the older --color-<role> naming convention used in legacy     */
+	/* Moni apps to the primary bare tokens above. Do not remove.              */
 	:host {
 		--color-primary: var(--primary);
 		--color-on-primary: var(--on-primary);
@@ -109,8 +192,7 @@ export const sharedStyles = css `
 		--color-inverse-on-surface: var(--inverse-on-surface);
 		--color-inverse-primary: var(--inverse-primary);
 
-		/* Tokens previously defined in tokens.css — keep names stable so the
-		   apps that import them continue to work. */
+		/* Named aliases for tokens defined in the legacy tokens.css stylesheet. */
 		--font-sans: var(--font);
 		--shadow-1: var(--elevate1);
 		--shadow-2: var(--elevate2);
@@ -124,13 +206,23 @@ export const sharedStyles = css `
 		--duration-normal: 250ms;
 	}
 
-	/* ─── Utility classes ─── */
+	/* ─── 4. Utility classes ─────────────────────────────────────────────── */
+
+	/**
+	 * Clamps text to a single line with an ellipsis when overflow occurs.
+	 * Apply to any element inside a shadow root where text needs to be truncated.
+	 */
 	.truncate {
 		overflow: hidden;
 		white-space: nowrap;
 		text-overflow: ellipsis;
 	}
 
+	/**
+	 * Visually hides an element while keeping it accessible to screen readers
+	 * and maintaining its position in the DOM and tab order.
+	 * Use for labeling icon-only buttons, skip links, etc.
+	 */
 	.visually-hidden {
 		position: absolute;
 		width: 1px;

package/dist/components/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @file components/index.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 export { MoniBadge } from './moni-badge.js';
 export { MoniBottomSheet } from './moni-bottom-sheet.js';
 export { MoniButton } from './moni-button.js';

package/dist/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/components/index.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/index.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 // Auto-register all Moni UI Web Components.
 // Importing this file defines every <moni-*> custom element.
 export { MoniBadge } from './moni-badge.js';

package/dist/components/loading-shapes.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @file components/loading-shapes.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 export declare const loadingIndicatorPolygons: {
     '4-sided-cookie': string;
     '9-sided-cookie': string;

package/dist/components/loading-shapes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loading-shapes.d.ts","sourceRoot":"","sources":["../../src/components/loading-shapes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,wBAAwB;;;;;;;;CAQpC,CAAC"}
+{"version":3,"file":"loading-shapes.d.ts","sourceRoot":"","sources":["../../src/components/loading-shapes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;CAQpC,CAAC"}

package/dist/components/loading-shapes.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/loading-shapes.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 export const loadingIndicatorPolygons = {
     '4-sided-cookie': '63.83% 2.22%, 65.10% 1.70%, 66.36% 1.26%, 67.62% 0.89%, 68.88% 0.58%, 70.14% 0.34%, 71.39% 0.16%, 72.63% 0.05%, 73.86% 0.00%, 75.08% 0.01%, 76.28% 0.08%, 77.48% 0.21%, 78.66% 0.40%, 79.82% 0.63%, 80.97% 0.93%, 82.09% 1.27%, 83.20% 1.67%, 84.28% 2.11%, 85.34% 2.60%, 86.37% 3.14%, 87.38% 3.72%, 88.36% 4.35%, 89.31% 5.02%, 90.23% 5.73%, 91.12% 6.48%, 91.98% 7.26%, 92.80% 8.09%, 93.58% 8.94%, 94.32% 9.83%, 95.03% 10.76%, 95.70% 11.71%, 96.32% 12.69%, 96.90% 13.70%, 97.43% 14.74%, 97.92% 15.80%, 98.36% 16.88%, 98.76% 17.99%, 99.10% 19.12%, 99.38% 20.26%, 99.62% 21.43%, 99.80% 22.61%, 99.92% 23.80%, 99.99% 25.01%, 100.00% 26.23%, 99.94% 27.47%, 99.83% 28.71%, 99.65% 29.95%, 99.40% 31.21%, 99.09% 32.47%, 98.71% 33.73%, 98.26% 35.00%, 97.75% 36.25%, 97.26% 37.36%, 96.78% 38.47%, 96.30% 39.59%, 95.83% 40.72%, 95.42% 41.87%, 95.06% 43.03%, 94.76% 44.21%, 94.52% 45.40%, 94.33% 46.59%, 94.20% 47.79%, 94.12% 48.99%, 94.11% 50.19%, 94.14% 51.40%, 94.24% 52.60%, 94.39% 53.80%, 94.59% 54.99%, 94.85% 56.17%, 95.17% 57.34%, 95.55% 58.50%, 95.98% 59.65%, 96.45% 60.77%, 96.94% 61.89%, 97.42% 63.00%, 97.92% 64.15%, 98.41% 65.41%, 98.84% 66.68%, 99.20% 67.94%, 99.49% 69.20%, 99.71% 70.45%, 99.87% 71.70%, 99.97% 72.93%, 100.00% 74.16%, 99.97% 75.38%, 99.89% 76.58%, 99.75% 77.78%, 99.55% 78.95%, 99.30% 80.11%, 98.99% 81.25%, 98.63% 82.37%, 98.23% 83.47%, 97.77% 84.55%, 97.27% 85.60%, 96.72% 86.63%, 96.12% 87.63%, 95.49% 88.60%, 94.81% 89.55%, 94.09% 90.46%, 93.33% 91.34%, 92.54% 92.19%, 91.70% 93.00%, 90.84% 93.77%, 89.94% 94.51%, 89.01% 95.20%, 88.05% 95.86%, 87.06% 96.47%, 86.04% 97.04%, 85.00% 97.56%, 83.93% 98.04%, 82.84% 98.47%, 81.73% 98.85%, 80.60% 99.17%, 79.45% 99.45%, 78.28% 99.67%, 77.09% 99.84%, 75.89% 99.95%, 74.68% 100.00%, 73.46% 99.99%, 72.23% 99.92%, 70.98% 99.79%, 69.73% 99.59%, 68.48% 99.33%, 67.22% 99.00%, 65.95% 98.60%, 64.69% 98.14%, 63.47% 97.63%, 62.36% 97.14%, 61.25% 96.66%, 60.13% 96.18%, 58.99% 95.72%, 57.84% 95.32%, 56.67% 94.98%, 55.49% 94.70%, 54.31% 94.47%, 53.11% 94.29%, 51.91% 94.18%, 50.71% 94.11%, 49.50% 94.11%, 48.30% 94.16%, 47.10% 94.27%, 45.90% 94.43%, 44.71% 94.65%, 43.53% 94.93%, 42.36% 95.26%, 41.21% 95.65%, 40.07% 96.09%, 38.95% 96.58%, 37.84% 97.06%, 36.72% 97.54%, 35.54% 98.05%, 34.27% 98.53%, 33.01% 98.94%, 31.74% 99.28%, 30.49% 99.55%, 29.24% 99.76%, 27.99% 99.90%, 26.76% 99.98%, 25.53% 100.00%, 24.32% 99.96%, 23.12% 99.86%, 21.93% 99.70%, 20.76% 99.49%, 19.60% 99.23%, 18.47% 98.91%, 17.35% 98.54%, 16.26% 98.12%, 15.19% 97.65%, 14.14% 97.13%, 13.12% 96.57%, 12.12% 95.97%, 11.16% 95.32%, 10.22% 94.63%, 9.32% 93.90%, 8.45% 93.14%, 7.61% 92.33%, 6.81% 91.49%, 6.04% 90.62%, 5.32% 89.71%, 4.63% 88.77%, 3.99% 87.80%, 3.38% 86.81%, 2.83% 85.78%, 2.31% 84.74%, 1.85% 83.66%, 1.43% 82.57%, 1.07% 81.45%, 0.75% 80.31%, 0.49% 79.16%, 0.28% 77.98%, 0.13% 76.80%, 0.04% 75.59%, 0.00% 74.38%, 0.02% 73.15%, 0.11% 71.92%, 0.26% 70.67%, 0.47% 69.42%, 0.75% 68.16%, 1.09% 66.90%, 1.51% 65.64%, 1.99% 64.37%, 2.49% 63.19%, 2.98% 62.08%, 3.46% 60.97%, 3.94% 59.85%, 4.38% 58.71%, 4.77% 57.55%, 5.09% 56.38%, 5.37% 55.20%, 5.58% 54.01%, 5.74% 52.81%, 5.84% 51.61%, 5.89% 50.41%, 5.88% 49.20%, 5.82% 48.00%, 5.70% 46.80%, 5.52% 45.61%, 5.28% 44.42%, 4.99% 43.24%, 4.65% 42.07%, 4.25% 40.92%, 3.79% 39.78%, 3.30% 38.67%, 2.82% 37.56%, 2.34% 36.45%, 1.82% 35.22%, 1.36% 33.95%, 0.97% 32.69%, 0.65% 31.43%, 0.39% 30.18%, 0.20% 28.93%, 0.07% 27.68%, 0.01% 26.45%, 0.01% 25.23%, 0.06% 24.02%, 0.17% 22.82%, 0.34% 21.64%, 0.57% 20.47%, 0.85% 19.32%, 1.18% 18.19%, 1.56% 17.08%, 2.00% 15.99%, 2.48% 14.92%, 3.00% 13.88%, 3.57% 12.87%, 4.19% 11.88%, 4.85% 10.92%, 5.55% 9.99%, 6.29% 9.10%, 7.06% 8.23%, 7.88% 7.41%, 8.72% 6.61%, 9.61% 5.86%, 10.52% 5.14%, 11.47% 4.47%, 12.44% 3.83%, 13.45% 3.24%, 14.48% 2.69%, 15.53% 2.19%, 16.61% 1.74%, 17.71% 1.34%, 18.83% 0.98%, 19.98% 0.68%, 21.14% 0.43%, 22.31% 0.24%, 23.50% 0.10%, 24.71% 0.02%, 25.93% 0.00%, 27.16% 0.04%, 28.39% 0.14%, 29.64% 0.30%, 30.89% 0.53%, 32.15% 0.83%, 33.41% 1.19%, 34.68% 1.62%, 35.94% 2.12%, 37.08% 2.61%, 38.20% 3.10%, 39.31% 3.58%, 40.43% 4.06%, 41.58% 4.48%, 42.74% 4.85%, 43.91% 5.17%, 45.10% 5.43%, 46.29% 5.63%, 47.49% 5.77%, 48.69% 5.86%, 49.89% 5.90%, 51.10% 5.87%, 52.30% 5.79%, 53.50% 5.66%, 54.69% 5.47%, 55.88% 5.22%, 57.05% 4.91%, 58.21% 4.55%, 59.36% 4.14%, 60.49% 3.67%, 61.61% 3.18%, 62.72% 2.70%, 63.83% 2.22%',
     '9-sided-cookie': '61.39% 5.18%, 62.25% 5.81%, 63.15% 6.37%, 64.08% 6.88%, 65.04% 7.33%, 66.03% 7.71%, 67.04% 8.02%, 68.07% 8.27%, 69.11% 8.45%, 70.17% 8.57%, 71.18% 8.61%, 72.43% 8.63%, 73.38% 8.68%, 74.46% 8.80%, 75.52% 9.00%, 76.56% 9.26%, 77.57% 9.59%, 78.55% 9.98%, 79.50% 10.44%, 80.42% 10.95%, 81.30% 11.52%, 82.14% 12.14%, 82.93% 12.81%, 83.69% 13.54%, 84.39% 14.31%, 85.05% 15.13%, 85.65% 15.99%, 86.20% 16.89%, 86.69% 17.84%, 87.12% 18.81%, 87.49% 19.83%, 87.79% 20.87%, 87.99% 21.78%, 88.22% 23.01%, 88.46% 24.01%, 88.76% 25.02%, 89.14% 26.02%, 89.57% 26.98%, 90.07% 27.91%, 90.63% 28.81%, 91.24% 29.67%, 91.91% 30.49%, 92.64% 31.27%, 93.40% 31.98%, 94.34% 32.79%, 95.02% 33.41%, 95.78% 34.19%, 96.48% 35.02%, 97.12% 35.88%, 97.70% 36.77%, 98.21% 37.69%, 98.66% 38.65%, 99.05% 39.62%, 99.37% 40.62%, 99.63% 41.63%, 99.82% 42.66%, 99.94% 43.70%, 100.00% 44.74%, 99.99% 45.79%, 99.91% 46.84%, 99.76% 47.88%, 99.54% 48.92%, 99.26% 49.95%, 98.90% 50.97%, 98.47% 51.97%, 98.04% 52.81%, 97.43% 53.91%, 96.96% 54.80%, 96.53% 55.77%, 96.16% 56.77%, 95.86% 57.78%, 95.63% 58.81%, 95.46% 59.86%, 95.36% 60.91%, 95.34% 61.97%, 95.38% 63.03%, 95.49% 64.09%, 95.68% 65.27%, 95.82% 66.19%, 95.91% 67.28%, 95.93% 68.36%, 95.88% 69.43%, 95.76% 70.49%, 95.57% 71.53%, 95.32% 72.55%, 95.00% 73.55%, 94.61% 74.53%, 94.17% 75.47%, 93.66% 76.39%, 93.10% 77.27%, 92.48% 78.11%, 91.81% 78.92%, 91.09% 79.68%, 90.31% 80.39%, 89.48% 81.06%, 88.61% 81.68%, 87.69% 82.23%, 86.73% 82.74%, 85.81% 83.14%, 84.74% 83.55%, 83.75% 83.94%, 82.78% 84.40%, 81.85% 84.91%, 80.96% 85.49%, 80.11% 86.11%, 79.30% 86.80%, 78.54% 87.53%, 77.83% 88.31%, 77.17% 89.14%, 76.56% 90.02%, 75.97% 90.98%, 75.43% 91.87%, 74.84% 92.73%, 74.17% 93.59%, 73.45% 94.38%, 72.69% 95.13%, 71.89% 95.82%, 71.04% 96.45%, 70.16% 97.02%, 69.25% 97.53%, 68.30% 97.99%, 67.34% 98.38%, 66.34% 98.71%, 65.33% 98.97%, 64.30% 99.17%, 63.26% 99.30%, 62.21% 99.37%, 61.15% 99.37%, 60.08% 99.29%, 59.02% 99.15%, 57.96% 98.93%, 56.92% 98.65%, 55.99% 98.34%, 54.89% 97.96%, 53.86% 97.67%, 52.82% 97.46%, 51.77% 97.31%, 50.72% 97.23%, 49.66% 97.21%, 48.61% 97.27%, 47.55% 97.39%, 46.51% 97.59%, 45.48% 97.85%, 44.51% 98.16%, 43.35% 98.56%, 42.42% 98.84%, 41.36% 99.08%, 40.30% 99.25%, 39.24% 99.35%, 38.18% 99.38%, 37.12% 99.34%, 36.07% 99.23%, 35.04% 99.05%, 34.02% 98.81%, 33.02% 98.50%, 32.04% 98.13%, 31.09% 97.70%, 30.17% 97.21%, 29.27% 96.66%, 28.42% 96.05%, 27.60% 95.38%, 26.82% 94.66%, 26.08% 93.88%, 25.40% 93.04%, 24.76% 92.16%, 24.27% 91.38%, 23.64% 90.33%, 23.06% 89.45%, 22.42% 88.60%, 21.72% 87.80%, 20.98% 87.05%, 20.19% 86.35%, 19.35% 85.70%, 18.47% 85.11%, 17.56% 84.58%, 16.60% 84.10%, 15.67% 83.70%, 14.49% 83.26%, 13.63% 82.90%, 12.65% 82.42%, 11.72% 81.88%, 10.83% 81.29%, 9.98% 80.64%, 9.19% 79.94%, 8.45% 79.20%, 7.75% 78.41%, 7.12% 77.58%, 6.53% 76.71%, 6.01% 75.81%, 5.54% 74.87%, 5.14% 73.91%, 4.80% 72.92%, 4.52% 71.90%, 4.30% 70.87%, 4.16% 69.82%, 4.08% 68.75%, 4.08% 67.67%, 4.15% 66.59%, 4.26% 65.66%, 4.47% 64.41%, 4.59% 63.41%, 4.66% 62.35%, 4.66% 61.29%, 4.59% 60.23%, 4.44% 59.18%, 4.24% 58.15%, 3.96% 57.13%, 3.62% 56.12%, 3.21% 55.14%, 2.73% 54.19%, 2.14% 53.14%, 1.71% 52.32%, 1.25% 51.33%, 0.87% 50.32%, 0.55% 49.29%, 0.31% 48.25%, 0.14% 47.21%, 0.04% 46.16%, 0.00% 45.11%, 0.03% 44.07%, 0.13% 43.03%, 0.30% 42.00%, 0.53% 40.98%, 0.83% 39.98%, 1.19% 38.99%, 1.62% 38.03%, 2.11% 37.10%, 2.67% 36.19%, 3.28% 35.32%, 3.96% 34.48%, 4.70% 33.69%, 5.41% 33.02%, 6.33% 32.22%, 7.09% 31.54%, 7.84% 30.78%, 8.53% 29.97%, 9.16% 29.12%, 9.74% 28.24%, 10.26% 27.32%, 10.72% 26.37%, 11.11% 25.38%, 11.45% 24.37%, 11.71% 23.34%, 11.94% 22.20%, 12.13% 21.24%, 12.40% 20.20%, 12.75% 19.17%, 13.15% 18.18%, 13.62% 17.23%, 14.15% 16.31%, 14.73% 15.43%, 15.37% 14.60%, 16.06% 13.81%, 16.80% 13.07%, 17.58% 12.37%, 18.40% 11.73%, 19.27% 11.14%, 20.17% 10.61%, 21.11% 10.14%, 22.08% 9.72%, 23.08% 9.37%, 24.11% 9.09%, 25.16% 8.87%, 26.24% 8.72%, 27.27% 8.64%, 28.33% 8.62%, 29.45% 8.59%, 30.51% 8.50%, 31.56% 8.34%, 32.60% 8.12%, 33.62% 7.83%, 34.61% 7.47%, 35.58% 7.05%, 36.52% 6.56%, 37.43% 6.02%, 38.31% 5.41%, 39.15% 4.75%, 39.15% 4.75%, 40.04% 4.03%, 40.85% 3.44%, 41.76% 2.86%, 42.71% 2.35%, 43.68% 1.90%, 44.67% 1.52%, 45.68% 1.21%, 46.70% 0.96%, 47.73% 0.78%, 48.77% 0.67%, 49.81% 0.62%, 50.86% 0.65%, 51.90% 0.73%, 52.94% 0.89%, 53.96% 1.11%, 54.98% 1.40%, 55.97% 1.76%, 56.95% 2.18%, 57.90% 2.67%, 58.83% 3.23%, 59.73% 3.85%, 60.46% 4.43%',

package/dist/components/moni-app-bar.d.ts

@@ -1,47 +1,142 @@
+/**
+ * @file components/moni-app-bar.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Material 3 App Bar (`m3-docs/components/app-bars/specs.md`).
- *
- * App bars are placed at the top of a screen to help users navigate.
- * Two main placements:
- *  - **top** (default): header above content. Standard height **64dp**.
- *  - **bottom**: footer below content (mobile pattern). Houses navigation
- *    icons and an optional FAB anchor.
- *
- * Two variants:
- *  - **standard** (default): flat surface with no shadow at rest.
- *  - **floating**: gains an elevation 2 shadow when content scrolls under it.
- *
- * Two size modes:
- *  - **default**: 64dp tall.
- *  - **prominent**: 152dp tall, used when a subtitle is shown.
- *
- * Center-aligned title (M3 spec): title is centered horizontally.
- * Navigation icons go to the leading edge; actions to the trailing edge.
- *
- * Attributes:
- *  - placement:  top (default) | bottom
- *  - variant:   standard (default) | floating
- *  - size:      default (default, 64dp) | prominent (152dp)
- *  - title:     text content of the title (centered)
- *  - subtitle:  optional subtitle shown below the title (prominent only)
- *  - elevated:  present → adds elevation 2 shadow (e.g. when scrolled)
- *
- * Slots:
- *  - leading:  navigation icon(s) on the leading edge
- *  - trailing: action icon(s) on the trailing edge
- *  - fab:      (bottom only) FAB anchored to the trailing edge
- *  - default:  any extra content (e.g. tabs)
+ * Material Design 3 App Bar component.
+ *
+ * App bars provide navigation and action controls at the top (or bottom) of a
+ * screen. They are positioned sticky by default so they remain visible as the
+ * user scrolls through content.
+ *
+ * **M3 spec reference:** `m3-docs/components/app-bars/specs.md`
+ *
+ * **Placement:**
+ * - `top` (default) — 64dp header fixed above page content. Uses `position: sticky`
+ *   with `inset-block-start: 0` so it stays at the top of the scroll container.
+ * - `bottom` — Mobile navigation footer anchored to the bottom of the viewport.
+ *   Ideal for housing primary navigation icons and an optional FAB.
+ *
+ * **Variants:**
+ * - `standard` — Flat surface (no shadow) when content is at the top. Best for most UIs.
+ * - `floating` — Always elevated with `--elevate2` shadow. Use when the bar visually
+ *   floats above the content regardless of scroll position.
+ *
+ * **Sizes:**
+ * - `default` — 64dp (4rem) tall. Standard for most use cases.
+ * - `prominent` — 152dp (9.5rem) tall. Use when a subtitle or expanded area is needed.
+ *   The `subtitle` attribute is only rendered in this size.
+ *
+ * @example
+ * ```html
+ * <!-- Top app bar with navigation icon and action buttons -->
+ * <moni-app-bar title="Settings">
+ *   <moni-button slot="leading" shape="circle" variant="text" icon="menu"></moni-button>
+ *   <moni-button slot="trailing" shape="circle" variant="text" icon="search"></moni-button>
+ *   <moni-button slot="trailing" shape="circle" variant="text" icon="more_vert"></moni-button>
+ * </moni-app-bar>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Prominent app bar with subtitle -->
+ * <moni-app-bar size="prominent" title="Inbox" subtitle="12 unread messages" elevated>
+ * </moni-app-bar>
+ * ```
+ *
+ * @slot leading   - Navigation icon(s) placed on the leading (start) edge.
+ * @slot trailing  - Action icon(s) placed on the trailing (end) edge.
+ * @slot fab       - FAB anchored to the trailing edge (bottom placement only).
+ * @slot default   - Additional content (e.g. a tab bar below the title row).
+ *
+ * @csspart bar      - The inner grid container.
+ * @csspart leading  - The leading slot wrapper.
+ * @csspart trailing - The trailing slot wrapper.
+ * @csspart title    - The title text element.
+ * @csspart subtitle - The subtitle text element (prominent size only).
+ * @csspart actions  - The actions slot wrapper (prominent size only).
  */
 export declare class MoniAppBar extends MoniElement {
+    /**
+     * Determines whether the bar is placed at the top or bottom of the viewport.
+     *
+     * - `'top'` (default) — Sticky header at the top of the scroll container.
+     * - `'bottom'` — Fixed footer; primarily used for mobile bottom navigation patterns.
+     *
+     * @default 'top'
+     */
     placement: 'top' | 'bottom';
+    /**
+     * Visual variant of the app bar.
+     *
+     * - `'standard'` (default) — Flat surface. No shadow at rest; gains shadow
+     *   programmatically via the `elevated` attribute when content scrolls beneath it.
+     * - `'floating'` — Permanently elevated with `--elevate2` box-shadow.
+     *
+     * @default 'standard'
+     */
     variant: 'standard' | 'floating';
+    /**
+     * Height variant of the app bar.
+     *
+     * - `'default'` — 64dp (4rem). Standard M3 top app bar height.
+     * - `'prominent'` — 152dp (9.5rem). Use when showing a subtitle or when
+     *   extra vertical space is needed for a contextual action row.
+     *
+     * @default 'default'
+     */
     size: 'default' | 'prominent';
+    /**
+     * Title text displayed in the center of the app bar.
+     *
+     * The title is center-aligned per M3 spec. Long titles are truncated with
+     * an ellipsis. For semantic HTML, the consumer should also provide an `<h1>`
+     * in the page content that matches this title.
+     *
+     * @default ''
+     */
     title: string;
+    /**
+     * Optional subtitle displayed below the title.
+     *
+     * Only rendered when `size="prominent"`. Provides secondary context
+     * (e.g. folder name, item count, description).
+     *
+     * @default ''
+     */
     subtitle: string;
+    /**
+     * When present, applies `--elevate2` box-shadow to signal that content has
+     * scrolled beneath the bar.
+     *
+     * Consumers are responsible for toggling this attribute reactively based on
+     * the scroll position of the main content area:
+     * ```ts
+     * container.addEventListener('scroll', () => {
+     *   appBar.elevated = container.scrollTop > 0;
+     * });
+     * ```
+     *
+     * @default false
+     */
     elevated: boolean;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    /**
+     * Renders the app bar grid layout.
+     *
+     * The inner `.bar` element uses a 3-column CSS grid:
+     * - Column 1: leading slot (navigation icon).
+     * - Column 2: title (center-aligned, fills remaining space).
+     * - Column 3: trailing slot (action icons).
+     *
+     * In `prominent` size, a subtitle row and an actions row are appended
+     * conditionally. The subtitle only renders when the `subtitle` attribute
+     * is non-empty; the actions slot always renders for prominent bars.
+     */
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-app-bar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-app-bar.d.ts","sourceRoot":"","sources":["../../src/components/moni-app-bar.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBACa,UAAW,SAAQ,WAAW;IAE1C,SAAS,EAAE,KAAK,GAAG,QAAQ,CAAS;IAEpC,OAAO,EAAE,UAAU,GAAG,UAAU,CAAc;IAE9C,IAAI,EAAE,SAAS,GAAG,WAAW,CAAa;IACb,KAAK,SAAM;IACX,QAAQ,SAAM;IACC,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BAyGpB;IAEO,MAAM;CAwBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,UAAU,CAAC;KAC3B;CACD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"moni-app-bar.d.ts","sourceRoot":"","sources":["../../src/components/moni-app-bar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C;;;;;;;OAOG;IAEH,SAAS,EAAE,KAAK,GAAG,QAAQ,CAAS;IAEpC;;;;;;;;OAQG;IAEH,OAAO,EAAE,UAAU,GAAG,UAAU,CAAc;IAE9C;;;;;;;;OAQG;IAEH,IAAI,EAAE,SAAS,GAAG,WAAW,CAAa;IAE1C;;;;;;;;OAQG;IAC0B,KAAK,SAAM;IAExC;;;;;;;OAOG;IAC0B,QAAQ,SAAM;IAE3C;;;;;;;;;;;;;OAaG;IACyC,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BAyGpB;IAEF;;;;;;;;;;;OAWG;IACM,MAAM;CAwBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,UAAU,CAAC;KAC3B;CACD;AAED,eAAe,UAAU,CAAC"}

package/dist/components/moni-app-bar.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-app-bar.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -8,47 +14,124 @@ import { html, css, nothing } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material 3 App Bar (`m3-docs/components/app-bars/specs.md`).
+ * Material Design 3 App Bar component.
+ *
+ * App bars provide navigation and action controls at the top (or bottom) of a
+ * screen. They are positioned sticky by default so they remain visible as the
+ * user scrolls through content.
+ *
+ * **M3 spec reference:** `m3-docs/components/app-bars/specs.md`
+ *
+ * **Placement:**
+ * - `top` (default) — 64dp header fixed above page content. Uses `position: sticky`
+ *   with `inset-block-start: 0` so it stays at the top of the scroll container.
+ * - `bottom` — Mobile navigation footer anchored to the bottom of the viewport.
+ *   Ideal for housing primary navigation icons and an optional FAB.
  *
- * App bars are placed at the top of a screen to help users navigate.
- * Two main placements:
- *  - **top** (default): header above content. Standard height **64dp**.
- *  - **bottom**: footer below content (mobile pattern). Houses navigation
- *    icons and an optional FAB anchor.
+ * **Variants:**
+ * - `standard` — Flat surface (no shadow) when content is at the top. Best for most UIs.
+ * - `floating` — Always elevated with `--elevate2` shadow. Use when the bar visually
+ *   floats above the content regardless of scroll position.
  *
- * Two variants:
- *  - **standard** (default): flat surface with no shadow at rest.
- *  - **floating**: gains an elevation 2 shadow when content scrolls under it.
+ * **Sizes:**
+ * - `default` — 64dp (4rem) tall. Standard for most use cases.
+ * - `prominent` — 152dp (9.5rem) tall. Use when a subtitle or expanded area is needed.
+ *   The `subtitle` attribute is only rendered in this size.
  *
- * Two size modes:
- *  - **default**: 64dp tall.
- *  - **prominent**: 152dp tall, used when a subtitle is shown.
+ * @example
+ * ```html
+ * <!-- Top app bar with navigation icon and action buttons -->
+ * <moni-app-bar title="Settings">
+ *   <moni-button slot="leading" shape="circle" variant="text" icon="menu"></moni-button>
+ *   <moni-button slot="trailing" shape="circle" variant="text" icon="search"></moni-button>
+ *   <moni-button slot="trailing" shape="circle" variant="text" icon="more_vert"></moni-button>
+ * </moni-app-bar>
+ * ```
  *
- * Center-aligned title (M3 spec): title is centered horizontally.
- * Navigation icons go to the leading edge; actions to the trailing edge.
+ * @example
+ * ```html
+ * <!-- Prominent app bar with subtitle -->
+ * <moni-app-bar size="prominent" title="Inbox" subtitle="12 unread messages" elevated>
+ * </moni-app-bar>
+ * ```
  *
- * Attributes:
- *  - placement:  top (default) | bottom
- *  - variant:   standard (default) | floating
- *  - size:      default (default, 64dp) | prominent (152dp)
- *  - title:     text content of the title (centered)
- *  - subtitle:  optional subtitle shown below the title (prominent only)
- *  - elevated:  present → adds elevation 2 shadow (e.g. when scrolled)
+ * @slot leading   - Navigation icon(s) placed on the leading (start) edge.
+ * @slot trailing  - Action icon(s) placed on the trailing (end) edge.
+ * @slot fab       - FAB anchored to the trailing edge (bottom placement only).
+ * @slot default   - Additional content (e.g. a tab bar below the title row).
  *
- * Slots:
- *  - leading:  navigation icon(s) on the leading edge
- *  - trailing: action icon(s) on the trailing edge
- *  - fab:      (bottom only) FAB anchored to the trailing edge
- *  - default:  any extra content (e.g. tabs)
+ * @csspart bar      - The inner grid container.
+ * @csspart leading  - The leading slot wrapper.
+ * @csspart trailing - The trailing slot wrapper.
+ * @csspart title    - The title text element.
+ * @csspart subtitle - The subtitle text element (prominent size only).
+ * @csspart actions  - The actions slot wrapper (prominent size only).
  */
 let MoniAppBar = class MoniAppBar extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Determines whether the bar is placed at the top or bottom of the viewport.
+         *
+         * - `'top'` (default) — Sticky header at the top of the scroll container.
+         * - `'bottom'` — Fixed footer; primarily used for mobile bottom navigation patterns.
+         *
+         * @default 'top'
+         */
         this.placement = 'top';
+        /**
+         * Visual variant of the app bar.
+         *
+         * - `'standard'` (default) — Flat surface. No shadow at rest; gains shadow
+         *   programmatically via the `elevated` attribute when content scrolls beneath it.
+         * - `'floating'` — Permanently elevated with `--elevate2` box-shadow.
+         *
+         * @default 'standard'
+         */
         this.variant = 'standard';
+        /**
+         * Height variant of the app bar.
+         *
+         * - `'default'` — 64dp (4rem). Standard M3 top app bar height.
+         * - `'prominent'` — 152dp (9.5rem). Use when showing a subtitle or when
+         *   extra vertical space is needed for a contextual action row.
+         *
+         * @default 'default'
+         */
         this.size = 'default';
+        /**
+         * Title text displayed in the center of the app bar.
+         *
+         * The title is center-aligned per M3 spec. Long titles are truncated with
+         * an ellipsis. For semantic HTML, the consumer should also provide an `<h1>`
+         * in the page content that matches this title.
+         *
+         * @default ''
+         */
         this.title = '';
+        /**
+         * Optional subtitle displayed below the title.
+         *
+         * Only rendered when `size="prominent"`. Provides secondary context
+         * (e.g. folder name, item count, description).
+         *
+         * @default ''
+         */
         this.subtitle = '';
+        /**
+         * When present, applies `--elevate2` box-shadow to signal that content has
+         * scrolled beneath the bar.
+         *
+         * Consumers are responsible for toggling this attribute reactively based on
+         * the scroll position of the main content area:
+         * ```ts
+         * container.addEventListener('scroll', () => {
+         *   appBar.elevated = container.scrollTop > 0;
+         * });
+         * ```
+         *
+         * @default false
+         */
         this.elevated = false;
     }
     static { this.styles = [
@@ -157,6 +240,18 @@ let MoniAppBar = class MoniAppBar extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Renders the app bar grid layout.
+     *
+     * The inner `.bar` element uses a 3-column CSS grid:
+     * - Column 1: leading slot (navigation icon).
+     * - Column 2: title (center-aligned, fills remaining space).
+     * - Column 3: trailing slot (action icons).
+     *
+     * In `prominent` size, a subtitle row and an actions row are appended
+     * conditionally. The subtitle only renders when the `subtitle` attribute
+     * is non-empty; the actions slot always renders for prominent bars.
+     */
     render() {
         const hasSubtitle = this.size === 'prominent' && Boolean(this.subtitle);
         const hasActions = Boolean(this.size === 'prominent');