@moni-labs/moni-ui 0.2.0 → 0.3.0

package/src/components/moni-typography.ts

@@ -1,31 +1,57 @@
+/**
+ * @file components/moni-typography.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { css, nothing } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { unsafeStatic, html as staticHtml } from 'lit/static-html.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material 3 Typography (`m3-docs/components/`).
+ * Material Design 3 Typography component.
+ *
+ * A specialized text component that enforces the M3 type scale. It ensures
+ * typography is consistent, accessible, and correctly styled across the
+ * application without requiring manual CSS classes.
+ *
+ * **M3 spec reference:** `m3-docs/components/typography/specs.md`
+ *
+ * **Type Scale Categories:**
+ * - `display`: The largest text on the screen, reserved for short, important
+ *   text or numerals. Works best on large screens. (Renders `<h1>` by default).
+ * - `headline`: High-emphasis text for primary page/section headers.
+ *   (Renders `<h2>` by default).
+ * - `title`: Medium-emphasis text used for dialog headers or smaller section
+ *   titles. (Renders `<h3>` by default).
+ * - `body`: Standard paragraph text used for long-form content.
+ *   (Renders `<p>` by default).
+ * - `label`: Small, utilitarian text used for buttons, captions, and form
+ *   elements. (Renders `<label>` by default).
+ *
+ * Each category supports three sizes: `large`, `medium`, and `small`.
  *
- * Renders a single piece of text using the M3 type scale. The component
- * chooses both the semantic tag and the typography class based on the
- * `variant` attribute. Consumers can override the tag via `as`.
+ * **Semantic Tags:**
+ * The component automatically selects an appropriate HTML semantic tag based on
+ * the variant. You can explicitly override this by setting the `as` attribute
+ * (e.g., to render a `headline` style but using a `<span>` tag for SEO or
+ * structural reasons).
  *
- * M3 type scale (5 categories, 3 sizes each):
- *  - **display**: largest text, used for marketing or hero content.
- *  - **headline**: page-level headings (H1 equivalent).
- *  - **title**:    section headings, dialog titles.
- *  - **body**:     paragraph text.
- *  - **label**:    button text, captions.
+ * @example
+ * ```html
+ * <!-- Renders an <h1> with display-large styles -->
+ * <moni-typography variant="display" size="large">Hero Text</moni-typography>
  *
- * Each category has `large`, `medium`, and `small` sizes (per M3 spec).
+ * <!-- Renders a <p> with body-medium styles -->
+ * <moni-typography variant="body">Standard paragraph text.</moni-typography>
  *
- * Attributes:
- *  - variant: display | headline | title | body | label (default body)
- *  - size:    large | medium | small (default medium)
- *  - as:      override the rendered tag (e.g. "span", "p", "label")
+ * <!-- Overriding the semantic tag -->
+ * <moni-typography variant="title" as="span">Inline title</moni-typography>
+ * ```
  *
- * Slots:
- *  - default: text content (falls back to `text` attribute if empty)
+ * @slot default - The text content to display.
  */
 @customElement('moni-typography')
 export class MoniTypography extends MoniElement {

package/src/index.ts

@@ -1,7 +1,56 @@
+/**
+ * @file index.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
+/**
+ * @module @moni-labs/moni-ui
+ *
+ * Main entry point for the Moni UI component library.
+ *
+ * **What this file does:**
+ * 1. **Side-effect import** — `import './components/index.js'` triggers the
+ *    auto-registration of every `<moni-*>` custom element with the browser's
+ *    Custom Element registry. This must happen before any component is rendered
+ *    in the DOM.
+ * 2. **Re-exports** — All component classes, utilities, and TypeScript types
+ *    are re-exported so consumers get a single import path:
+ *
+ * ```ts
+ * import {
+ *   MoniButton,
+ *   getThemeEngine,
+ *   generateScheme,
+ *   type ColorScheme
+ * } from '@moni-labs/moni-ui';
+ * ```
+ *
+ * **Import strategies:**
+ * - **Full bundle** (this file): imports and registers ALL components at once.
+ *   Best for SPAs that use many components.
+ * - **Tree-shaken per-component**: import individual files from
+ *   `@moni-labs/moni-ui/components/moni-button.js` etc. to let bundlers
+ *   include only what is used. Better for apps that use a small subset.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry Custom Element Registry}
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
 // Auto-register all Moni UI Web Components
+// ─────────────────────────────────────────────────────────────────────────────
+// This import has side effects: it calls customElements.define() for every
+// <moni-*> element. Bundlers must NOT tree-shake this import.
 import './components/index.js';
 
-// Web Components (visual-only)
+// ─────────────────────────────────────────────────────────────────────────────
+// Web Component class exports
+// ─────────────────────────────────────────────────────────────────────────────
+// Exporting the class enables TypeScript consumers to:
+//  - Subclass components for customization.
+//  - Use the class in type narrowing (instanceof MoniButton).
+//  - Access static members and properties programmatically.
 export {
 	MoniBadge,
 	MoniBottomSheet,
@@ -45,8 +94,17 @@ export {
 	MoniShape,
 } from './components/index.js';
 
-// Utils
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility exports
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Theme engine singleton factory.
+ * @see {@link getThemeEngine} for full documentation.
+ */
 export { getThemeEngine, resetThemeEngine } from './utils/theme.svelte.js';
+
+/** TypeScript types for theme engine configuration. */
 export type {
 	ThemeSettings,
 	ThemeMode,
@@ -54,6 +112,11 @@ export type {
 	ThemeRadius,
 	ThemeFont
 } from './utils/theme.svelte.js';
+
+/**
+ * Color generation and application utilities.
+ * @see utils/color.ts for full documentation.
+ */
 export {
 	generateScheme,
 	applySchemeToDocument,
@@ -61,5 +124,6 @@ export {
 	hexToHsl,
 	hslToHex
 } from './utils/color.js';
-export type { ColorScheme, ContrastLevel } from './utils/color.js';
 
+/** TypeScript types for the color system. */
+export type { ColorScheme, ContrastLevel } from './utils/color.js';

package/src/styles/tailwind.css

@@ -0,0 +1,67 @@
+/**
+ * @file styles/tailwind.css
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
+@import 'tailwindcss';
+
+@theme {
+	/* ─── Material Design 3 Expressive tokens integration ─── */
+	--color-primary: var(--moni-primary);
+	--color-on-primary: var(--moni-on-primary);
+	--color-primary-container: var(--moni-primary-container);
+	--color-on-primary-container: var(--moni-on-primary-container);
+
+	--color-secondary: var(--moni-secondary);
+	--color-on-secondary: var(--moni-on-secondary);
+	--color-secondary-container: var(--moni-secondary-container);
+	--color-on-secondary-container: var(--moni-on-secondary-container);
+
+	--color-tertiary: var(--moni-tertiary);
+	--color-on-tertiary: var(--moni-on-tertiary);
+	--color-tertiary-container: var(--moni-tertiary-container);
+	--color-on-tertiary-container: var(--moni-on-tertiary-container);
+
+	--color-error: var(--moni-error);
+	--color-on-error: var(--moni-on-error);
+	--color-error-container: var(--moni-error-container);
+	--color-on-error-container: var(--moni-on-error-container);
+
+	--color-background: var(--moni-background);
+	--color-on-background: var(--moni-on-background);
+	--color-surface: var(--moni-surface);
+	--color-on-surface: var(--moni-on-surface);
+	--color-surface-variant: var(--moni-surface-variant);
+	--color-on-surface-variant: var(--moni-on-surface-variant);
+
+	--color-outline: var(--moni-outline);
+	--color-outline-variant: var(--moni-outline-variant);
+
+	--color-surface-container-lowest: var(--moni-surface-container-lowest);
+	--color-surface-container-low: var(--moni-surface-container-low);
+	--color-surface-container: var(--moni-surface-container);
+	--color-surface-container-high: var(--moni-surface-container-high);
+	--color-surface-container-highest: var(--moni-surface-container-highest);
+
+	--color-inverse-surface: var(--moni-inverse-surface);
+	--color-inverse-on-surface: var(--moni-inverse-on-surface);
+	--color-inverse-primary: var(--moni-inverse-primary);
+
+	/* ─── Typography ─── */
+	--font-sans: var(--moni-font-sans, 'Geist', system-ui, -apple-system, sans-serif);
+	--font-serif: var(--moni-font-title, 'Instrument Serif', Georgia, serif);
+	--font-mono: 'Geist Mono', 'Fira Code', monospace;
+	--font-brand: var(--moni-font-sans, 'Geist', system-ui, sans-serif);
+	--font-title: var(--moni-font-title, 'Instrument Serif', Georgia, serif);
+	--font-icon: var(--moni-font-icon, 'Material Symbols Rounded');
+
+	/* ─── Radius scale ─── */
+	--radius-base: var(--moni-radius-base, 12px);
+	--radius-sm: calc(var(--moni-radius-base, 12px) * 0.5);
+	--radius-md: var(--moni-radius-base, 12px);
+	--radius-lg: calc(var(--moni-radius-base, 12px) * 1.5);
+	--radius-xl: calc(var(--moni-radius-base, 12px) * 2);
+	--radius-full: 9999px;
+}

package/src/styles/tokens.css

@@ -1,46 +1,51 @@
-@import 'tailwindcss';
-
-@theme {
-	/* ─── Material Design 3 Expressive tokens ─── */
-	--color-primary: var(--md-sys-color-primary);
-	--color-on-primary: var(--md-sys-color-on-primary);
-	--color-primary-container: var(--md-sys-color-primary-container);
-	--color-on-primary-container: var(--md-sys-color-on-primary-container);
-
-	--color-secondary: var(--md-sys-color-secondary);
-	--color-on-secondary: var(--md-sys-color-on-secondary);
-	--color-secondary-container: var(--md-sys-color-secondary-container);
-	--color-on-secondary-container: var(--md-sys-color-on-secondary-container);
-
-	--color-tertiary: var(--md-sys-color-tertiary);
-	--color-on-tertiary: var(--md-sys-color-on-tertiary);
-	--color-tertiary-container: var(--md-sys-color-tertiary-container);
-	--color-on-tertiary-container: var(--md-sys-color-on-tertiary-container);
-
-	--color-error: var(--md-sys-color-error);
-	--color-on-error: var(--md-sys-color-on-error);
-	--color-error-container: var(--md-sys-color-error-container);
-	--color-on-error-container: var(--md-sys-color-on-error-container);
-
-	--color-background: var(--md-sys-color-background);
-	--color-on-background: var(--md-sys-color-on-background);
-	--color-surface: var(--md-sys-color-surface);
-	--color-on-surface: var(--md-sys-color-on-surface);
-	--color-surface-variant: var(--md-sys-color-surface-variant);
-	--color-on-surface-variant: var(--md-sys-color-on-surface-variant);
-
-	--color-outline: var(--md-sys-color-outline);
-	--color-outline-variant: var(--md-sys-color-outline-variant);
-
-	--color-surface-container-lowest: var(--md-sys-color-surface-container-lowest);
-	--color-surface-container-low: var(--md-sys-color-surface-container-low);
-	--color-surface-container: var(--md-sys-color-surface-container);
-	--color-surface-container-high: var(--md-sys-color-surface-container-high);
-	--color-surface-container-highest: var(--md-sys-color-surface-container-highest);
-
-	--color-inverse-surface: var(--md-sys-color-inverse-surface);
-	--color-inverse-on-surface: var(--md-sys-color-inverse-on-surface);
-	--color-inverse-primary: var(--md-sys-color-inverse-primary);
+/**
+ * @file styles/tokens.css
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
+:root {
+	/* ─── Moni Design System core prefixed tokens ─── */
+	--moni-primary: var(--md-sys-color-primary, #6750a4);
+	--moni-on-primary: var(--md-sys-color-on-primary, #ffffff);
+	--moni-primary-container: var(--md-sys-color-primary-container, #eaddff);
+	--moni-on-primary-container: var(--md-sys-color-on-primary-container, #21005d);
+
+	--moni-secondary: var(--md-sys-color-secondary, #625b71);
+	--moni-on-secondary: var(--md-sys-color-on-secondary, #ffffff);
+	--moni-secondary-container: var(--md-sys-color-secondary-container, #e8def8);
+	--moni-on-secondary-container: var(--md-sys-color-on-secondary-container, #1d192b);
+
+	--moni-tertiary: var(--md-sys-color-tertiary, #7d5260);
+	--moni-on-tertiary: var(--md-sys-color-on-tertiary, #ffffff);
+	--moni-tertiary-container: var(--md-sys-color-tertiary-container, #ffd8e4);
+	--moni-on-tertiary-container: var(--md-sys-color-on-tertiary-container, #31111d);
+
+	--moni-error: var(--md-sys-color-error, #b3261e);
+	--moni-on-error: var(--md-sys-color-on-error, #ffffff);
+	--moni-error-container: var(--md-sys-color-error-container, #f9dedc);
+	--moni-on-error-container: var(--md-sys-color-on-error-container, #410e0b);
+
+	--moni-background: var(--md-sys-color-background, #fef7ff);
+	--moni-on-background: var(--md-sys-color-on-background, #1d1b20);
+	--moni-surface: var(--md-sys-color-surface, #fef7ff);
+	--moni-on-surface: var(--md-sys-color-on-surface, #1d1b20);
+	--moni-surface-variant: var(--md-sys-color-surface-variant, #e7e0ec);
+	--moni-on-surface-variant: var(--md-sys-color-on-surface-variant, #49454f);
+
+	--moni-outline: var(--md-sys-color-outline, #79747e);
+	--moni-outline-variant: var(--md-sys-color-outline-variant, #cac4d0);
+
+	--moni-surface-container-lowest: var(--md-sys-color-surface-container-lowest, #ffffff);
+	--moni-surface-container-low: var(--md-sys-color-surface-container-low, #f7f2fa);
+	--moni-surface-container: var(--md-sys-color-surface-container, #f3edf7);
+	--moni-surface-container-high: var(--md-sys-color-surface-container-high, #ece6f0);
+	--moni-surface-container-highest: var(--md-sys-color-surface-container-highest, #e6e1e5);
+
+	--moni-inverse-surface: var(--md-sys-color-inverse-surface, #313033);
+	--moni-inverse-on-surface: var(--md-sys-color-inverse-on-surface, #f4f0f4);
+	--moni-inverse-primary: var(--md-sys-color-inverse-primary, #d0bcff);
 
 	/* ─── Semantic Moni tokens ─── */
 	--color-success: #16a34a;
@@ -126,65 +131,72 @@
 	--moni-grain-opacity: var(--moni-grain-opacity, 0.03);
 
 	/* ─── Legacy Moni tokens (fallback durante la migración) ─── */
-	--color-brand-bg: var(--md-sys-color-background);
-	--color-brand-surface: var(--md-sys-color-surface);
-	--color-brand-primary: var(--md-sys-color-on-surface);
-	--color-brand-muted: var(--md-sys-color-on-surface-variant);
-	--color-brand-border: var(--md-sys-color-outline-variant);
-	--color-brand-accent: var(--md-sys-color-primary);
-
-	--color-admin-bg: var(--md-sys-color-background);
-	--color-admin-surface: var(--md-sys-color-surface);
-	--color-admin-sidebar: var(--md-sys-color-inverse-surface);
-	--color-admin-sidebar-fg: var(--md-sys-color-inverse-on-surface);
-	--color-admin-sidebar-muted: var(--md-sys-color-inverse-on-surface);
-	--color-admin-accent: var(--md-sys-color-primary);
-	--color-admin-accent-soft: var(--md-sys-color-primary-container);
-	--color-admin-text: var(--md-sys-color-on-surface);
+	--color-brand-bg: var(--moni-background);
+	--color-brand-surface: var(--moni-surface);
+	--color-brand-primary: var(--moni-on-surface);
+	--color-brand-muted: var(--moni-on-surface-variant);
+	--color-brand-border: var(--moni-outline-variant);
+	--color-brand-accent: var(--moni-primary);
+
+	--color-admin-bg: var(--moni-background);
+	--color-admin-surface: var(--moni-surface);
+	--color-admin-sidebar: var(--moni-inverse-surface);
+	--color-admin-sidebar-fg: var(--moni-inverse-on-surface);
+	--color-admin-sidebar-muted: var(--moni-inverse-on-surface);
+	--color-admin-accent: var(--moni-primary);
+	--color-admin-accent-soft: var(--moni-primary-container);
+	--color-admin-text: var(--moni-on-surface);
 	--color-admin-success: var(--color-success);
 	--color-admin-warn: var(--color-warning);
 	--color-admin-danger: var(--color-danger);
 	--color-admin-info: var(--color-info);
-}
 
-:root {
-	--primary: var(--md-sys-color-primary);
-	--on-primary: var(--md-sys-color-on-primary);
-	--primary-container: var(--md-sys-color-primary-container);
-	--on-primary-container: var(--md-sys-color-on-primary-container);
-
-	--secondary: var(--md-sys-color-secondary);
-	--on-secondary: var(--md-sys-color-on-secondary);
-	--secondary-container: var(--md-sys-color-secondary-container);
-	--on-secondary-container: var(--md-sys-color-on-secondary-container);
-
-	--tertiary: var(--md-sys-color-tertiary);
-	--on-tertiary: var(--md-sys-color-on-tertiary);
-	--tertiary-container: var(--md-sys-color-tertiary-container);
-	--on-tertiary-container: var(--md-sys-color-on-tertiary-container);
-
-	--error: var(--md-sys-color-error);
-	--on-error: var(--md-sys-color-on-error);
-	--error-container: var(--md-sys-color-error-container);
-	--on-error-container: var(--md-sys-color-on-error-container);
-
-	--background: var(--md-sys-color-background);
-	--on-background: var(--md-sys-color-on-background);
-	--surface: var(--md-sys-color-surface);
-	--on-surface: var(--md-sys-color-on-surface);
-	--surface-variant: var(--md-sys-color-surface-variant);
-	--on-surface-variant: var(--md-sys-color-on-surface-variant);
-
-	--outline: var(--md-sys-color-outline);
-	--outline-variant: var(--md-sys-color-outline-variant);
-
-	--surface-container-lowest: var(--md-sys-color-surface-container-lowest);
-	--surface-container-low: var(--md-sys-color-surface-container-low);
-	--surface-container: var(--md-sys-color-surface-container);
-	--surface-container-high: var(--md-sys-color-surface-container-high);
-	--surface-container-highest: var(--md-sys-color-surface-container-highest);
-
-	--inverse-surface: var(--md-sys-color-inverse-surface);
-	--inverse-on-surface: var(--md-sys-color-inverse-on-surface);
-	--inverse-primary: var(--md-sys-color-inverse-primary);
+	/* ─── CSS compatibility aliases for Light DOM / external styling ─── */
+	--color-primary: var(--moni-primary);
+	--color-on-primary: var(--moni-on-primary);
+	--color-primary-container: var(--moni-primary-container);
+	--color-on-primary-container: var(--moni-on-primary-container);
+
+	--color-secondary: var(--moni-secondary);
+	--color-on-secondary: var(--moni-on-secondary);
+	--color-secondary-container: var(--moni-secondary-container);
+	--color-on-secondary-container: var(--moni-on-secondary-container);
+
+	--color-tertiary: var(--moni-tertiary);
+	--color-on-tertiary: var(--moni-on-tertiary);
+	--color-tertiary-container: var(--moni-tertiary-container);
+	--color-on-tertiary-container: var(--moni-on-tertiary-container);
+
+	--color-error: var(--moni-error);
+	--color-on-error: var(--moni-on-error);
+	--color-error-container: var(--moni-error-container);
+	--color-on-error-container: var(--moni-on-error-container);
+
+	--color-background: var(--moni-background);
+	--color-on-background: var(--moni-on-background);
+	--color-surface: var(--moni-surface);
+	--color-on-surface: var(--moni-on-surface);
+	--color-surface-variant: var(--moni-surface-variant);
+	--color-on-surface-variant: var(--moni-on-surface-variant);
+
+	--color-outline: var(--moni-outline);
+	--color-outline-variant: var(--moni-outline-variant);
+
+	--color-surface-container-lowest: var(--moni-surface-container-lowest);
+	--color-surface-container-low: var(--moni-surface-container-low);
+	--color-surface-container: var(--moni-surface-container);
+	--color-surface-container-high: var(--moni-surface-container-high);
+	--color-surface-container-highest: var(--moni-surface-container-highest);
+
+	--color-inverse-surface: var(--moni-inverse-surface);
+	--color-inverse-on-surface: var(--moni-inverse-on-surface);
+	--color-inverse-primary: var(--moni-inverse-primary);
+
+	/* Deprecated global variables fallback (can be disabled if conflicting) */
+	--primary: var(--moni-primary);
+	--on-primary: var(--moni-on-primary);
+	--background: var(--moni-background);
+	--surface: var(--moni-surface);
+	--on-surface: var(--moni-on-surface);
+	--outline: var(--moni-outline);
 }

package/src/types/svelte-runes.d.ts

@@ -1,7 +1,69 @@
-// Minimal type declarations for Svelte 5 runes used in non-Svelte TS files.
-// These allow the project to type-check without requiring the Svelte compiler in the TS pipeline.
+/**
+ * @file types/svelte-runes.d.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 
+/**
+ * Minimal ambient type declarations for Svelte 5 compiler runes.
+ *
+ * Svelte 5 introduces "runes" — special compiler-recognized global functions
+ * (`$state`, `$derived`, `$effect`, `$props`) that are transformed at build
+ * time by the Svelte compiler. Outside the Svelte compiler pipeline (e.g.
+ * when TypeScript checks `.ts` files that use runes, like `theme.svelte.ts`),
+ * these globals are not declared, causing `tsc` to emit "Cannot find name '$state'"
+ * errors.
+ *
+ * This file declares them as simple pass-through generics so TypeScript is
+ * satisfied without requiring the Svelte compiler to be part of the `tsc`
+ * type-check pipeline.
+ *
+ * **Important:** These declarations reflect the type signatures of the runes,
+ * not their full runtime behavior. They are intentionally minimal — just enough
+ * to pass `tsc --noEmit`. The real reactive behavior is provided by the Svelte
+ * compiler at build time.
+ *
+ * @see {@link https://svelte.dev/docs/svelte/what-are-runes Svelte 5 Runes}
+ */
+
+/**
+ * Declares a reactive state variable.
+ * At runtime, reading or writing `value` triggers Svelte's fine-grained reactivity.
+ * For TypeScript checking outside the compiler, typed as a plain value.
+ *
+ * @template T - The type of the state value.
+ * @param initial - The initial value of the state.
+ * @returns A reactive reference to the value (typed as `T` for TS purposes).
+ */
 declare const $state: <T>(initial: T) => T;
+
+/**
+ * Declares a derived (computed) value that updates whenever its dependencies change.
+ * The function `fn` is re-run automatically by Svelte when any reactive state
+ * it reads changes.
+ *
+ * @template T - The type of the derived value.
+ * @param fn - A function that computes the derived value.
+ * @returns The computed value (typed as `T` for TS purposes).
+ */
 declare const $derived: <T>(fn: () => T) => T;
+
+/**
+ * Declares a reactive side effect that re-runs when its reactive dependencies change.
+ * The returned cleanup function (if any) is called before the effect re-runs and
+ * when the component is destroyed.
+ *
+ * @param fn - The effect function. May return a cleanup function.
+ */
 declare const $effect: (fn: () => void | (() => void)) => void;
+
+/**
+ * Declares the props of a Svelte 5 component as a reactive object.
+ * Used inside `<script>` blocks to destructure incoming properties with
+ * full TypeScript type support.
+ *
+ * @template T - The shape of the component's props. Defaults to `Record<string, unknown>`.
+ * @returns The component's props object.
+ */
 declare const $props: <T = Record<string, unknown>>() => T;