@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/moni-card.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-card.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,43 +14,97 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material 3 Card (`m3-docs/components/cards/specs.md`).
+ * Material Design 3 Card component.
+ *
+ * Cards display content and actions about a single subject. They are
+ * container surfaces that group related information together, making it
+ * easy for users to scan and interact with collections of related data.
+ *
+ * **M3 spec reference:** `m3-docs/components/cards/specs.md`
+ *
+ * **Variants:**
+ * - `elevated` (default) — `surface-container-low` background + `--elevate1` shadow.
+ *   Best for collections where the card needs visual separation from a
+ *   patterned or colored background. Gains shadow on hover/drag.
+ * - `filled` — `surface-container-highest` background, no shadow.
+ *   Lowest emphasis; use when cards sit directly on the main background surface.
+ * - `outlined` — `surface` background + 1dp `outline-variant` stroke.
+ *   Highest structural emphasis without casting a shadow. Best on solid backgrounds.
+ *
+ * **M3 measurements:**
+ * - Container corner radius: 12dp.
+ * - Horizontal content padding: 16dp.
+ * - Gap between cards in a collection: max 8dp.
+ * - Headline text alignment: start.
  *
- * Cards display content and actions on a single subject. Three variants:
- *  - **elevated**: surface-container-low background + elevation 1 shadow.
- *    Default for collections where the card needs separation from a
- *    patterned background.
- *  - **filled**: surface-container-highest background, no shadow.
- *    Lowest emphasis; use when cards sit directly on the background.
- *  - **outlined**: surface background + outline-variant 1dp stroke.
- *    Highest emphasis without shadow; good on solid color backgrounds.
+ * **Interactive cards:**
+ * When `clickable=true`, the card renders M3 state layer overlays on hover,
+ * focus, and press via the `::before` pseudo-element. The consumer must handle
+ * the `click` event to implement navigation or selection logic.
  *
- * M3 measurements:
- *  - Container corner radius: **12dp**.
- *  - Left/right padding: **16dp**.
- *  - Padding between cards in a collection: max **8dp**.
- *  - Headline text alignment: **start**.
+ * @example
+ * ```html
+ * <moni-card variant="outlined" clickable>
+ *   <img slot="media" src="photo.jpg" alt="Card image" />
+ *   <h3 slot="headline">Card Title</h3>
+ *   <p slot="supporting">Supporting text that describes the card topic.</p>
+ *   <div slot="actions">
+ *     <moni-button variant="text">Cancel</moni-button>
+ *     <moni-button>Confirm</moni-button>
+ *   </div>
+ * </moni-card>
+ * ```
  *
- * Slots:
- *  - media:        image or video at the top of the card.
- *  - default:      primary content (headline, subhead, supporting text).
- *  - headline:     shortcut for the H3-equivalent title (semantic).
- *  - subhead:      secondary title slot.
- *  - supporting:   supporting text slot.
- *  - actions:      action buttons row at the bottom of the card.
+ * @slot media      - An image, video, or icon at the top of the card.
+ * @slot default    - Primary body content (replaces all named slots if used).
+ * @slot headline   - H3-equivalent title text.
+ * @slot subhead    - Secondary title below the headline.
+ * @slot supporting - Descriptive supporting body text.
+ * @slot actions    - Action buttons row at the bottom of the card.
  *
- * Attributes:
- *  - variant: elevated (default) | filled | outlined
- *  - clickable: present → apply hover/focus/pressed state layers
- *  - draggable:  present → apply dragged state elevation (3)
- *  - disabled:   present → reduced opacity + cursor not-allowed
+ * @csspart card    - The outer card container.
+ * @csspart media   - The media area wrapper.
+ * @csspart content - The content wrapper.
+ * @csspart actions - The actions row wrapper.
  */
 let MoniCard = class MoniCard extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Visual variant of the card.
+         *
+         * - `'elevated'` (default) — Surface-low background + elevation shadow.
+         * - `'filled'` — Surface-highest background, no shadow.
+         * - `'outlined'` — Surface background + outline-variant stroke.
+         *
+         * @default 'elevated'
+         */
         this.variant = 'elevated';
+        /**
+         * When `true`, applies M3 state layer overlays (hover, focus, pressed)
+         * to communicate interactivity. The card background shifts slightly on hover.
+         *
+         * Use when the card itself is a clickable navigation or selection target.
+         *
+         * @default false
+         */
         this.clickable = false;
+        /**
+         * When `true`, applies `--elevate3` box-shadow to simulate the M3 "dragged"
+         * state as specified in the M3 card interaction spec.
+         *
+         * Consumers should toggle this attribute based on the drag state of the card
+         * (e.g. via a drag-and-drop library callback).
+         *
+         * @default false
+         */
         this.draggable = false;
+        /**
+         * When `true`, the card renders at 50% opacity with `cursor: not-allowed`,
+         * signaling that the card and its actions are unavailable.
+         *
+         * @default false
+         */
         this.disabled = false;
     }
     static { this.styles = [

package/dist/components/moni-carousel.d.ts

@@ -1,29 +1,79 @@
+/**
+ * @file components/moni-carousel.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
+/**
+ * Data model for a single item in a `<moni-carousel>`.
+ */
 export interface CarouselItem {
+    /** Display title overlaid on the item. */
     title: string;
+    /** URL or path to the background image. */
     img: string;
+    /** Optional link target. If provided, the item renders as an `<a>` element. */
     href?: string;
+    /** Link target attribute (e.g. `'_blank'`). Only applies if `href` is set. */
     target?: string;
 }
 /**
  * Material Design 3 Expressive Carousel component.
- * Supports three layouts:
- *  - `multi-browse`: Shows a collection of items (large, medium, and small items).
- *  - `hero`: Focuses on one large item with a smaller item peeking.
- *  - `uncontained`: Standard same-sized layout bleeding off the edges.
  *
- * Attributes:
- *  - layout: 'multi-browse' | 'hero' | 'uncontained'
- *  - auto: if true, dynamically calculates items sizes to fit the container without gaps.
- *  - large-width: width of large items (used in non-auto mode or as a guideline).
- *  - medium-width: width of medium items (multi-browse layout).
- *  - small-width: width of small/peeking items.
- *  - gap: spacing between elements (default 8px).
- *  - padding: leading/trailing padding (default 16px).
- *  - border-radius: radius of cards (default 28px).
- *  - header-text: header title of the carousel.
- *  - show-all: renders a "Show all" action button/link.
- *  - show-all-text: customize the text for the "Show all" action.
+ * Carousels display a collection of related items in a scrollable, horizontal list.
+ * They allow users to quickly browse through items like images, cards, or products.
+ *
+ * **M3 spec reference:** `m3-docs/components/carousel/specs.md`
+ *
+ * **Layout variants:**
+ * - `multi-browse` (default) — Shows a mix of large, medium, and small (peeking)
+ *   items. Best for exploring a large number of items.
+ * - `hero` — Focuses on one large primary item while showing a sliver of the
+ *   next item. Best for featuring important content.
+ * - `uncontained` — Standard layout where all items have the same width and
+ *   bleed off the edges of the container.
+ *
+ * **Animation & Gestures:**
+ * This component uses GSAP for smooth drag, flick, and snap animations,
+ * mirroring the high-fidelity M3 Expressive motion specs. It handles touch
+ * gestures for mobile and mouse-drag for desktop.
+ *
+ * **Auto-sizing (`auto` mode):**
+ * When `auto=true` (default), the carousel measures its own width and
+ * dynamically calculates the optimal sizes for large, medium, and small items
+ * based on the active `layout` to ensure they fit perfectly without awkward gaps
+ * or clipping at the edges.
+ *
+ * @example
+ * ```html
+ * <!-- Declarative usage via DOM properties (recommended) -->
+ * <moni-carousel layout="hero"></moni-carousel>
+ * <script>
+ *   const carousel = document.querySelector('moni-carousel');
+ *   carousel.items = [
+ *     { title: 'Item 1', img: '/img1.jpg', href: '/link1' },
+ *     { title: 'Item 2', img: '/img2.jpg' }
+ *   ];
+ * </script>
+ *
+ * <!-- Slot-based usage (for SSR or simple static content) -->
+ * <moni-carousel layout="uncontained">
+ *   <div slot="item">
+ *     <img src="/img1.jpg" />
+ *     <h3>Static Item</h3>
+ *   </div>
+ * </moni-carousel>
+ * ```
+ *
+ * @slot item - Alternative to the `items` property. Slot individual HTML elements
+ *              instead of passing data objects.
+ *
+ * @csspart carousel - The outer wrapper.
+ * @csspart track    - The scrolling track element.
+ * @csspart item     - Individual carousel item containers.
+ * @csspart img      - The image elements inside the items.
+ * @csspart title    - The title text elements inside the items.
  */
 export declare class MoniCarousel extends MoniElement {
     items: CarouselItem[];
@@ -101,7 +151,7 @@ export declare class MoniCarousel extends MoniElement {
     private _handleShowAllClick;
     private _handleShowAllSlotChange;
     private _handleSlotChange;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-carousel.d.ts","sourceRoot":"","sources":["../../src/components/moni-carousel.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,YAAa,SAAQ,WAAW;IACjB,KAAK,EAAE,YAAY,EAAE,CAAM;IACzB,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,aAAa,CAAkB;IAClD,IAAI,UAAQ;IACF,UAAU,SAAO;IAChB,WAAW,SAAM;IAClB,UAAU,SAAM;IAC1C,GAAG,SAAK;IACR,OAAO,SAAM;IACe,YAAY,SAAM;IACtB,OAAO,UAAS;IAC1B,WAAW,SAAc;IAC3B,UAAU,SAAM;IACJ,OAAO,UAAS;IAE3D,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,kBAAkB,CAAS;IAE5C,IAAI,cAAc,IAAI,YAAY,EAAE,CAEnC;IAE2B,OAAO,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,MAAM,CAA8B;IAE/D,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,gBAAgB,CAAmC;IAE3D,OAAgB,MAAM,4BAiOpB;IAEO,iBAAiB;IAwBjB,oBAAoB;IAoBpB,YAAY;IAaZ,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC;IAwBpD,IAAI,cAAc;;;;;MAwEjB;IAED,IAAI,QAAQ,WAEX;IAED,OAAO,CAAC,cAAc;IA+EtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAaX;IAEF,OAAO,CAAC,eAAe,CAOrB;IAEF,YAAY,GAAI,iBAAe,UAmB7B;IAEF,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,cAAc;IAwCtB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,iBAAiB;IA4ChB,MAAM;CAqIf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD"}
+{"version":3,"file":"moni-carousel.d.ts","sourceRoot":"","sources":["../../src/components/moni-carousel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,qBACa,YAAa,SAAQ,WAAW;IACjB,KAAK,EAAE,YAAY,EAAE,CAAM;IACzB,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,aAAa,CAAkB;IAClD,IAAI,UAAQ;IACF,UAAU,SAAO;IAChB,WAAW,SAAM;IAClB,UAAU,SAAM;IAC1C,GAAG,SAAK;IACR,OAAO,SAAM;IACe,YAAY,SAAM;IACtB,OAAO,UAAS;IAC1B,WAAW,SAAc;IAC3B,UAAU,SAAM;IACJ,OAAO,UAAS;IAE3D,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,kBAAkB,CAAS;IAE5C,IAAI,cAAc,IAAI,YAAY,EAAE,CAEnC;IAE2B,OAAO,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,MAAM,CAA8B;IAE/D,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,gBAAgB,CAAmC;IAE3D,OAAgB,MAAM,4BAiOpB;IAEO,iBAAiB;IAwBjB,oBAAoB;IAoBpB,YAAY;IAaZ,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC;IAwBpD,IAAI,cAAc;;;;;MAwEjB;IAED,IAAI,QAAQ,WAEX;IAED,OAAO,CAAC,cAAc;IA+EtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAaX;IAEF,OAAO,CAAC,eAAe,CAOrB;IAEF,YAAY,GAAI,iBAAe,UAmB7B;IAEF,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,cAAc;IAwCtB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,iBAAiB;IA4ChB,MAAM;CAqIf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD"}

package/dist/components/moni-carousel.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-carousel.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);
@@ -10,23 +16,60 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import { gsap } from 'gsap';
 /**
  * Material Design 3 Expressive Carousel component.
- * Supports three layouts:
- *  - `multi-browse`: Shows a collection of items (large, medium, and small items).
- *  - `hero`: Focuses on one large item with a smaller item peeking.
- *  - `uncontained`: Standard same-sized layout bleeding off the edges.
  *
- * Attributes:
- *  - layout: 'multi-browse' | 'hero' | 'uncontained'
- *  - auto: if true, dynamically calculates items sizes to fit the container without gaps.
- *  - large-width: width of large items (used in non-auto mode or as a guideline).
- *  - medium-width: width of medium items (multi-browse layout).
- *  - small-width: width of small/peeking items.
- *  - gap: spacing between elements (default 8px).
- *  - padding: leading/trailing padding (default 16px).
- *  - border-radius: radius of cards (default 28px).
- *  - header-text: header title of the carousel.
- *  - show-all: renders a "Show all" action button/link.
- *  - show-all-text: customize the text for the "Show all" action.
+ * Carousels display a collection of related items in a scrollable, horizontal list.
+ * They allow users to quickly browse through items like images, cards, or products.
+ *
+ * **M3 spec reference:** `m3-docs/components/carousel/specs.md`
+ *
+ * **Layout variants:**
+ * - `multi-browse` (default) — Shows a mix of large, medium, and small (peeking)
+ *   items. Best for exploring a large number of items.
+ * - `hero` — Focuses on one large primary item while showing a sliver of the
+ *   next item. Best for featuring important content.
+ * - `uncontained` — Standard layout where all items have the same width and
+ *   bleed off the edges of the container.
+ *
+ * **Animation & Gestures:**
+ * This component uses GSAP for smooth drag, flick, and snap animations,
+ * mirroring the high-fidelity M3 Expressive motion specs. It handles touch
+ * gestures for mobile and mouse-drag for desktop.
+ *
+ * **Auto-sizing (`auto` mode):**
+ * When `auto=true` (default), the carousel measures its own width and
+ * dynamically calculates the optimal sizes for large, medium, and small items
+ * based on the active `layout` to ensure they fit perfectly without awkward gaps
+ * or clipping at the edges.
+ *
+ * @example
+ * ```html
+ * <!-- Declarative usage via DOM properties (recommended) -->
+ * <moni-carousel layout="hero"></moni-carousel>
+ * <script>
+ *   const carousel = document.querySelector('moni-carousel');
+ *   carousel.items = [
+ *     { title: 'Item 1', img: '/img1.jpg', href: '/link1' },
+ *     { title: 'Item 2', img: '/img2.jpg' }
+ *   ];
+ * </script>
+ *
+ * <!-- Slot-based usage (for SSR or simple static content) -->
+ * <moni-carousel layout="uncontained">
+ *   <div slot="item">
+ *     <img src="/img1.jpg" />
+ *     <h3>Static Item</h3>
+ *   </div>
+ * </moni-carousel>
+ * ```
+ *
+ * @slot item - Alternative to the `items` property. Slot individual HTML elements
+ *              instead of passing data objects.
+ *
+ * @csspart carousel - The outer wrapper.
+ * @csspart track    - The scrolling track element.
+ * @csspart item     - Individual carousel item containers.
+ * @csspart img      - The image elements inside the items.
+ * @csspart title    - The title text elements inside the items.
  */
 let MoniCarousel = class MoniCarousel extends MoniElement {
     constructor() {

package/dist/components/moni-checkbox.d.ts

@@ -1,34 +1,139 @@
+/**
+ * @file components/moni-checkbox.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Checkbox that faithfully ports BeerCSS's `.checkbox` styles.
- *
- * BeerCSS architecture:
- *  - `.checkbox` is inline-flex, aligns items center
- *  - `input` has width/height = --_size, opacity: 0  (occupies real space, no absolute!)
- *  - `span::before` is the visible checkbox box (position: absolute, inset from the input)
- *  - `span::after` is the ripple hover effect
- *  - Content is set via CSS: "check_box_outline_blank" / "check_box" (Material Symbols font)
- *
- * Attributes:
- *  - label:    text label
- *  - checked:  present → input is checked
- *  - disabled: present → input is disabled
- *  - size:     small | medium (default) | large | extra
- *  - name:     forwarded to input.name
- *  - value:    forwarded to input.value
+ * Material Design 3 Checkbox component.
+ *
+ * Checkboxes allow users to select one or more items from a set, or toggle
+ * a single binary option. They are visual-only shells — the consumer is
+ * responsible for wiring up form submission and validation logic.
+ *
+ * **Visual architecture (BeerCSS pattern):**
+ * The native `<input type="checkbox">` occupies real layout space (16×16 minimum)
+ * but is visually hidden via `opacity: 0`. A `<span>` sibling rendered after
+ * the input holds two pseudo-elements:
+ * - `::before` — the visible checkbox icon (Material Symbols ligature).
+ * - `::after`  — the hover/focus state layer ripple ring.
+ *
+ * The `::before` content switches between:
+ * - `'check_box_outline_blank'` (unchecked)
+ * - `'check_box'` (checked)
+ * - `'indeterminate_check_box'` (native indeterminate state)
+ *
+ * **Form integration:**
+ * Setting `name` and `value` passes them to the native `<input>` element,
+ * enabling participation in HTML form submissions.
+ *
+ * @fires change - Bubbles and is composed. Fired when the checkbox is toggled.
+ *                 The consumer can read `element.checked` for the new state.
+ *
+ * @example
+ * ```html
+ * <moni-checkbox label="Accept terms" name="terms" value="yes"></moni-checkbox>
+ *
+ * <script>
+ *   document.querySelector('moni-checkbox').addEventListener('change', (e) => {
+ *     console.log('checked:', e.target.checked);
+ *   });
+ * </script>
+ * ```
+ *
+ * @csspart checkbox - The outer `<label>` element.
  */
 export declare class MoniCheckbox extends MoniElement {
+    /**
+     * Text label displayed to the right of the checkbox icon.
+     *
+     * When non-empty, the label is rendered as a text node inside the `<span>`.
+     * When empty, the default slot is rendered instead, allowing slotted HTML.
+     *
+     * @default ''
+     */
     label: string;
+    /**
+     * Whether the checkbox is currently checked.
+     *
+     * Reflected as an attribute so CSS attribute selectors and external state
+     * readers can observe the checked state without accessing the JS property.
+     * Synced to the native input via `updated()`.
+     *
+     * @default false
+     */
     checked: boolean;
+    /**
+     * When `true`, the native input is disabled: the checkbox is not interactive
+     * and renders at 50% opacity.
+     *
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * Visual size of the checkbox icon.
+     *
+     * Maps to the `--_size` custom property which controls both the invisible
+     * input's hit area and the visible `::before` icon size.
+     *
+     * | Value      | `--_size` |
+     * |------------|-----------|
+     * | `'small'`  | 1rem      |
+     * | `'medium'` | 1.5rem    |
+     * | `'large'`  | 2rem      |
+     * | `'extra'`  | 2.5rem    |
+     *
+     * @default 'medium'
+     */
     size: 'small' | 'medium' | 'large' | 'extra';
+    /**
+     * Forwarded to the native `<input name>` attribute.
+     * Required for grouping checkboxes within a form.
+     *
+     * @default ''
+     */
     name: string;
+    /**
+     * Forwarded to the native `<input value>` attribute.
+     * The value submitted in a form when this checkbox is checked.
+     *
+     * @default ''
+     */
     value: string;
+    /** Direct reference to the native input element for programmatic access. */
     private _input;
+    /**
+     * Syncs `checked` and `disabled` back to the native input element after
+     * Lit's render cycle, ensuring the DOM stays in sync with component state.
+     *
+     * This is necessary because Lit's `.property=${value}` binding updates the
+     * DOM property, but the `live()` directive and direct property assignment
+     * are more reliable for boolean inputs across browser implementations.
+     *
+     * @param changed - Map of changed property names to their previous values.
+     */
     updated(changed: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
+    /**
+     * Handles the native input's `change` event.
+     *
+     * Reads the new checked state from the input and re-dispatches a composed
+     * `'change'` event so the signal crosses shadow DOM boundaries and can be
+     * heard by parent elements in the light DOM.
+     *
+     * @param e - The native `change` event from the hidden `<input>`.
+     */
     private _onChange;
-    render(): import("lit-html").TemplateResult<1>;
+    /**
+     * Renders the accessible checkbox label structure.
+     *
+     * The `<label>` wraps the hidden `<input>` and a `<span>` so that clicking
+     * anywhere on the label area (including the text) toggles the checkbox.
+     * The `has-label` class on the span adds left padding to separate the icon
+     * from the label text.
+     */
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-checkbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-checkbox.d.ts","sourceRoot":"","sources":["../../src/components/moni-checkbox.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,YAAa,SAAQ,WAAW;IACf,KAAK,SAAM;IACI,OAAO,UAAS;IAChB,QAAQ,UAAS;IAE7D,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAC3B,IAAI,SAAM;IACV,KAAK,SAAM;IAExB,OAAO,CAAC,MAAM,CAAoB;IAEzC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BAoHpB;IAEF,OAAO,CAAC,SAAS;IAKR,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"moni-checkbox.d.ts","sourceRoot":"","sources":["../../src/components/moni-checkbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBACa,YAAa,SAAQ,WAAW;IAC5C;;;;;;;OAOG;IAC0B,KAAK,SAAM;IAExC;;;;;;;;OAQG;IACyC,OAAO,UAAS;IAE5D;;;;;OAKG;IACyC,QAAQ,UAAS;IAE7D;;;;;;;;;;;;;;OAcG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD;;;;;OAKG;IAC0B,IAAI,SAAM;IAEvC;;;;;OAKG;IAC0B,KAAK,SAAM;IAExC,4EAA4E;IAC5D,OAAO,CAAC,MAAM,CAAoB;IAElD;;;;;;;;;OASG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BAoHpB;IAEF;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;;OAOG;IACM,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}