@moni-labs/moni-ui 0.2.0 → 0.3.1

package/src/components/moni-button.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-button.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 { ifDefined } from 'lit/directives/if-defined.js';
@@ -6,41 +13,54 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Visual-only button. Renders a native `<button>` styled per Material 3 Expressive.
+ * Material Design 3 Button component.
+ *
+ * Buttons allow users to take actions and make choices with a single tap.
+ * This component provides all M3 button variants, sizes, and shape morphing
+ * capabilities (e.g. morphing to a pill shape on press or toggle).
+ *
+ * **M3 spec reference:** `m3-docs/components/buttons/specs.md`
+ *
+ * **Variants:**
+ * - `filled` (default) — High emphasis. Use for primary actions.
+ * - `tonal` — Medium emphasis. Secondary actions that still need to stand out.
+ * - `elevated` — Medium emphasis with shadow. Used when sitting on patterned backgrounds.
+ * - `outlined` — Medium emphasis, no fill. Secondary or tertiary actions.
+ * - `text` — Low emphasis. Tertiary actions (e.g. dialog cancel button).
+ *
+ * **Shape morphing (M3 Expressive feature):**
+ * - On press (active state): Round and square buttons morph to a slightly squarer
+ *   "pressed" shape with specific M3 corner radii (e.g. XS/S 8dp, M 12dp).
+ * - On toggle (`active` attribute): The resting shape flips (e.g. round ↔ square).
+ *
+ * **Rendering as a link:**
+ * When the `href` attribute is provided, the component internally renders as
+ * an `<a>` element instead of a `<button>`, allowing native routing and
+ * middle-click (open in new tab) behaviors while maintaining button visuals.
+ *
+ * @example
+ * ```html
+ * <!-- Primary filled button -->
+ * <moni-button icon="add">Create new</moni-button>
+ *
+ * <!-- Outlined button -->
+ * <moni-button variant="outlined">Cancel</moni-button>
  *
- * **Shape morph on press** (`m3-docs/components/buttons/specs.md` § Shape morph):
- * round and square buttons both morph to the same pressed shape, with per-size
- * corner radii: XS 8dp, S 8dp, M 12dp, L 16dp, XL 16dp. The per-size rules
- * `.button.{xsmall,small,large,xlarge,extra}:active` override the default
- * `:active` rule by specificity (0,4,0 vs 0,3,0).
+ * <!-- Toggle button (toggles active state on click) -->
+ * <moni-button icon="favorite" active>Like</moni-button>
  *
- * **Shape morph on selected** (toggle): when `active` is true, the resting
- * shape flips (round ↔ square). See `render()`.
+ * <!-- Link button -->
+ * <moni-button href="/settings" icon="settings">Settings</moni-button>
+ * ```
  *
- * Attributes:
- *  - variant:   filled (default) | tonal | elevated | outlined | text | fill
- *  - size:      xsmall | small | medium (default) | large | xlarge
- *               (legacy `extra` alias for `xlarge`, deprecated in v0.3.0)
- *  - shape:     round (default) | square | circle | no-round
- *               | left-round | right-round | top-round | bottom-round
- *               | left-round-flat | right-round-flat | top-round-flat
- *               | bottom-round-flat | inner-round
- *               (the `-flat` and `inner-round` shapes are Moni brand
- *                extensions; not part of M3 — see WEB_COMPONENT_GUIDELINES.md)
- *  - disabled:  present → native disabled
- *  - loading:   present → shows an indeterminate circular progress
- *  - active:    present → toggle (selection) state; applies shape morph
- *               (round↔square) and variant-specific color swap
- *  - icon:      Material Symbols name to prepend
- *  - icon-trailing: Material Symbols name to append
- *  - type:      button (default) | submit | reset
- *  - href:      present → renders as `<a>` instead of `<button>`
- *  - target:    for `<a>` rendering
+ * @slot default       - The button label text.
+ * @slot icon          - Optional override for the leading icon.
+ * @slot icon-trailing - Optional override for the trailing icon.
  *
- * Slots:
- *  - default:   button label
- *  - icon:      optional override for the leading icon
- *  - icon-trailing: optional override for the trailing icon
+ * @csspart button     - The inner `<button>` or `<a>` element.
+ * @csspart icon       - The leading icon container.
+ * @csspart label      - The label container.
+ * @csspart trailing-icon - The trailing icon container.
  */
 @customElement('moni-button')
 export class MoniButton extends MoniElement {

package/src/components/moni-card.ts

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