@moni-labs/moni-ui 0.2.0 → 0.3.1

package/src/components/moni-carousel.ts

@@ -1,34 +1,85 @@
+/**
+ * @file components/moni-carousel.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, query, state, queryAll } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import { gsap } from 'gsap';
 
+/**
+ * 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.
  */
 @customElement('moni-carousel')
 export class MoniCarousel extends MoniElement {
@@ -45,6 +96,9 @@ export class MoniCarousel extends MoniElement {
 	@property({ attribute: 'show-all-text' }) showAllText = 'Show all';
 	@property({ attribute: 'header-text' }) headerText = '';
 	@property({ type: Boolean, attribute: 'hide-nav' }) hideNav = false;
+	@property({ type: Boolean, reflect: true }) infinite = false;
+	@property({ type: Boolean, reflect: true }) autoplay = false;
+	@property({ type: Number, attribute: 'autoplay-interval' }) autoplayInterval = 3000;
 
 	@state() private _containerWidth = 0;
 	@state() private _slottedItems: CarouselItem[] = [];
@@ -73,6 +127,10 @@ export class MoniCarousel extends MoniElement {
 	private _tickerCurrent = 0;
 	private _isTicking = false;
 
+	// Infinite & Autoplay state
+	private _infiniteInitialized = false;
+	private _autoplayTimer: any = null;
+
 	// quickSetter caches — avoid gsap.set() overhead per frame
 	private _cardSetX: ((value: number) => void)[] = [];
 	private _cardSetWidth: ((value: number) => void)[] = [];
@@ -361,6 +419,10 @@ export class MoniCarousel extends MoniElement {
 		}
 		this._buildQuickSetters();
 		this.updateLayout(true);
+		
+		if (this.autoplay) {
+			this._startAutoplay();
+		}
 	}
 
 	override updated(changedProperties: Map<string, any>) {
@@ -374,16 +436,32 @@ export 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();
+				}
+			}
 		}
 	}
 
@@ -586,6 +664,7 @@ export class MoniCarousel extends MoniElement {
 			this._tickerCurrent = this._tickerTarget;
 			gsap.ticker.remove(this._tick);
 			this._isTicking = false;
+			this._checkInfiniteWrap();
 		}
 
 		this._applyLayout(this._tickerCurrent);
@@ -608,6 +687,34 @@ export class MoniCarousel extends MoniElement {
 			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)) {
@@ -625,7 +732,21 @@ export 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
@@ -642,8 +763,112 @@ export class MoniCarousel extends MoniElement {
 		}
 	}
 
+	private 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));
+	}
+
+	private 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);
+	}
+
+	private 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;
+	}
+
+	private _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;
+					}
+				});
+			}
+		}
+	}
+
+	private _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) as unknown as number;
+		}
+	}
+
+	private _stopAutoplay() {
+		if (this._autoplayTimer) {
+			clearInterval(this._autoplayTimer);
+			this._autoplayTimer = null;
+		}
+	}
+
+	private _handleMouseEnter() {
+	}
+ 
+	private _handleMouseLeave() {
+		this._handleMouseUp();
+	}
+
 	private _handleMouseDown(e: MouseEvent) {
 		gsap.killTweensOf(this._scrollContainer);
+		this._checkInfiniteWrap();
 		this._isDown = true;
 		this._draggedDistance = 0;
 		this._scrollContainer.style.scrollBehavior = 'auto';
@@ -685,13 +910,22 @@ export 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
@@ -716,6 +950,7 @@ export class MoniCarousel extends MoniElement {
 
 	private _handleTouchStart(e: TouchEvent) {
 		gsap.killTweensOf(this._scrollContainer);
+		this._checkInfiniteWrap();
 		this._isDown = true;
 		this._draggedDistance = 0;
 		this._scrollContainer.style.scrollBehavior = 'auto';
@@ -780,7 +1015,7 @@ export class MoniCarousel extends MoniElement {
 			// Restablecer el snap después de un pequeño retraso
 			if ((this as any)._wheelTimeout) clearTimeout((this as any)._wheelTimeout);
 			(this as any)._wheelTimeout = setTimeout(() => {
-				if (this.layout !== 'uncontained') {
+				if (this.layout !== 'uncontained' && !this._isDown) {
 					this._scrollContainer.style.scrollSnapType = 'x mandatory';
 				}
 			}, 150);
@@ -794,9 +1029,10 @@ export class MoniCarousel extends MoniElement {
 			return;
 		}
 
+		const originalIndex = index % this.effectiveItems.length;
 		this.dispatchEvent(
 			new CustomEvent('item-click', {
-				detail: { item, index },
+				detail: { item, index: originalIndex },
 				bubbles: true,
 				composed: true
 			})
@@ -804,14 +1040,13 @@ export class MoniCarousel extends MoniElement {
 	}
 
 	private _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' });
 	}
 
 	private _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' });
 	}
@@ -908,15 +1143,27 @@ export class MoniCarousel extends MoniElement {
 			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="
@@ -964,18 +1211,19 @@ export 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(
+								? visualItems.map(
 										(item, idx) => html`
 											<div 
 												class="card" 
@@ -983,16 +1231,16 @@ export class MoniCarousel extends MoniElement {
 											>
 												${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>
 														`}

package/src/components/moni-checkbox.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-checkbox.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -5,35 +12,122 @@ import { live } from 'lit/directives/live.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Checkbox that faithfully ports BeerCSS's `.checkbox` styles.
+ * 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.
  *
- * 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)
+ * @fires change - Bubbles and is composed. Fired when the checkbox is toggled.
+ *                 The consumer can read `element.checked` for the new state.
  *
- * 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
+ * @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.
  */
 @customElement('moni-checkbox')
 export 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 ''
+	 */
 	@property({ reflect: true }) label = '';
+
+	/**
+	 * 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
+	 */
 	@property({ type: Boolean, reflect: true }) checked = false;
+
+	/**
+	 * When `true`, the native input is disabled: the checkbox is not interactive
+	 * and renders at 50% opacity.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * 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'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' | 'extra' = 'medium';
+
+	/**
+	 * Forwarded to the native `<input name>` attribute.
+	 * Required for grouping checkboxes within a form.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * Forwarded to the native `<input value>` attribute.
+	 * The value submitted in a form when this checkbox is checked.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) value = '';
 
+	/** Direct reference to the native input element for programmatic access. */
 	@query('input') private _input!: HTMLInputElement;
 
+	/**
+	 * 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.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (this._input) {
 			if (changed.has('checked')) this._input.checked = this.checked;
@@ -159,11 +253,28 @@ export class MoniCheckbox extends MoniElement {
 		`
 	];
 
+	/**
+	 * 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(e: Event) {
 		this.checked = (e.target as HTMLInputElement).checked;
 		this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
 	}
 
+	/**
+	 * 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.
+	 */
 	override render() {
 		return html`<label part="checkbox">
 			<input