@moni-labs/moni-ui 0.2.0 → 0.3.1

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() {
@@ -44,6 +87,9 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
         this.showAllText = 'Show all';
         this.headerText = '';
         this.hideNav = false;
+        this.infinite = false;
+        this.autoplay = false;
+        this.autoplayInterval = 3000;
         this._containerWidth = 0;
         this._slottedItems = [];
         this._hasSlottedShowAll = false;
@@ -61,6 +107,9 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
         this._tickerTarget = 0;
         this._tickerCurrent = 0;
         this._isTicking = false;
+        // Infinite & Autoplay state
+        this._infiniteInitialized = false;
+        this._autoplayTimer = null;
         // quickSetter caches — avoid gsap.set() overhead per frame
         this._cardSetX = [];
         this._cardSetWidth = [];
@@ -79,6 +128,7 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
                 this._tickerCurrent = this._tickerTarget;
                 gsap.ticker.remove(this._tick);
                 this._isTicking = false;
+                this._checkInfiniteWrap();
             }
             this._applyLayout(this._tickerCurrent);
         };
@@ -98,6 +148,30 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
             if (this._cardSetX.length !== this._cards.length) {
                 this._buildQuickSetters();
             }
+            if (this.infinite && !this._infiniteInitialized && this.effectiveItems.length > 0) {
+                const C = this.effectiveItems.length;
+                const V = C * this._visualCardsMultiplier;
+                const K = this._snapSetsCount;
+                const centerSetIndex = Math.floor(K / 2);
+                // Wait for the browser to render the new items so scrollWidth is updated
+                // A double-rAF or setTimeout ensures the layout engine has processed the new snap-items
+                requestAnimationFrame(() => {
+                    setTimeout(() => {
+                        if (this._scrollContainer) {
+                            // Force layout calculation
+                            this._scrollContainer.scrollWidth;
+                            this._scrollContainer.scrollLeft = centerSetIndex * V * this.itemSize;
+                            // If the browser still clamped it, it means it's not ready. 
+                            // But with setTimeout it should be fully ready.
+                            // Force the visual ticker to match instantly to avoid an animation zoom from 0
+                            this._tickerTarget = this._scrollContainer.scrollLeft / this.itemSize;
+                            this._tickerCurrent = this._tickerTarget;
+                            this._applyLayout(this._tickerCurrent);
+                        }
+                    }, 20);
+                });
+                this._infiniteInitialized = true;
+            }
             this._tickerTarget = this._scrollContainer.scrollLeft / this.itemSize;
             if (instant || (!this._isTicking && this._tickerCurrent === 0)) {
                 this._tickerCurrent = this._tickerTarget;
@@ -391,6 +465,9 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
         }
         this._buildQuickSetters();
         this.updateLayout(true);
+        if (this.autoplay) {
+            this._startAutoplay();
+        }
     }
     updated(changedProperties) {
         super.updated(changedProperties);
@@ -402,15 +479,30 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
             changedProperties.has('padding') ||
             changedProperties.has('items') ||
             changedProperties.has('hideNav') ||
+            changedProperties.has('infinite') ||
+            changedProperties.has('autoplay') ||
+            changedProperties.has('autoplayInterval') ||
             changedProperties.has('_containerWidth') ||
             changedProperties.has('_slottedItems') ||
             changedProperties.has('_hasSlottedShowAll')) {
+            if (changedProperties.has('infinite') || changedProperties.has('items') || changedProperties.has('_slottedItems')) {
+                this._infiniteInitialized = false;
+            }
             if (changedProperties.has('layout') && this._scrollContainer) {
                 this._scrollContainer.scrollLeft = 0;
+                this._infiniteInitialized = false;
                 this._scrollContainer.style.scrollSnapType =
                     this.layout === 'uncontained' ? 'none' : 'x mandatory';
             }
             this.updateLayout(true);
+            if (changedProperties.has('autoplay') || changedProperties.has('autoplayInterval') || changedProperties.has('items') || changedProperties.has('_slottedItems')) {
+                if (this.autoplay) {
+                    this._startAutoplay();
+                }
+                else {
+                    this._stopAutoplay();
+                }
+            }
         }
     }
     get computedLayout() {
@@ -596,7 +688,21 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
         const isMobile = this._isMobile;
         const cardCount = this._cards.length;
         for (let i = 0; i < cardCount; i++) {
-            const p = i - t;
+            let p = i - t;
+            if (this.infinite) {
+                // Modulo wrap so the cards perfectly loop around the center
+                p = i - (t % cardCount);
+                if (p > cardCount / 2)
+                    p -= cardCount;
+                if (p < -cardCount / 2)
+                    p += cardCount;
+            }
+            // Optimization: if the card is far off-screen, hide it to save rendering work
+            if (p < -15 || p > 15) {
+                this._cardSetX[i](-9999);
+                this._titleSetOpacity[i](0);
+                continue;
+            }
             const layout = this._getCardLayout(p);
             // Use quickSetters — ~3x faster than gsap.set() per call
             this._cardSetX[i](layout.x);
@@ -609,8 +715,97 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
             this._titleSetOpacity[i](layout.opacity);
         }
     }
+    get _visualCardsMultiplier() {
+        if (!this.infinite || this.effectiveItems.length === 0)
+            return 1;
+        const C = this.effectiveItems.length;
+        // We need at least ~15 cards to fill the screen seamlessly for small datasets
+        return Math.max(1, Math.ceil(15 / C));
+    }
+    get _snapSetsCount() {
+        if (!this.infinite || this.effectiveItems.length === 0)
+            return 1;
+        const C = this.effectiveItems.length;
+        const V = C * this._visualCardsMultiplier;
+        // We want enough snap items so the user NEVER reaches the end in a single fast swipe.
+        // A total of ~1000 items is extremely cheap as empty divs, and provides a massive buffer.
+        let K = Math.ceil(1000 / V);
+        if (K % 2 === 0)
+            K += 1; // Keep it odd for a perfect center
+        return Math.max(3, K);
+    }
+    get _snapItemsCount() {
+        if (this.infinite) {
+            const C = this.effectiveItems.length;
+            const V_mult = this._visualCardsMultiplier;
+            const K = this._snapSetsCount;
+            return K * (C * V_mult);
+        }
+        return this.effectiveItems.length;
+    }
+    _checkInfiniteWrap() {
+        if (!this.infinite || this.effectiveItems.length === 0 || !this._scrollContainer)
+            return;
+        const C = this.effectiveItems.length;
+        const V = C * this._visualCardsMultiplier;
+        const K = this._snapSetsCount;
+        const centerSetIndex = Math.floor(K / 2);
+        // The scroll track is divided into K sets, each containing V items.
+        const setWidth = V * this.itemSize;
+        const currentScroll = this._scrollContainer.scrollLeft;
+        const currentSet = Math.floor(currentScroll / setWidth);
+        if (currentSet !== centerSetIndex) {
+            const delta = (centerSetIndex - currentSet) * setWidth;
+            const oldSnap = this._scrollContainer.style.scrollSnapType;
+            const oldBehavior = this._scrollContainer.style.scrollBehavior;
+            // Temporarily disable snap and smooth behavior so the wrap is instantaneous
+            this._scrollContainer.style.scrollSnapType = 'none';
+            this._scrollContainer.style.scrollBehavior = 'auto';
+            this._scrollContainer.scrollLeft += delta;
+            // INSTANTLY update the GSAP visual ticker so it doesn't animate the jump
+            this._tickerTarget = this._scrollContainer.scrollLeft / this.itemSize;
+            this._tickerCurrent = this._tickerTarget;
+            this._applyLayout(this._tickerCurrent);
+            // Restore original scroll behavior
+            this._scrollContainer.style.scrollBehavior = oldBehavior;
+            if (this._isDown) {
+                this._scrollLeftStart += delta;
+            }
+            if (oldSnap && oldSnap !== 'none') {
+                // Re-enable snap on the next frame to avoid jumping
+                requestAnimationFrame(() => {
+                    if (this._scrollContainer && !this._isDown) {
+                        this._scrollContainer.style.scrollSnapType = oldSnap;
+                    }
+                });
+            }
+        }
+    }
+    _startAutoplay() {
+        this._stopAutoplay();
+        if (this.autoplay && this.effectiveItems.length > 0) {
+            this._autoplayTimer = setInterval(() => {
+                // We removed _isInteracting to make autoplay more robust. It only pauses on active drag.
+                if (!this._isDown) {
+                    this._scrollNext();
+                }
+            }, this.autoplayInterval);
+        }
+    }
+    _stopAutoplay() {
+        if (this._autoplayTimer) {
+            clearInterval(this._autoplayTimer);
+            this._autoplayTimer = null;
+        }
+    }
+    _handleMouseEnter() {
+    }
+    _handleMouseLeave() {
+        this._handleMouseUp();
+    }
     _handleMouseDown(e) {
         gsap.killTweensOf(this._scrollContainer);
+        this._checkInfiniteWrap();
         this._isDown = true;
         this._draggedDistance = 0;
         this._scrollContainer.style.scrollBehavior = 'auto';
@@ -647,11 +842,20 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
         }
         // Dynamic momentum: stronger swipes have a much higher multiplier
         const momentumMultiplier = 350 + Math.abs(this._velocity) * 300;
-        const projectedScrollLeft = this._scrollContainer.scrollLeft - this._velocity * momentumMultiplier;
+        let projectedScrollLeft = this._scrollContainer.scrollLeft - this._velocity * momentumMultiplier;
+        // Cap momentum throw to prevent hitting infinite wrap edges on fast swipes
+        const maxThrowDist = 15 * this.itemSize;
+        if (projectedScrollLeft < this._scrollContainer.scrollLeft - maxThrowDist) {
+            projectedScrollLeft = this._scrollContainer.scrollLeft - maxThrowDist;
+        }
+        else if (projectedScrollLeft > this._scrollContainer.scrollLeft + maxThrowDist) {
+            projectedScrollLeft = this._scrollContainer.scrollLeft + maxThrowDist;
+        }
         if (this.layout !== 'uncontained') {
             this._scrollContainer.style.scrollSnapType = 'none';
             let targetIndex = Math.round(projectedScrollLeft / this.itemSize);
-            targetIndex = Math.max(0, Math.min(this.effectiveItems.length - 1, targetIndex));
+            const maxIndex = this.effectiveItems.length > 0 ? this._snapItemsCount - 1 : 0;
+            targetIndex = Math.max(0, Math.min(maxIndex, targetIndex));
             const snapPoint = targetIndex * this.itemSize;
             // Dynamic duration: longer distance = more time, max 0.85s for faster feeling
             const currentIndex = Math.round(this._scrollContainer.scrollLeft / this.itemSize);
@@ -672,6 +876,7 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
     }
     _handleTouchStart(e) {
         gsap.killTweensOf(this._scrollContainer);
+        this._checkInfiniteWrap();
         this._isDown = true;
         this._draggedDistance = 0;
         this._scrollContainer.style.scrollBehavior = 'auto';
@@ -727,7 +932,7 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
             if (this._wheelTimeout)
                 clearTimeout(this._wheelTimeout);
             this._wheelTimeout = setTimeout(() => {
-                if (this.layout !== 'uncontained') {
+                if (this.layout !== 'uncontained' && !this._isDown) {
                     this._scrollContainer.style.scrollSnapType = 'x mandatory';
                 }
             }, 150);
@@ -739,20 +944,20 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
             e.stopPropagation();
             return;
         }
+        const originalIndex = index % this.effectiveItems.length;
         this.dispatchEvent(new CustomEvent('item-click', {
-            detail: { item, index },
+            detail: { item, index: originalIndex },
             bubbles: true,
             composed: true
         }));
     }
     _scrollPrevious() {
-        const target = Math.max(0, this._scrollContainer.scrollLeft - this.itemSize);
+        const target = this._scrollContainer.scrollLeft - this.itemSize;
         this._scrollContainer.style.scrollBehavior = 'smooth';
         this._scrollContainer.scrollTo({ left: target, behavior: 'smooth' });
     }
     _scrollNext() {
-        const maxScroll = this._scrollContainer.scrollWidth - this._scrollContainer.clientWidth;
-        const target = Math.min(maxScroll, this._scrollContainer.scrollLeft + this.itemSize);
+        const target = this._scrollContainer.scrollLeft + this.itemSize;
         this._scrollContainer.style.scrollBehavior = 'smooth';
         this._scrollContainer.scrollTo({ left: target, behavior: 'smooth' });
     }
@@ -840,14 +1045,23 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
         if (rightPadding < minRightPaddingNeeded) {
             rightPadding = minRightPaddingNeeded;
         }
+        let snapItemsCount = hasItems ? this._snapItemsCount : 0;
+        let visualItems = this.effectiveItems;
+        if (this.infinite && hasItems) {
+            const V_mult = this._visualCardsMultiplier;
+            visualItems = [];
+            for (let i = 0; i < V_mult; i++) {
+                visualItems = visualItems.concat(this.effectiveItems);
+            }
+        }
         const trackWidth = hasItems
-            ? this.effectiveItems.length * L + (this.effectiveItems.length - 1) * this.gap
+            ? snapItemsCount * L + (snapItemsCount - 1) * this.gap
             : 0;
         const isScrollable = hasItems && this._scrollContainer &&
             (this._scrollContainer.scrollWidth > this._scrollContainer.clientWidth);
-        const showPrevArrow = isScrollable && this._scrollContainer.scrollLeft > 5;
-        const showNextArrow = isScrollable &&
-            (this._scrollContainer.scrollWidth - this._scrollContainer.scrollLeft - this._scrollContainer.clientWidth > 5);
+        const showPrevArrow = this.infinite || (isScrollable && this._scrollContainer.scrollLeft > 5);
+        const showNextArrow = this.infinite || (isScrollable &&
+            (this._scrollContainer.scrollWidth - this._scrollContainer.scrollLeft - this._scrollContainer.clientWidth > 5));
         return html `
 			<div class="carousel-container" style="
 				--carousel-snap-width: ${L}px;
@@ -894,34 +1108,35 @@ let MoniCarousel = class MoniCarousel extends MoniElement {
 						@mousedown=${this._handleMouseDown}
 						@mousemove=${this._handleMouseMove}
 						@mouseup=${this._handleMouseUp}
-						@mouseleave=${this._handleMouseUp}
+						@mouseenter=${this._handleMouseEnter}
+						@mouseleave=${this._handleMouseLeave}
 						@touchstart=${this._handleTouchStart}
 						@touchmove=${this._handleTouchMove}
 						@touchend=${this._handleTouchEnd}
 						@wheel=${this._handleWheel}
 					>
 						<div class="snap-track">
-							${hasItems ? this.effectiveItems.map(() => html `<div class="snap-item"></div>`) : ''}
+							${hasItems ? Array.from({ length: snapItemsCount }).map(() => html `<div class="snap-item"></div>`) : ''}
 						</div>
 						<div class="visual-track">
 							${hasItems
-            ? this.effectiveItems.map((item, idx) => html `
+            ? visualItems.map((item, idx) => html `
 											<div 
 												class="card" 
 												@click=${(e) => this._handleCardClick(e, item, idx)}
 											>
 												${item.href
                 ? html `
-															<a href="${item.href}" target="${item.target || '_self'}" style="text-decoration:none; color:inherit;">
+															<a href="${item.href}" target="${item.target || '_self'}" style="text-decoration:none; color:inherit;" draggable="false">
 																<div class="img-parallax-container">
-																	<img src="${item.img}" alt="${item.title}" draggable="false" />
+																	<img src="${item.img}" alt="${item.title}" draggable="false" loading="lazy" />
 																</div>
 																<h2 class="card-title">${item.title}</h2>
 															</a>
 														`
                 : html `
 															<div class="img-parallax-container">
-																<img src="${item.img}" alt="${item.title}" draggable="false" />
+																<img src="${item.img}" alt="${item.title}" draggable="false" loading="lazy" />
 															</div>
 															<h2 class="card-title">${item.title}</h2>
 														`}
@@ -986,6 +1201,15 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: 'hide-nav' })
 ], MoniCarousel.prototype, "hideNav", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], MoniCarousel.prototype, "infinite", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], MoniCarousel.prototype, "autoplay", void 0);
+__decorate([
+    property({ type: Number, attribute: 'autoplay-interval' })
+], MoniCarousel.prototype, "autoplayInterval", void 0);
 __decorate([
     state()
 ], MoniCarousel.prototype, "_containerWidth", void 0);

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"}