@moni-labs/moni-ui 0.2.0 → 0.3.1

package/src/components/moni-textarea.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-textarea.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, nothing } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -7,26 +14,50 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Visual-only textarea. Same field shell as moni-text-field but renders a
- * `<textarea>`. Visual-only: no `@input` listener.
+ * Material Design 3 Textarea component.
+ *
+ * A multi-line text input field designed for collecting longer amounts of text,
+ * such as comments, descriptions, or messages.
+ *
+ * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ *
+ * **Visual architecture:**
+ * It shares the exact same `.field` shell and styling engine as
+ * `<moni-text-field>`, but internally renders a native `<textarea>` instead
+ * of an `<input>`. This ensures visual consistency across all form elements
+ * regarding floating labels, helper text, error states, and icons.
+ *
+ * **Character Counter:**
+ * If the `maxlength` attribute is set, the textarea automatically displays
+ * a character counter (`{current length} / {maxlength}`) positioned at the
+ * trailing edge of the supporting text area (bottom right). This can be
+ * suppressed by setting the `no-counter` attribute.
+ *
+ * **State management:**
+ * This component is purely visual and presentational. It reflects attributes
+ * down to the native textarea, but it does NOT attach internal `@input` or
+ * `@change` listeners. Consumers should attach standard DOM listeners directly
+ * to this element to capture user input, just as they would with a native
+ * textarea.
+ *
+ * @example
+ * ```html
+ * <!-- Standard filled textarea -->
+ * <moni-textarea label="Description" rows="4"></moni-textarea>
  *
- * M3 spec (`m3-docs/components/text-fields/specs.md`): the textarea supports
- * both **filled** and **outlined** variants. When `maxlength` is set, a
- * character counter is shown next to the supporting text
- * (`{value.length} / {maxlength}`).
+ * <!-- Outlined textarea with character counter -->
+ * <moni-textarea
+ *   variant="outlined"
+ *   label="Bio"
+ *   maxlength="160"
+ * ></moni-textarea>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
- *  - icon:           leading Material Symbols name
- *  - trailing-icon:  trailing Material Symbols name
- *  - prefix:         short text rendered before the input (e.g. "https://")
- *  - suffix:         short text rendered after the input (e.g. ".com")
- *  - loading:        present → shows indeterminate circular progress
- *  - rows:           native textarea rows attribute (default 3)
- *  - maxlength:      when set, displays a character counter
- *                    (auto-shown; can be hidden via `no-counter`)
- *  - no-counter:     suppress the character counter even when maxlength is set
+ * @csspart field     - The outer `.field` div container.
+ * @csspart input     - The native `<textarea>` element.
+ * @csspart label     - The floating `<label>` element.
+ * @csspart helper    - The helper/error text area.
+ * @csspart counter   - The character counter element.
  */
 @customElement('moni-textarea')
 export class MoniTextarea extends MoniElement {

package/src/components/moni-time-picker.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-time-picker.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, PropertyValues } from 'lit';
 import { customElement, property, state, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
@@ -5,18 +12,42 @@ import './moni-icon.js';
 import './moni-button.js';
 
 /**
- * Material Design 3 Time Picker Component.
- * Supports interactive clock face (dial) and manual keyboard input.
+ * Material Design 3 Time Picker component.
+ *
+ * A highly interactive control that allows users to select a specific time.
+ * It provides two distinct input modes:
+ * 1. **Dial mode:** An interactive clock face where users can drag or click
+ *    to select hours and minutes.
+ * 2. **Input mode:** Standard text inputs for precise keyboard entry.
+ *
+ * **M3 spec reference:** `m3-docs/components/time-pickers/specs.md`
+ *
+ * **Time formats & modes:**
+ * - The `value` property expects and always outputs a 24-hour formatted string
+ *   (`HH:MM`, e.g., `"14:30"`).
+ * - Setting `use-24-hour` configures the visual presentation to use a 24-hour
+ *   clock dial (inner and outer rings) and removes the AM/PM toggle. Otherwise,
+ *   it uses a standard 12-hour dial with an AM/PM toggle.
+ *
+ * **Responsive design:**
+ * The `orientation` attribute configures the layout. `vertical` stacks the
+ * time display above the clock face, `horizontal` places them side-by-side,
+ * and `auto` responds to the container/viewport width automatically.
+ *
+ * @fires change - Fired when the selected time changes interactively. The
+ *                 `detail.value` contains the new time in `HH:MM` format.
+ * @fires cancel - Fired when the 'Cancel' button is clicked.
+ * @fires ok     - Fired when the 'OK' button is clicked. The `detail.value`
+ *                 contains the final confirmed time.
  *
- * Attributes:
- *  - value: Time value in "HH:MM" 24h format (default "00:00")
- *  - use24Hour: If true, uses 24-hour mode without AM/PM toggle (default false)
- *  - mode: "dial" | "input" (default "dial")
+ * @example
+ * ```html
+ * <!-- 12-hour format (AM/PM) -->
+ * <moni-time-picker value="14:30"></moni-time-picker>
  *
- * Events:
- *  - change: Fired when value changes (detail: { value })
- *  - cancel: Fired when cancel button is clicked
- *  - ok: Fired when OK button is clicked (detail: { value })
+ * <!-- 24-hour format -->
+ * <moni-time-picker use-24-hour value="14:30"></moni-time-picker>
+ * ```
  */
 @customElement('moni-time-picker')
 export class MoniTimePicker extends MoniElement {

package/src/components/moni-toolbar.ts

@@ -1,26 +1,55 @@
+/**
+ * @file components/moni-toolbar.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material 3 Toolbar (`m3-docs/components/top-app-bar/specs.md`).
+ * Material Design 3 Top App Bar (Toolbar) component.
+ *
+ * Top app bars display information and actions at the top of a screen.
+ * They are used for branding, screen titles, navigation, and actions.
+ *
+ * **M3 spec reference:** `m3-docs/components/top-app-bar/specs.md`
+ *
+ * **Note:** This is the standard top-level toolbar. For bottom navigation
+ * bars (often used on mobile), use `<moni-app-bar>`.
+ *
+ * **Variants:**
+ * - `standard` (default): A full-width bar (64dp height) that sits flush
+ *   against the top of the screen.
+ * - `floating`: A detached bar with a 4dp margin and rounded 8dp corners,
+ *   appearing to float above the content.
  *
- * This is the larger/top-level variant. If you need the compact
- * Navigation Bar at the bottom of the screen, use `<moni-app-bar>`.
+ * **Scroll behavior:**
+ * When the `scroll` attribute is present, the toolbar visually responds to
+ * scrolling by increasing its elevation (shadow) and dynamically shifting
+ * its surface color to indicate depth over the scrolling content.
  *
- * Supported M3 types:
- *  - **standard** (default): 64dp height, flat surface color, bottom shadow.
- *  - **floating**: 4dp margin, rounded 8dp corners, elevated.
+ * @example
+ * ```html
+ * <!-- Standard toolbar with navigation and actions -->
+ * <moni-toolbar title="Inbox">
+ *   <moni-icon-button slot="leading" icon="menu"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="search"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="more_vert"></moni-icon-button>
+ * </moni-toolbar>
  *
- * Slots:
- *  - default:       title / center content.
- *  - leading:       navigation icon/button.
- *  - trailing:      action icons/buttons.
- *  - action-button: floating action button (moni-fab) anchored right.
+ * <!-- Floating toolbar with an attached FAB -->
+ * <moni-toolbar type="floating" title="Notes">
+ *   <moni-fab slot="action-button" icon="add"></moni-fab>
+ * </moni-toolbar>
+ * ```
  *
- * Attributes:
- *  - type:   standard (default) | floating
- *  - scroll: true | false (default). When true, elevation increases on scroll.
+ * @slot default       - The title text or center content.
+ * @slot leading       - Navigation icon/button placed on the far left.
+ * @slot trailing      - Action icons/buttons placed on the far right.
+ * @slot action-button - A floating action button (FAB) anchored to the right side.
  */
 @customElement('moni-toolbar')
 export class MoniToolbar extends MoniElement {

package/src/components/moni-tooltip.ts

@@ -1,36 +1,67 @@
+/**
+ * @file components/moni-tooltip.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Tooltip that faithfully ports BeerCSS's `.tooltip` styles and adds M3
- * Expressive semantics.
+ * Material Design 3 Tooltip component.
+ *
+ * Tooltips provide contextual text labels or rich content that appear when
+ * users hover over, focus on, or tap an element. They surface supplementary
+ * information that helps users understand interface elements without
+ * permanently occupying screen space.
+ *
+ * **M3 spec reference:** `m3-docs/components/tooltips/specs.md`
+ *
+ * **Types:**
+ * - **Plain** (default) — Text-only label for simple descriptions (max 1 line).
+ * - **Rich** (`rich` attribute) — HTML content including formatted text,
+ *   links, and icons. Rich tooltips can contain multiple lines and action links.
+ *
+ * **Placements:**
+ * - `top` (default), `top-start`, `top-end`
+ * - `bottom`, `bottom-start`, `bottom-end`
+ *
+ * **Trigger mechanism:**
+ * The tooltip uses `position: absolute` inside the parent element. The parent
+ * must have `position: relative` (set automatically via `connectedCallback`).
+ * Hover/focus events on the parent trigger the tooltip's CSS `:hover` and
+ * `:focus-within` selectors, which drive the show/hide transition.
+ *
+ * **Accessibility:**
+ * - The tooltip has `role="tooltip"`.
+ * - For keyboard accessibility, the parent should have `aria-describedby`
+ *   pointing to the tooltip's `id` attribute. The component exposes a
+ *   `tooltipId` getter for this purpose.
+ * - The `Escape` key closes rich tooltips.
  *
- * **M3 spec** (`m3-docs/components/tooltips/specs.md`):
- *  - Two types: **plain** (text only) and **rich** (HTML content).
- *  - 6 placements: top, top-start, top-end, bottom, bottom-start, bottom-end.
- *  - Trigger: hover (mouse) or focus (keyboard) on the parent.
- *  - Auto-dismiss: tooltip hides on `mouseleave` / `focusout` / `Escape`.
+ * @example
+ * ```html
+ * <!-- Plain tooltip -->
+ * <button aria-describedby="save-tip">
+ *   Save
+ *   <moni-tooltip id="save-tip" text="Ctrl+S"></moni-tooltip>
+ * </button>
  *
- * The component delegates trigger detection to the parent element (consistent
- * with the original BeerCSS port). The tooltip element is `position: absolute`
- * inside the parent so it follows the trigger naturally.
+ * <!-- Rich tooltip -->
+ * <button>
+ *   Filter
+ *   <moni-tooltip rich position="bottom">
+ *     <strong>Filter by date</strong>
+ *     <p>Select a date range to filter results.</p>
+ *   </moni-tooltip>
+ * </button>
+ * ```
  *
- * **Accessibility**:
- *  - The tooltip has `role="tooltip"` (M3 spec).
- *  - When `rich` content is used, the parent should also have
- *    `aria-describedby="<tooltip-id>"`. The component sets a unique `id` on
- *    the tooltip element and exposes it via `tooltipId` getter.
- *  - `Escape` closes the tooltip (WAI-ARIA tooltip pattern).
+ * @slot default - Rich content for the tooltip body (only used when `rich=true`).
  *
- * Attributes:
- *  - text:      tooltip text (plain tooltip)
- *  - position:  top (default) | top-start | top-end | bottom | bottom-start | bottom-end
- *  - size:      '' (default) | small | medium | large
- *  - rich:      boolean — when true, the default slot accepts arbitrary HTML
- *               for rich content (links, icons, etc.). When false (default),
- *               the slot is rendered as text only.
- *  - id:        forwarded to the tooltip element (useful for aria-describedby)
+ * @csspart tooltip - The tooltip container element.
  */
 @customElement('moni-tooltip')
 export class MoniTooltip extends MoniElement {

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;
+}