@francofantomius/material-components 1.0.1 → 1.1.0

package/llms.txt

@@ -0,0 +1,2326 @@
+# @francofantomius/material-components
+
+> Reusable, accessible, and lightweight Material Design 3 Web Components built with Lit.
+
+`@francofantomius/material-components` is a comprehensive suite of modern, accessible, and lightweight **Material Design 3 (M3)** Web Components built with [Lit](https://lit.dev/). They run natively in all modern browsers and integrate seamlessly with React (18/19), Vue 3, Angular, Svelte, Solid, or vanilla HTML and JavaScript.
+
+## Table of Contents
+
+- [Overview & Core Features](#overview--core-features)
+- [Installation & Setup](#installation--setup)
+- [Typography & Icons Setup](#typography--icons-setup)
+- [Import Strategies](#import-strategies)
+- [Theming & Color Palettes](#theming--color-palettes)
+- [Form Integration (FACE)](#form-integration-face)
+- [Framework Integration Guidelines](#framework-integration-guidelines)
+  - [React (18 / 19)](#react-18--19)
+  - [Vue 3](#vue-3)
+  - [Angular & Svelte](#angular--svelte)
+- [Component Index](#component-index)
+- [Component Reference](#component-reference)
+  - [Actions](#actions)
+    - [Button (`md-button`)](#button-md-button)
+    - [Button Group (`md-button-group`)](#button-group-md-button-group)
+    - [Segmented Button (`md-segmented-button`, `md-segmented-button-set`)](#segmented-button-md-segmented-button-md-segmented-button-set)
+    - [Split Button (`md-split-button`)](#split-button-md-split-button)
+    - [Icon Button (`md-icon-button`)](#icon-button-md-icon-button)
+    - [Floating Action Button (`md-fab`)](#floating-action-button-md-fab)
+    - [FAB Menu (`md-fab-menu`, `md-fab-menu-item`)](#fab-menu-md-fab-menu-md-fab-menu-item)
+    - [Toolbar (`md-toolbar`)](#toolbar-md-toolbar)
+  - [Inputs & Controls](#inputs--controls)
+    - [Text Field (`md-text-field`)](#text-field-md-text-field)
+    - [Checkbox (`md-checkbox`)](#checkbox-md-checkbox)
+    - [Radio & Radio Group (`md-radio`, `md-radio-group`)](#radio--radio-group-md-radio-md-radio-group)
+    - [Switch (`md-switch`)](#switch-md-switch)
+    - [Slider (`md-slider`)](#slider-md-slider)
+    - [Time Picker (`md-time-picker`)](#time-picker-md-time-picker)
+    - [Date Picker (`md-date-picker`)](#date-picker-md-date-picker)
+    - [Chip & Chip Set (`md-chip`, `md-chip-set`)](#chip--chip-set-md-chip-md-chip-set)
+    - [Search Bar (`md-search-bar`)](#search-bar-md-search-bar)
+  - [Surfaces & Containment](#surfaces--containment)
+    - [Card (`md-card`)](#card-md-card)
+    - [Dialog (`md-dialog`)](#dialog-md-dialog)
+    - [Divider (`md-divider`)](#divider-md-divider)
+    - [Menu (`md-menu`, `md-menu-item`)](#menu-md-menu-md-menu-item)
+    - [List & List Item (`md-list`, `md-list-item`)](#list--list-item-md-list-md-list-item)
+    - [Table & Data Table (`md-table`)](#table--data-table-md-table)
+    - [Side Sheet (`md-side-sheet`)](#side-sheet-md-side-sheet)
+    - [Bottom Sheet (`md-bottom-sheet`)](#bottom-sheet-md-bottom-sheet)
+    - [Carousel (`md-carousel`, `md-carousel-item`)](#carousel-md-carousel-md-carousel-item)
+  - [Communication & Feedback](#communication--feedback)
+    - [Badge (`md-badge`)](#badge-md-badge)
+    - [Progress Indicators (`md-progress`)](#progress-indicators-md-progress)
+    - [Loading Indicator (`md-loading-indicator`)](#loading-indicator-md-loading-indicator)
+    - [Snackbar (`md-snackbar`)](#snackbar-md-snackbar)
+    - [Tooltip (`md-tooltip`)](#tooltip-md-tooltip)
+  - [Navigation](#navigation)
+    - [Navigation Bar (`md-navigation-bar`, `md-navigation-bar-item`)](#navigation-bar-md-navigation-bar-md-navigation-bar-item)
+    - [Navigation Drawer (`md-navigation-drawer`, `md-navigation-drawer-item`)](#navigation-drawer-md-navigation-drawer-md-navigation-drawer-item)
+    - [Navigation Rail (`md-navigation-rail`, `md-navigation-rail-item`)](#navigation-rail-md-navigation-rail-md-navigation-rail-item)
+    - [Top App Bar (`md-top-app-bar`)](#top-app-bar-md-top-app-bar)
+    - [Tabs (`md-tabs`, `md-tab`)](#tabs-md-tabs-md-tab)
+    - [App Drawer (`md-app-drawer`, `md-app-drawer-item`)](#app-drawer-md-app-drawer-md-app-drawer-item)
+    - [Account Menu (`md-account-menu`, `md-account-item`)](#account-menu-md-account-menu-md-account-item)
+  - [Media & Playback](#media--playback)
+    - [Player (`md-player`)](#player-md-player)
+  - [Utilities & Data](#utilities--data)
+    - [Icon (`md-icon`)](#icon-md-icon)
+    - [Code Block & Highlighter (`md-code`)](#code-block--highlighter-md-code)
+
+---
+
+## Overview & Core Features
+
+- **Material Design 3 Specifications**: Adheres to official M3 guidelines for tokenized color systems, dynamic elevation, state layers, rounded shapes, and typography.
+- **Form-Associated Custom Elements (FACE)**: Text fields, checkboxes, switches, and radios utilize browser-native `ElementInternals` to participate in standard `<form>` submission, `FormData`, and native constraint validation (`required`, `checkValidity()`, `reportValidity()`).
+- **Tree-Shakeable Subpaths**: Import only the elements you need (e.g., `@francofantomius/material-components/button`) to keep bundle sizes minimal.
+- **Accessibility (a11y)**: Built-in WCAG 2.1 AA focus rings, full keyboard interactions, high-contrast support, and ARIA attributes.
+- **TypeScript Support**: Full `.d.ts` type declarations and `custom-elements.json` (Custom Elements Manifest) for IDE autocomplete and linting.
+- **Framework Agnostic**: Native Custom Elements work across React, Vue, Angular, Svelte, Solid, and vanilla HTML.
+
+---
+
+## Installation & Setup
+
+Install the library and its peer dependency `lit`:
+
+```bash
+npm install @francofantomius/material-components lit
+```
+
+---
+
+## Typography & Icons Setup
+
+Material 3 relies on **Roboto** for typography and **Material Symbols Outlined** for scalable vector icons. Include the Google Fonts stylesheets in your HTML `<head>`:
+
+```html
+<!-- Google Material Symbols Outlined font -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" />
+
+<!-- Google Roboto font -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" />
+```
+
+---
+
+## Import Strategies
+
+### 1. Subpath Imports (Recommended for Production)
+
+Import individual component modules to optimize tree-shaking:
+
+```javascript
+import '@francofantomius/material-components/button';
+import '@francofantomius/material-components/text-field';
+import '@francofantomius/material-components/card';
+```
+
+### 2. Full Component Bundle
+
+For quick prototyping or full component registration:
+
+```javascript
+import '@francofantomius/material-components';
+```
+
+---
+
+## Theming & Color Palettes
+
+### Material Design 3 CSS Custom Properties
+
+Configure tokens globally on `:root` or scope them to a container. Dark mode can be toggled using the `[data-theme='dark']` attribute:
+
+```css
+:root {
+  --md-sys-color-primary: #6750A4;
+  --md-sys-color-on-primary: #FFFFFF;
+  --md-sys-color-primary-container: #EADDFF;
+  --md-sys-color-on-primary-container: #21005D;
+  --md-sys-color-secondary: #625B71;
+  --md-sys-color-on-secondary: #FFFFFF;
+  --md-sys-color-surface: #FEF7FF;
+  --md-sys-color-on-surface: #1D1B20;
+  --md-sys-color-outline: #79747E;
+  --md-sys-color-error: #B3261E;
+}
+
+[data-theme='dark'] {
+  --md-sys-color-primary: #D0BCFF;
+  --md-sys-color-on-primary: #381E72;
+  --md-sys-color-primary-container: #4F378B;
+  --md-sys-color-on-primary-container: #EADDFF;
+  --md-sys-color-secondary: #CCC2DC;
+  --md-sys-color-on-secondary: #332D41;
+  --md-sys-color-surface: #141218;
+  --md-sys-color-on-surface: #E6E0E9;
+  --md-sys-color-outline: #938F99;
+  --md-sys-color-error: #F2B8B5;
+}
+```
+
+### TypeScript Theme Helper API
+
+The `@francofantomius/material-components/theme` module provides utilities for dynamic runtime palette assignment:
+
+```typescript
+import { applyTheme, darkColorScheme, lightColorScheme } from '@francofantomius/material-components/theme';
+
+// Switch to Dark Color Scheme
+applyTheme(darkColorScheme);
+
+// Switch back to Light Color Scheme
+applyTheme(lightColorScheme);
+
+// Apply Custom Brand Colors
+applyTheme({
+  primary: '#006A60',
+  onPrimary: '#FFFFFF',
+  primaryContainer: '#74F8E5',
+  onPrimaryContainer: '#00201C',
+});
+```
+
+---
+
+## Form Integration (FACE)
+
+Form controls (`<md-text-field>`, `<md-checkbox>`, `<md-switch>`, `<md-radio>`) are Form-Associated Custom Elements. They automatically participate in standard HTML forms and `FormData`.
+
+### HTML Form Example
+
+```html
+<form id="signup-form">
+  <md-text-field
+    name="fullname"
+    label="Full Name"
+    required
+    supporting-text="Enter your first and last name"
+  ></md-text-field>
+
+  <md-text-field
+    name="email"
+    label="Email Address"
+    type="email"
+    required
+  ></md-text-field>
+
+  <md-checkbox name="newsletter" checked>
+    Receive monthly newsletter
+  </md-checkbox>
+
+  <md-switch name="telemetry" selected icons>
+    Anonymous analytics
+  </md-switch>
+
+  <div style="margin-top: 16px; display: flex; gap: 12px;">
+    <md-button type="reset" variant="outlined">Reset</md-button>
+    <md-button type="submit" variant="filled">Submit Form</md-button>
+  </div>
+</form>
+```
+
+### JavaScript Handling
+
+```javascript
+const form = document.getElementById('signup-form');
+
+form.addEventListener('submit', (e) => {
+  e.preventDefault();
+  
+  if (!form.checkValidity()) {
+    form.reportValidity();
+    return;
+  }
+
+  const formData = new FormData(form);
+  const data = Object.fromEntries(formData.entries());
+  console.log('Submitted Payload:', data);
+});
+```
+
+---
+
+## Framework Integration Guidelines
+
+### React (18 / 19)
+
+React 19 supports Custom Elements natively (properties, attributes, and custom events). In React 18, use standard props/attributes or refs for complex events and properties.
+
+```tsx
+import React, { useState } from 'react';
+import '@francofantomius/material-components/button';
+import '@francofantomius/material-components/text-field';
+import '@francofantomius/material-components/switch';
+
+export function UserSettings() {
+  const [username, setUsername] = useState('Alice');
+  const [notifications, setNotifications] = useState(true);
+
+  return (
+    <div>
+      <md-text-field
+        label="Username"
+        value={username}
+        onInput={(e: any) => setUsername(e.target.value)}
+      />
+      <md-switch
+        selected={notifications}
+        onChange={(e: any) => setNotifications(e.target.selected)}
+      >
+        Notifications
+      </md-switch>
+      <md-button variant="filled" onClick={() => console.log('Saved!')}>
+        Save Settings
+      </md-button>
+    </div>
+  );
+}
+```
+
+### Vue 3
+
+Configure Vue's compiler to recognize `md-` tags as custom elements in `vite.config.js`:
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag.startsWith('md-')
+        }
+      }
+    })
+  ]
+});
+```
+
+Use inside SFC template:
+
+```html
+<script setup>
+import { ref } from 'vue';
+import '@francofantomius/material-components/button';
+import '@francofantomius/material-components/switch';
+
+const isEnabled = ref(true);
+</script>
+
+<template>
+  <div>
+    <md-switch :selected="isEnabled" @change="isEnabled = !isEnabled">
+      Enable Feature
+    </md-switch>
+    <md-button variant="filled" :disabled="!isEnabled">
+      Proceed
+    </md-button>
+  </div>
+</template>
+```
+
+### Angular & Svelte
+
+- **Angular**: Include `CUSTOM_ELEMENTS_SCHEMA` in `@NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })` or standalone component definition.
+- **Svelte**: Custom elements work natively with standard property and event bindings without extra wrappers.
+
+---
+
+## Component Index
+
+| Category | Component Tag | Subpath Import | Description |
+| :--- | :--- | :--- | :--- |
+| **Actions** | `<md-button>` | `@francofantomius/material-components/button` | Buttons with 5 visual emphasis levels |
+| **Actions** | `<md-button-group>` | `@francofantomius/material-components/button-group` | Button groups with connected shape-shifting or standard layouts |
+| **Actions** | `<md-segmented-button>`, `<md-segmented-button-set>` | `@francofantomius/material-components/segmented-button` | Compact single or multi-select option groups |
+| **Actions** | `<md-split-button>` | `@francofantomius/material-components/split-button` | Primary action button with connected dropdown trigger |
+| **Actions** | `<md-icon-button>` | `@francofantomius/material-components/icon-button` | Compact action & toggle buttons |
+| **Actions** | `<md-fab>` | `@francofantomius/material-components/fab` | Floating Action Button (small, medium, large, extended) |
+| **Actions** | `<md-fab-menu>`, `<md-fab-menu-item>` | `@francofantomius/material-components/fab-menu` | FAB Menu / Speed Dial expanding into stacked sub-actions with labels and modal scrim |
+| **Actions** | `<md-toolbar>` | `@francofantomius/material-components/toolbar` | M3 Expressive floating & docked action toolbar |
+| **Inputs & Controls** | `<md-text-field>` | `@francofantomius/material-components/text-field` | Filled & outlined inputs with validation |
+| **Inputs & Controls** | `<md-checkbox>` | `@francofantomius/material-components/checkbox` | Checkbox with indeterminate and error states |
+| **Inputs & Controls** | `<md-radio>`, `<md-radio-group>` | `@francofantomius/material-components/radio` | Mutually exclusive radio selections |
+| **Inputs & Controls** | `<md-switch>` | `@francofantomius/material-components/switch` | Toggle switch with optional thumb icons |
+| **Inputs & Controls** | `<md-slider>` | `@francofantomius/material-components/slider` | Continuous, discrete, and dual-thumb range sliders |
+| **Inputs & Controls** | `<md-time-picker>` | `@francofantomius/material-components/time-picker` | 12h/24h dial & input time picker with modal and docked modes |
+| **Inputs & Controls** | `<md-date-picker>` | `@francofantomius/material-components/date-picker` | Calendar grid, date range, month/year navigation in modal & docked modes |
+| **Inputs & Controls** | `<md-chip>`, `<md-chip-set>` | `@francofantomius/material-components/chip` | Assist, filter, input, and suggestion chips |
+| **Inputs & Controls** | `<md-search-bar>` | `@francofantomius/material-components/search-bar` | Docked and fullscreen search view |
+| **Surfaces & Containment** | `<md-card>` | `@francofantomius/material-components/card` | Elevated, filled, and outlined surface containers |
+| **Surfaces & Containment** | `<md-dialog>` | `@francofantomius/material-components/dialog` | Modal dialogs for prompts & confirmation |
+| **Surfaces & Containment** | `<md-divider>` | `@francofantomius/material-components/divider` | Horizontal, vertical, and inset separators |
+| **Surfaces & Containment** | `<md-menu>`, `<md-menu-item>` | `@francofantomius/material-components/menu` | Temporary surfaces displaying lists of choices anchored to triggers |
+| **Surfaces & Containment** | `<md-list>`, `<md-list-item>` | `@francofantomius/material-components/list` | 1-line, 2-line, and 3-line structured lists |
+| **Surfaces & Containment** | `<md-table>` | `@francofantomius/material-components/table` | Data table with sorting, selection, and pagination |
+| **Surfaces & Containment** | `<md-side-sheet>` | `@francofantomius/material-components/side-sheet` | Standard in-flow & modal overlay side sheets |
+| **Surfaces & Containment** | `<md-bottom-sheet>` | `@francofantomius/material-components/bottom-sheet` | Standard docked & modal overlay bottom sheets with drag gestures |
+| **Surfaces & Containment** | `<md-carousel>`, `<md-carousel-item>` | `@francofantomius/material-components/carousel` | Multi-browse, hero, and full-width image & content carousels |
+| **Communication & Feedback** | `<md-badge>` | `@francofantomius/material-components/badge` | Numeric count and status dot indicators |
+| **Communication & Feedback** | `<md-progress>` | `@francofantomius/material-components/progress` | Linear and circular progress with M3 wavy lines |
+| **Communication & Feedback** | `<md-loading-indicator>` | `@francofantomius/material-components/loading-indicator` | Contained & morphing shape loading indicator for short wait times |
+| **Communication & Feedback** | `<md-snackbar>` | `@francofantomius/material-components/snackbar` | Temporary bottom toast messages |
+| **Communication & Feedback** | `<md-tooltip>` | `@francofantomius/material-components/tooltip` | Plain & rich contextual tooltips with directional positioning and delays |
+| **Navigation** | `<md-navigation-bar>`, `<md-navigation-bar-item>` | `@francofantomius/material-components/navigation-bar` | Bottom navigation bar with 3-5 destinations, indicator pills, badges & label modes |
+| **Navigation** | `<md-navigation-drawer>` | `@francofantomius/material-components/navigation-drawer` | Side drawer navigation (modal / standard / responsive) |
+| **Navigation** | `<md-navigation-rail>`, `<md-navigation-rail-item>` | `@francofantomius/material-components/navigation-rail` | Vertical navigation rail for mid to large screens |
+| **Navigation** | `<md-top-app-bar>` | `@francofantomius/material-components/top-app-bar` | Header bar (small, center-aligned, medium, large) |
+| **Navigation** | `<md-tabs>`, `<md-tab>` | `@francofantomius/material-components/tabs` | Top tab navigation with sliding active indicator |
+| **Navigation** | `<md-app-drawer>` | `@francofantomius/material-components/app-drawer` | Popover application grid launcher with drag reordering |
+| **Navigation** | `<md-account-menu>` | `@francofantomius/material-components/account-menu` | Account switcher, credentials, security & storage popover |
+| **Media & Playback** | `<md-player>` | `@francofantomius/material-components/player` | Audio & video player with scrubber, queue, and volume |
+| **Utilities & Data** | `<md-icon>` | `@francofantomius/material-components/icon` | Material Symbols font icon wrapper |
+| **Utilities & Data** | `<md-code>` | `@francofantomius/material-components/code` | Syntax highlighter with real-time multi-language linting |
+
+---
+
+## Component Reference
+
+### Actions
+
+#### Button (`md-button`)
+
+- **Subpath**: `@francofantomius/material-components/button`
+- **Description**: Buttons help users initiate actions and choices with five distinct levels of visual emphasis: filled, elevated, tonal, outlined, and text.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'filled' \| 'elevated' \| 'tonal' \| 'outlined' \| 'text'` | `'filled'` | Visual emphasis style of the button |
+| `disabled` | `boolean` | `false` | Whether the button is interactive or disabled |
+| `loading` | `boolean` | `false` | Displays an internal circular progress spinner and disables click |
+| `icon` | `string` | `''` | Leading Material Symbols icon name |
+| `trailing-icon` | `string` | `''` | Trailing Material Symbols icon name |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML form button type |
+| `href` | `string` | `''` | When provided, renders as an accessible anchor link |
+| `target` | `string` | `''` | Link target attribute (e.g., `_blank`) |
+
+##### Code Example
+```html
+<md-button variant="filled">Filled</md-button>
+<md-button variant="elevated">Elevated</md-button>
+<md-button variant="tonal">Tonal</md-button>
+<md-button variant="outlined">Outlined</md-button>
+<md-button variant="text">Text</md-button>
+<md-button variant="filled" icon="add">Create New</md-button>
+<md-button variant="outlined" trailing-icon="arrow_forward">Next Step</md-button>
+<md-button variant="tonal" loading>Saving...</md-button>
+<md-button variant="outlined" href="https://material.io" target="_blank" trailing-icon="open_in_new">
+  Material Design Docs
+</md-button>
+```
+
+---
+
+#### Button Group (`md-button-group`)
+
+- **Subpath**: `@francofantomius/material-components/button-group`
+- **Description**: Button groups organize related action buttons into cohesive sets with standard or connected shape-shifting layouts according to Material Design 3 specifications.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation of the button group |
+| `connected` | `boolean` | `false` | Connects adjacent buttons with seamless shared borders and shape-shifting corner radii |
+| `shape` | `'pill' \| 'rounded' \| 'square'` | `'pill'` | Corner shape morphing style when connected |
+| `variant` | `'filled' \| 'elevated' \| 'tonal' \| 'outlined' \| 'text'` | `''` | Cascades a visual emphasis style to child buttons |
+| `full-width` | `boolean` | `false` | Stretches child buttons evenly across the container width |
+| `disabled` | `boolean` | `false` | Disables all child buttons in the group |
+
+##### Code Example
+```html
+<!-- Standard Button Group -->
+<md-button-group>
+  <md-button variant="outlined" icon="edit">Edit</md-button>
+  <md-button variant="outlined" icon="content_copy">Copy</md-button>
+  <md-button variant="filled" icon="share">Share</md-button>
+</md-button-group>
+
+<!-- Connected Shape-Shifting Group -->
+<md-button-group connected variant="outlined">
+  <md-button icon="format_align_left">Left</md-button>
+  <md-button icon="format_align_center">Center</md-button>
+  <md-button icon="format_align_right">Right</md-button>
+</md-button-group>
+
+<!-- Vertical Connected Group -->
+<md-button-group connected orientation="vertical" variant="outlined">
+  <md-button icon="zoom_in">Zoom In</md-button>
+  <md-button icon="zoom_out">Zoom Out</md-button>
+  <md-button icon="fit_screen">Reset</md-button>
+</md-button-group>
+```
+
+---
+
+#### Segmented Button (`md-segmented-button`, `md-segmented-button-set`)
+
+- **Subpath**: `@francofantomius/material-components/segmented-button`
+- **Description**: Segmented buttons help users select options, switch views, or sort elements in compact single-select or multi-select groups.
+
+##### Properties & Attributes (`md-segmented-button-set`)
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `multiselect` | `boolean` | `false` | Enables multi-selection mode across segments |
+| `disabled` | `boolean` | `false` | Disables all child segmented buttons in the set |
+
+##### Properties & Attributes (`md-segmented-button`)
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `selected` | `boolean` | `false` | Active selection state of the segment |
+| `disabled` | `boolean` | `false` | Disables segment interactions |
+| `value` | `string` | `''` | Value associated with the segment |
+| `label` | `string` | `''` | Label text of the segment |
+| `icon` | `string` | `''` | Leading Material Symbols icon name |
+| `no-checkmark` | `boolean` | `false` | Hides the automatic checkmark indicator when selected |
+
+##### Code Example
+```html
+<!-- Single select (e.g. view filter) -->
+<md-segmented-button-set>
+  <md-segmented-button selected label="Songs"></md-segmented-button>
+  <md-segmented-button label="Albums"></md-segmented-button>
+  <md-segmented-button label="Podcasts"></md-segmented-button>
+</md-segmented-button-set>
+
+<!-- Multi select (e.g. text formatting) -->
+<md-segmented-button-set multiselect>
+  <md-segmented-button icon="format_bold" label="Bold" selected></md-segmented-button>
+  <md-segmented-button icon="format_italic" label="Italic"></md-segmented-button>
+  <md-segmented-button icon="format_underlined" label="Underline"></md-segmented-button>
+</md-segmented-button-set>
+```
+
+---
+
+#### Split Button (`md-split-button`)
+
+- **Subpath**: `@francofantomius/material-components/split-button`
+- **Description**: Split buttons combine a primary action button with a connected dropdown trigger button for related contextual options.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'filled' \| 'elevated' \| 'tonal' \| 'outlined'` | `'filled'` | Visual emphasis style of the split button |
+| `disabled` | `boolean` | `false` | Disables both action and menu trigger buttons |
+| `label` | `string` | `''` | Primary action button text label |
+| `icon` | `string` | `''` | Leading icon for the primary action button |
+| `trailing-icon` | `string` | `'arrow_drop_down'` | Dropdown trigger icon name |
+| `open` | `boolean` | `false` | Whether the associated menu / options dropdown is open |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML form button type for the main action |
+| `action-aria-label` | `string` | `''` | Accessible label for the main action button |
+| `menu-aria-label` | `string` | `'More options'` | Accessible label for the trailing menu trigger button |
+
+##### Events
+| Name | Detail | Description |
+| :--- | :--- | :--- |
+| `action` | `{ target: MdSplitButton, open: boolean }` | Dispatched when the leading primary action button is clicked |
+| `trailing-click` | `{ target: MdSplitButton, open: boolean }` | Dispatched when the trailing dropdown menu button is clicked |
+| `toggle` | `{ target: MdSplitButton, open: boolean }` | Dispatched when the trailing menu trigger toggles open state |
+
+##### Code Example
+```html
+<!-- Default filled split button -->
+<md-split-button label="Save"></md-split-button>
+
+<!-- Split button with icons and tonal variant -->
+<md-split-button variant="tonal" icon="cloud_upload" label="Upload" trailing-icon="expand_more"></md-split-button>
+
+<!-- Outlined split button -->
+<md-split-button variant="outlined" label="Export"></md-split-button>
+```
+
+---
+
+#### Icon Button (`md-icon-button`)
+
+- **Subpath**: `@francofantomius/material-components/icon-button`
+- **Description**: Icon buttons allow users to take compact actions and toggle choices with a single tap, supporting standard, filled, tonal, and outlined variants.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'standard' \| 'filled' \| 'tonal' \| 'outlined'` | `'standard'` | Visual container style |
+| `icon` | `string` | `''` | Material Symbols icon name |
+| `selected-icon` | `string` | `''` | Icon displayed when toggle button is active |
+| `toggle` | `boolean` | `false` | Enables two-state toggle behavior |
+| `selected` | `boolean` | `false` | Active selection state for toggle buttons |
+| `disabled` | `boolean` | `false` | Disables button interactions |
+| `href` | `string` | `''` | Renders as hyperlink when present |
+
+##### Code Example
+```html
+<md-icon-button icon="favorite" variant="standard" aria-label="Favorite"></md-icon-button>
+<md-icon-button icon="star" variant="filled" aria-label="Bookmark"></md-icon-button>
+<md-icon-button icon="settings" variant="tonal" aria-label="Settings"></md-icon-button>
+<md-icon-button icon="share" variant="outlined" aria-label="Share"></md-icon-button>
+
+<!-- Toggle Icon Buttons -->
+<md-icon-button toggle icon="bookmark_border" selected-icon="bookmark" aria-label="Bookmark"></md-icon-button>
+<md-icon-button toggle variant="tonal" icon="notifications_none" selected-icon="notifications" aria-label="Alerts"></md-icon-button>
+```
+
+---
+
+#### Floating Action Button (`md-fab`)
+
+- **Subpath**: `@francofantomius/material-components/fab`
+- **Description**: A Floating Action Button (FAB) performs the primary, most common action on a screen. Supports small, medium, large, and extended modes.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Container dimension |
+| `icon` | `string` | `''` | Material Symbols icon name |
+| `label` | `string` | `''` | Extended text label (renders extended FAB) |
+| `lowered` | `boolean` | `false` | Applies lower elevation level 1 instead of level 3 |
+| `disabled` | `boolean` | `false` | Disables button interaction |
+
+##### Code Example
+```html
+<md-fab size="small" icon="edit" aria-label="Edit"></md-fab>
+<md-fab icon="add" label="New Message"></md-fab>
+<md-fab size="large" icon="palette" aria-label="Palette"></md-fab>
+<md-fab icon="download" lowered aria-label="Download"></md-fab>
+```
+
+---
+
+#### FAB Menu (`md-fab-menu`, `md-fab-menu-item`)
+
+- **Subpath**: `@francofantomius/material-components/fab-menu`
+- **Description**: A Floating Action Button Menu (FAB Menu / Speed Dial) expands a primary FAB into a stack of contextual sub-actions with text labels, animated transitions, and optional modal scrim overlay.
+
+##### Properties & Attributes (`md-fab-menu`)
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Whether the menu stack is open |
+| `modal` | `boolean` | `false` | Displays a scrim backdrop overlay behind the open menu |
+| `direction` | `'up' \| 'down' \| 'left' \| 'right'` | `'up'` | Direction the sub-action stack expands |
+| `icon` | `string` | `'add'` | Material Symbols icon for the trigger FAB |
+| `open-icon` | `string` | `''` | Optional distinct icon shown when opened (defaults to 45° rotation) |
+| `label` | `string` | `''` | Extended text label for the trigger FAB |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Trigger FAB button size |
+| `lowered` | `boolean` | `false` | Applies lower elevation level 1 instead of level 3 |
+| `disabled` | `boolean` | `false` | Disables menu trigger and interactions |
+| `close-on-item-click` | `boolean` | `true` | Automatically closes menu when a sub-item is clicked |
+| `close-on-outside-click` | `boolean` | `true` | Automatically closes menu when clicking outside |
+
+##### Properties & Attributes (`md-fab-menu-item`)
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `icon` | `string` | `''` | Material Symbols icon name for the sub-action |
+| `label` | `string` | `''` | Text label displayed beside the mini-FAB |
+| `label-placement` | `'start' \| 'end' \| 'top' \| 'bottom'` | `'start'` | Positioning of the label pill relative to the sub-FAB |
+| `disabled` | `boolean` | `false` | Disables sub-action item interactions |
+| `value` | `string` | `''` | Value or identifier for the action |
+| `size` | `'small' \| 'medium'` | `'small'` | Size of the mini-FAB button |
+| `lowered` | `boolean` | `false` | Lower elevation level |
+
+##### Events
+| Name | Detail | Description |
+| :--- | :--- | :--- |
+| `open` | `undefined` | Dispatched when the FAB menu opens |
+| `close` | `undefined` | Dispatched when the FAB menu closes |
+| `toggle` | `{ open: boolean }` | Dispatched when the menu toggles open/close state |
+| `action` | `{ item: MdFabMenuItem, value: string, label: string }` | Dispatched when a sub-action item is activated |
+| `scrim-click` | `undefined` | Dispatched when modal scrim backdrop is clicked |
+
+##### Code Example
+```html
+<!-- Standard Upward FAB Menu -->
+<md-fab-menu icon="add">
+  <md-fab-menu-item icon="edit" label="Create Post" value="post"></md-fab-menu-item>
+  <md-fab-menu-item icon="photo_camera" label="Upload Photo" value="photo"></md-fab-menu-item>
+  <md-fab-menu-item icon="videocam" label="Go Live" value="live"></md-fab-menu-item>
+</md-fab-menu>
+
+<!-- Modal FAB Menu with Scrim -->
+<md-fab-menu modal icon="add" label="Actions">
+  <md-fab-menu-item icon="mail" label="New Message" value="email"></md-fab-menu-item>
+  <md-fab-menu-item icon="event" label="Schedule Event" value="event"></md-fab-menu-item>
+</md-fab-menu>
+```
+
+---
+
+#### Toolbar (`md-toolbar`)
+
+- **Subpath**: `@francofantomius/material-components/toolbar`
+- **Description**: Material Design 3 Expressive Action Toolbar for housing actions, tools, controls, and integrated floating action buttons in floating island or docked edge-to-edge layouts.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mode` | `'floating' \| 'docked'` | `'floating'` | Layout mode: floating island or docked bar |
+| `docked` | `boolean` | `false` | Shorthand boolean to activate docked mode |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Controls layout orientation |
+| `elevated` | `boolean` | `false` | Increases elevation shadow depth |
+| `fixed` | `boolean` | `false` | Pins position relative to viewport |
+| `dock-position` | `'none' \| 'top' \| 'bottom' \| 'left' \| 'right'` | `'none'` | Viewport edge when docked and fixed |
+| `aria-label` | `string` | `''` | Accessible label for screen readers |
+
+##### Slots
+| Slot Name | Description |
+| :--- | :--- |
+| *(default)* | Primary action buttons, segmented buttons, switches, and dividers |
+| `leading` | Leading navigation or anchor icons |
+| `trailing` | Trailing action buttons or overflow menus |
+| `fab` / `action` | Slotted Primary Action / Floating Action Button (FAB) |
+
+##### Code Example
+```html
+<!-- Floating Action Toolbar -->
+<md-toolbar aria-label="Formatting Actions">
+  <md-icon-button icon="format_bold" aria-label="Bold"></md-icon-button>
+  <md-icon-button icon="format_italic" aria-label="Italic"></md-icon-button>
+  <md-divider vertical></md-divider>
+  <md-icon-button icon="format_align_left" aria-label="Align left"></md-icon-button>
+  <md-fab slot="fab" size="small" icon="edit" aria-label="Edit"></md-fab>
+</md-toolbar>
+
+<!-- Docked Bottom Toolbar -->
+<md-toolbar mode="docked" aria-label="Document Controls">
+  <div slot="leading">
+    <md-icon-button icon="attachment" aria-label="Attach"></md-icon-button>
+  </div>
+  <div slot="trailing">
+    <md-button variant="filled" label="Publish"></md-button>
+  </div>
+</md-toolbar>
+```
+
+---
+
+### Inputs & Controls
+
+#### Text Field (`md-text-field`)
+
+- **Subpath**: `@francofantomius/material-components/text-field`
+- **Description**: Text fields allow users to enter and edit text, supporting filled and outlined variants, floating labels, validation states, and prefix/suffix text.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'filled' \| 'outlined'` | `'filled'` | Container visual style |
+| `label` | `string` | `''` | Floating label text |
+| `value` | `string` | `''` | Current input value |
+| `type` | `string` | `'text'` | Input type (`text`, `email`, `password`, `number`, etc.) |
+| `placeholder` | `string` | `''` | Placeholder displayed when focused |
+| `prefix-text` | `string` | `''` | Affix text before the value |
+| `suffix-text` | `string` | `''` | Affix text after the value |
+| `supporting-text` | `string` | `''` | Helper text below the field |
+| `error` | `boolean` | `false` | Forces input into error visual state |
+| `error-text` | `string` | `''` | Error message shown when error is true |
+| `leading-icon` | `string` | `''` | Material Symbols leading icon |
+| `trailing-icon` | `string` | `''` | Material Symbols trailing icon |
+| `maxlength` | `number` | `-1` | Maximum character length with visual counter |
+| `required` | `boolean` | `false` | Form validation required constraint |
+| `disabled` | `boolean` | `false` | Disables user input |
+| `readonly` | `boolean` | `false` | Prevents text editing |
+
+##### Code Example
+```html
+<md-text-field label="Full Name" supporting-text="Your legal name"></md-text-field>
+<md-text-field variant="outlined" label="Email Address" type="email" leading-icon="mail"></md-text-field>
+<md-text-field variant="outlined" label="Price" prefix-text="$" suffix-text=".00" value="99"></md-text-field>
+<md-text-field variant="outlined" label="Bio" maxlength="50" supporting-text="Max 50 characters"></md-text-field>
+<md-text-field variant="outlined" label="Password" type="password" error error-text="Password must be at least 8 characters" value="pass"></md-text-field>
+```
+
+---
+
+#### Checkbox (`md-checkbox`)
+
+- **Subpath**: `@francofantomius/material-components/checkbox`
+- **Description**: Checkboxes allow users to select one or more items from a set, or toggle between checked, unchecked, and indeterminate states.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `checked` | `boolean` | `false` | Checked state |
+| `indeterminate` | `boolean` | `false` | Partially selected state |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+| `required` | `boolean` | `false` | Form validation constraint |
+| `error` | `boolean` | `false` | Applies error color styling |
+| `name` | `string` | `''` | HTML form input name |
+| `value` | `string` | `'on'` | HTML form submitted value |
+
+##### Code Example
+```html
+<md-checkbox checked>I agree to terms</md-checkbox>
+<md-checkbox indeterminate>Select all children</md-checkbox>
+<md-checkbox>Unchecked option</md-checkbox>
+<md-checkbox disabled checked>Disabled selection</md-checkbox>
+```
+
+---
+
+#### Radio & Radio Group (`md-radio`, `md-radio-group`)
+
+- **Subpath**: `@francofantomius/material-components/radio`
+- **Description**: Radio buttons allow users to select exactly one option from a set of mutually exclusive choices, organized within an `md-radio-group`.
+
+##### `<md-radio>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `checked` | `boolean` | `false` | Checked state of `md-radio` |
+| `value` | `string` | `'on'` | Value associated with `md-radio` |
+| `disabled` | `boolean` | `false` | Disables this radio button |
+
+##### `<md-radio-group>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `string` | `''` | Group name shared across radio buttons |
+| `value` | `string` | `''` | Currently selected radio value |
+| `row` | `boolean` | `false` | Arranges radio items horizontally |
+
+##### Code Example
+```html
+<md-radio-group name="shipping" value="express">
+  <md-radio value="standard">Standard Shipping (3-5 days)</md-radio>
+  <md-radio value="express">Express Delivery (1-2 days)</md-radio>
+  <md-radio value="overnight" disabled>Overnight Priority (Unavailable)</md-radio>
+</md-radio-group>
+
+<md-radio-group row name="size" value="m">
+  <md-radio value="s">Small</md-radio>
+  <md-radio value="m">Medium</md-radio>
+  <md-radio value="l">Large</md-radio>
+</md-radio-group>
+```
+
+---
+
+#### Switch (`md-switch`)
+
+- **Subpath**: `@francofantomius/material-components/switch`
+- **Description**: Switches toggle the state of a single setting on or off, with optional check and cross icons inside the thumb.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `selected` | `boolean` | `false` | On/Off toggle state |
+| `icons` | `boolean` | `false` | Displays check and cross icons inside thumb |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+| `name` | `string` | `''` | HTML form input name |
+| `value` | `string` | `'on'` | HTML form submitted value |
+
+##### Code Example
+```html
+<md-switch selected icons>Wi-Fi</md-switch>
+<md-switch selected>Bluetooth</md-switch>
+<md-switch disabled>Airplane Mode</md-switch>
+```
+
+---
+
+#### Slider (`md-slider`)
+
+- **Subpath**: `@francofantomius/material-components/slider`
+- **Description**: Sliders allow users to view and select a value (or range of values) along a horizontal track, supporting continuous or discrete steps, dual-thumb range selection, value indicator balloon tooltips, and leading/trailing icons.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `number` | `50` | Current value for single slider mode |
+| `value-start` | `number` | `0` | Start value for dual-thumb range mode |
+| `value-end` | `number` | `100` | End value for dual-thumb range mode |
+| `min` | `number` | `0` | Minimum allowed value |
+| `max` | `number` | `100` | Maximum allowed value |
+| `step` | `number` | `1` | Granularity step increment |
+| `range` | `boolean` | `false` | Enables dual-thumb range selection mode |
+| `ticks` | `boolean` | `false` | Displays discrete step tick marks along the track |
+| `labeled` | `boolean` | `false` | Shows floating value indicator balloon tooltip above thumb |
+| `icon` | `string` | `''` | Leading Material Symbols icon name |
+| `leading-icon` | `string` | `''` | Leading Material Symbols icon name |
+| `trailing-icon` | `string` | `''` | Trailing Material Symbols icon name |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+| `name` | `string` | `''` | HTML form input name |
+| `name-start` | `string` | `''` | HTML form input name for start value (range mode) |
+| `name-end` | `string` | `''` | HTML form input name for end value (range mode) |
+
+##### Slots
+- `leading-icon`: Custom leading icon or element.
+- `trailing-icon`: Custom trailing icon or element.
+
+##### Events
+- `input`: Dispatched continuously while dragging or adjusting with keys (`detail: { value, valueStart, valueEnd }`).
+- `change`: Dispatched on pointer release or committed keyboard change (`detail: { value, valueStart, valueEnd }`).
+
+##### Code Example
+```html
+<!-- Continuous Slider with Icons -->
+<md-slider value="60" icon="volume_down" trailing-icon="volume_up"></md-slider>
+
+<!-- Discrete Stepped Slider with Ticks & Value Indicator -->
+<md-slider min="0" max="100" step="10" value="40" ticks labeled></md-slider>
+
+<!-- Dual-Thumb Range Slider -->
+<md-slider range min="0" max="100" value-start="20" value-end="80" labeled></md-slider>
+
+<!-- Disabled Slider -->
+<md-slider value="50" disabled icon="lock"></md-slider>
+```
+
+---
+
+#### Chip & Chip Set (`md-chip`, `md-chip-set`)
+
+- **Subpath**: `@francofantomius/material-components/chip`
+- **Description**: Chips help users enter information, make selections, filter content, or trigger actions across assist, filter, input, and suggestion variants.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'assist' \| 'filter' \| 'input' \| 'suggestion'` | `'assist'` | Chip visual and interaction style |
+| `label` | `string` | `''` | Chip text content |
+| `icon` | `string` | `''` | Material Symbols leading icon |
+| `selected` | `boolean` | `false` | Selected state for filter chips |
+| `removable` | `boolean` | `false` | Shows trailing remove button for input chips |
+| `disabled` | `boolean` | `false` | Disables chip interactions |
+
+##### Code Example
+```html
+<md-chip-set>
+  <md-chip variant="assist" icon="event" label="Add to Calendar"></md-chip>
+  <md-chip variant="filter" selected label="Material 3"></md-chip>
+  <md-chip variant="input" label="Removable Tag" removable></md-chip>
+  <md-chip variant="suggestion" label="Suggested Query"></md-chip>
+</md-chip-set>
+```
+
+---
+
+#### Search Bar (`md-search-bar`)
+
+- **Subpath**: `@francofantomius/material-components/search-bar`
+- **Description**: Search bars allow users to enter queries and view search suggestions in docked or full-screen responsive views, following Material Design 3 guidelines.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `string` | `''` | Current query value in the search bar |
+| `placeholder` | `string` | `'Search'` | Placeholder label for the input |
+| `active` | `boolean` | `false` | Controls whether search view is expanded and showing suggestions |
+| `suggestions` | `Array<string \| SearchSuggestion>` | `[]` | List of search suggestions with labels, supporting text, and icons |
+| `leading-icon` | `string` | `'search'` | Leading icon displayed when inactive |
+| `active-leading-icon` | `string` | `'arrow_back'` | Leading icon displayed when active |
+| `trailing-icon` | `string` | `''` | Optional trailing action icon |
+| `show-back-button` | `boolean` | `true` | Whether to show the back button in active mode |
+| `responsive` | `boolean` | `true` | Automatically switches to full-screen view and collapsed search icon on mobile (<= 768px) |
+| `collapse-on-mobile` | `boolean` | `true` | Collapses search bar into a compact search icon button on mobile screens when inactive |
+| `fullscreen` | `boolean` | `false` | Forces full-screen search view overlay when active |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+
+##### Slots
+- `leading-icon`: Custom leading icon or button element.
+- `trailing-icon`: Custom trailing action buttons, avatar, or mic.
+- `suggestions`: Custom slotted suggestions list.
+- `(default)`: Additional content rendered inside active search surface.
+
+##### Events
+- `input`: Fired as user types (`detail: { value: string }`).
+- `change`: Fired on committed input change (`detail: { value: string }`).
+- `search`: Fired when user presses Enter or selects a suggestion (`detail: { value: string, suggestion?: object }`).
+- `active-change`: Fired when search bar expands/collapses (`detail: { active: boolean }`).
+- `suggestion-select`: Fired when a suggestion is selected (`detail: { suggestion: object, value: string, index: number }`).
+- `clear`: Fired when search value is cleared.
+
+##### Code Example
+```html
+<md-search-bar
+  id="demo-search-bar"
+  placeholder="Search destinations, hotels, flights..."
+  trailing-icon="mic"
+></md-search-bar>
+
+<!-- Custom Slotted Content in Active State -->
+<md-search-bar placeholder="Search files & documents">
+  <div style="padding: 12px 16px;">
+    <p style="margin: 0 0 8px 0; font-size: 13px; font-weight: 500;">Recent Searches</p>
+    <div style="display: flex; gap: 8px; flex-wrap: wrap;">
+      <md-chip label="Q4 Financial Report" icon="history"></md-chip>
+      <md-chip label="Design System M3" icon="history"></md-chip>
+    </div>
+  </div>
+</md-search-bar>
+```
+
+---
+
+#### Time Picker (`md-time-picker`)
+
+- **Subpath**: `@francofantomius/material-components/time-picker`
+- **Description**: Time pickers help users select and set a specific time using an interactive Material Design 3 clock dial or numeric text inputs, in both 12-hour (AM/PM) and 24-hour formats with modal or docked modes.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `string` | `''` | Current time value string (e.g. `'08:30 AM'` or `'14:30'`) |
+| `format` | `'12h' \| '24h'` | `'12h'` | Time display and selection format |
+| `view` | `'dial' \| 'input'` | `'dial'` | Active presentation mode: interactive clock dial or numeric text fields |
+| `modal` | `boolean` | `false` | Displays picker as a modal dialog overlay with backdrop scrim |
+| `open` | `boolean` | `false` | Controls open/close visibility state when in modal mode |
+| `headline` | `string` | `'Select time'` | Header headline text |
+| `auto-switch-to-minute` | `boolean` | `true` | Automatically transitions active field from hour to minute on dial |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+| `name` | `string` | `''` | HTML form input name (FACE) |
+| `required` | `boolean` | `false` | Form validation required constraint |
+
+##### Methods
+- `showModal()`: Opens the time picker as a modal dialog.
+- `show()`: Opens the time picker.
+- `close(returnValue?: string)`: Closes the modal time picker.
+- `confirm()`: Commits the selected time and fires `change` / `confirm` events.
+- `cancel()`: Cancels selection and dismisses modal dialog.
+- `getFormattedTime()`: Returns current formatted time according to `format`.
+- `getFormatted24()`: Returns current time in 24-hour `'HH:MM'` format.
+- `getFormatted12()`: Returns current time in 12-hour `'hh:mm A'` format.
+
+##### Events
+- `change`: Dispatched when a time value is confirmed or committed (`detail: { value, hour, minute, period, formatted24, formatted12 }`).
+- `input`: Dispatched during interactive time adjustment (`detail: { value, hour, minute, period, formatted24, formatted12 }`).
+- `confirm`: Dispatched when the user clicks OK (`detail: { value, hour, minute, period, formatted24, formatted12 }`).
+- `cancel`: Dispatched when selection is canceled or backdrop is clicked.
+- `open`: Dispatched when modal dialog opens.
+- `close`: Dispatched when modal dialog closes (`detail: { returnValue?: string }`).
+
+##### Code Example
+```html
+<!-- 12-hour Clock Dial Picker -->
+<md-time-picker format="12h" value="09:30 AM"></md-time-picker>
+
+<!-- 24-hour Text Input Mode -->
+<md-time-picker view="input" format="24h" value="14:45"></md-time-picker>
+
+<!-- Modal Time Picker with Trigger Button -->
+<md-button variant="filled" icon="schedule" onclick="document.getElementById('alarm-picker').showModal()">
+  Set Alarm
+</md-button>
+<md-time-picker id="alarm-picker" modal headline="Set Alarm" value="07:00 AM"></md-time-picker>
+```
+
+---
+
+#### Date Picker (`md-date-picker`)
+
+- **Subpath**: `@francofantomius/material-components/date-picker`
+- **Description**: Date pickers let people select a date or range of dates using an interactive calendar grid, month/year navigation, and Material Design 3 styling in docked and modal dialog formats.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'docked' \| 'modal'` | `'docked'` | Presentation format: inline/docked container or modal dialog overlay |
+| `range` | `boolean` | `false` | Enables date range selection mode (start date and end date) |
+| `value` | `string` | `''` | Selected date string (ISO `'YYYY-MM-DD'` or `'YYYY-MM-DD/YYYY-MM-DD'` for range) |
+| `start-date` | `string` | `''` | Start date in range selection mode |
+| `end-date` | `string` | `''` | End date in range selection mode |
+| `min` | `string` | `''` | Minimum selectable date constraint (ISO `'YYYY-MM-DD'`) |
+| `max` | `string` | `''` | Maximum selectable date constraint (ISO `'YYYY-MM-DD'`) |
+| `label` | `string` | `''` | Header subhead / supporting label text (e.g. `'Select date'`) |
+| `headline` | `string` | `''` | Custom header headline text (defaults to formatted date) |
+| `open` | `boolean` | `false` | Controls open/close visibility state when in modal mode |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+| `required` | `boolean` | `false` | Form validation required constraint |
+| `first-day-of-week` | `number` | `0` | Starting day of week: `0` for Sunday, `1` for Monday |
+| `show-actions` | `boolean` | `false` | Displays bottom action buttons (Cancel / OK) in docked mode |
+| `error` | `boolean` | `false` | Applies error visual styling |
+| `error-text` | `string` | `''` | Validation error message |
+| `supporting-text` | `string` | `''` | Helper text below the date picker |
+| `name` | `string` | `''` | HTML form input name (FACE) |
+
+##### Methods
+- `showModal()`: Opens the date picker as a modal dialog overlay.
+- `show()`: Opens the date picker.
+- `close()`: Closes the modal date picker.
+- `reset()`: Clears the selected date(s) and form association.
+
+##### Events
+- `change`: Dispatched when date selection is committed (`detail: { value, startDate?, endDate? }`).
+- `input`: Dispatched when date input value updates (`detail: { value }`).
+- `select`: Dispatched when an individual day is clicked (`detail: { date, type: 'single' | 'start' | 'end' }`).
+- `open`: Dispatched when modal dialog opens.
+- `close`: Dispatched when modal dialog closes.
+- `cancel`: Dispatched when modal dialog is canceled or backdrop is clicked.
+
+##### Code Example
+```html
+<!-- Docked Single Date Picker -->
+<md-date-picker value="2026-08-22" label="Select date"></md-date-picker>
+
+<!-- Date Range Picker -->
+<md-date-picker range value="2026-08-10/2026-08-20" label="Select range"></md-date-picker>
+
+<!-- Min and Max Date Constraints -->
+<md-date-picker min="2026-08-05" max="2026-08-25" value="2026-08-15"></md-date-picker>
+
+<!-- Modal Date Picker with Trigger Button -->
+<md-button variant="filled" icon="calendar_month" onclick="document.getElementById('booking-datepicker').showModal()">
+  Select Date
+</md-button>
+<md-date-picker id="booking-datepicker" variant="modal" value="2026-08-22"></md-date-picker>
+```
+
+---
+
+### Surfaces & Containment
+
+#### Card (`md-card`)
+
+- **Subpath**: `@francofantomius/material-components/card`
+- **Description**: Cards contain content and actions about a single subject, available in elevated, filled, and outlined styles with optional ripple interactivity.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'elevated' \| 'filled' \| 'outlined'` | `'elevated'` | Card visual style |
+| `interactive` | `boolean` | `false` | Enables hover elevation and ripple effect |
+| `disabled` | `boolean` | `false` | Disables card interactions |
+| `href` | `string` | `''` | Renders card as anchor link |
+| `target` | `string` | `''` | Anchor target when href is provided |
+
+##### Slots
+- `header`: Top card header content.
+- `actions`: Bottom actions button container.
+- `(default)`: Main card body content.
+
+##### Code Example
+```html
+<md-card variant="outlined" style="max-width: 340px;">
+  <div slot="header">
+    <h3 style="margin: 0; font-size: 18px;">Outlined Card</h3>
+  </div>
+  Explore our Material Design 3 component library with built-in interactive feedback.
+  <div slot="actions">
+    <md-button variant="text">Dismiss</md-button>
+    <md-button variant="filled">Learn More</md-button>
+  </div>
+</md-card>
+```
+
+---
+
+#### Dialog (`md-dialog`)
+
+- **Subpath**: `@francofantomius/material-components/dialog`
+- **Description**: Dialogs inform users about a task and can contain critical information, require decisions, or involve multiple tasks.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Reflects open/closed state of modal |
+| `headline` | `string` | `''` | Header title text |
+| `icon` | `string` | `''` | Material Symbols header icon |
+
+##### Slots
+- `actions`: Modal action buttons (Cancel, Confirm).
+- `(default)`: Dialog message body content.
+
+##### Events
+- `open`: Dispatched when dialog modal opens.
+- `close`: Dispatched when dialog closes (`detail: { returnValue?: string }`).
+- `cancel`: Dispatched when dialog is dismissed via Escape key.
+
+##### Code Example
+```html
+<md-button variant="filled" id="open-dialog-btn">Open Dialog</md-button>
+
+<md-dialog id="demo-dialog" headline="Discard Draft?" icon="warning">
+  Are you sure you want to discard your changes? This action cannot be undone.
+  <div slot="actions">
+    <md-button variant="text" id="cancel-btn">Cancel</md-button>
+    <md-button variant="filled" id="confirm-btn">Discard</md-button>
+  </div>
+</md-dialog>
+```
+
+---
+
+#### Divider (`md-divider`)
+
+- **Subpath**: `@francofantomius/material-components/divider`
+- **Description**: A divider is a thin line that groups content in lists and page layouts, supporting inset and vertical orientations.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `vertical` | `boolean` | `false` | Renders a vertical divider |
+| `inset` | `boolean` | `false` | Adds 16px start and end margins |
+| `inset-start` | `boolean` | `false` | Adds 16px margin only to the start |
+| `inset-end` | `boolean` | `false` | Adds 16px margin only to the end |
+
+##### Code Example
+```html
+<div>Section Item Alpha</div>
+<md-divider></md-divider>
+<div>Section Item Beta</div>
+<md-divider inset></md-divider>
+<div>Section Item Gamma</div>
+```
+
+---
+
+#### Menu (`md-menu`, `md-menu-item`)
+
+- **Subpath**: `@francofantomius/material-components/menu`
+- **Description**: Menus display a list of choices on temporary surfaces when users interact with a trigger or contextual control, supporting anchoring, keyboard navigation, supporting text, and selection events.
+
+##### `<md-menu>` Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Reflects open/closed visibility state |
+| `anchor` | `string \| HTMLElement \| null` | `null` | Anchor element ID or HTMLElement reference |
+| `positioning` | `'absolute' \| 'fixed'` | `'absolute'` | Positioning strategy relative to trigger or viewport |
+| `placement` | `'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'` | `'bottom-start'` | Anchor edge placement for the menu surface |
+| `alignment` | `'start' \| 'end' \| 'center'` | `'start'` | Alignment of the menu relative to the anchor |
+| `x-offset` | `number` | `0` | Horizontal pixel offset from the anchor |
+| `y-offset` | `number` | `4` | Vertical pixel offset from the anchor |
+| `quick` | `boolean` | `false` | Disables open/close transition animations |
+| `dense` | `boolean` | `false` | Applies compact vertical spacing and smaller icon sizing |
+| `stay-open-on-focusout` | `boolean` | `false` | Prevents menu from closing when focus leaves the surface |
+
+##### `<md-menu-item>` Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `headline` | `string` | `''` | Main item label text |
+| `supporting-text` | `string` | `''` | Secondary helper text below headline |
+| `trailing-supporting-text` | `string` | `''` | Trailing text (e.g. keyboard shortcut) |
+| `icon` | `string` | `''` | Leading Material Symbols icon name |
+| `trailing-icon` | `string` | `''` | Trailing Material Symbols icon name |
+| `disabled` | `boolean` | `false` | Disables interaction and dims item |
+| `selected` | `boolean` | `false` | Displays active selection state with checkmark |
+| `value` | `string` | `''` | Value associated with the menu item |
+| `href` | `string` | `''` | Renders item as an anchor link |
+| `target` | `string` | `''` | Anchor target attribute (e.g., `_blank`) |
+| `keep-open` | `boolean` | `false` | Prevents menu from closing when item is selected |
+| `dense` | `boolean` | `false` | Applies compact vertical sizing |
+
+##### Slots (`md-menu`)
+- `trigger`: Slotted trigger element (e.g., button or icon-button).
+- `(default)`: Menu items (`md-menu-item`) and dividers.
+
+##### Slots (`md-menu-item`)
+- `start` / `icon`: Leading icon or custom graphic.
+- `(default)`: Headline / label text.
+- `end` / `trailing`: Trailing content, shortcut text, or custom indicator.
+
+##### Events
+- `open`: Dispatched on `md-menu` when the menu opens.
+- `close`: Dispatched on `md-menu` when the menu closes.
+- `select`: Dispatched on `md-menu` and `md-menu-item` when an item is selected (`detail: { item: MdMenuItem, value: string }`).
+
+##### Code Example
+```html
+<!-- Basic Action Menu with Trigger Button -->
+<md-menu>
+  <md-button slot="trigger" variant="filled" icon="menu">Options</md-button>
+  <md-menu-item icon="content_cut" headline="Cut" trailing-supporting-text="Ctrl+X" value="cut"></md-menu-item>
+  <md-menu-item icon="content_copy" headline="Copy" trailing-supporting-text="Ctrl+C" value="copy"></md-menu-item>
+  <md-menu-item icon="content_paste" headline="Paste" trailing-supporting-text="Ctrl+V" value="paste"></md-menu-item>
+  <md-divider></md-divider>
+  <md-menu-item icon="delete" headline="Delete" trailing-supporting-text="Del" value="delete"></md-menu-item>
+</md-menu>
+
+<!-- Menu Anchored to External Trigger with Supporting Text -->
+<md-icon-button id="context-btn" icon="more_vert" aria-label="More options"></md-icon-button>
+<md-menu anchor="context-btn">
+  <md-menu-item headline="Single view" supporting-text="Standard layout" selected value="single"></md-menu-item>
+  <md-menu-item headline="Grid view" supporting-text="Compact card layout" value="grid"></md-menu-item>
+  <md-menu-item headline="Table view" supporting-text="Detailed table row layout" disabled value="table"></md-menu-item>
+</md-menu>
+```
+
+---
+
+#### List & List Item (`md-list`, `md-list-item`)
+
+- **Subpath**: `@francofantomius/material-components/list`
+- **Description**: Lists are continuous, vertical indexes of text and images, supporting 1-line, 2-line, and 3-line items with icons, avatars, and trailing text.
+
+##### `<md-list-item>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `headline` | `string` | `''` | Primary headline text |
+| `supporting-text` | `string` | `''` | Secondary supporting text description |
+| `trailing-supporting-text` | `string` | `''` | Metadata timestamp or trailing text |
+| `interactive` | `boolean` | `false` | Enables ripple hover and click response |
+| `disabled` | `boolean` | `false` | Disables item |
+| `href` | `string` | `''` | Renders item as hyperlink |
+
+##### `<md-list-item>` Slots
+- `start`: Leading icon, checkbox, or avatar.
+- `end`: Trailing icon, button, or switch.
+
+##### Code Example
+```html
+<md-list style="max-width: 400px; background: var(--md-sys-color-surface-container-low); border-radius: 12px;">
+  <md-list-item headline="Sarah Connor" supporting-text="Uploaded project roadmap" trailing-supporting-text="10:30 AM" interactive>
+    <md-icon slot="start" name="account_circle" size="32"></md-icon>
+  </md-list-item>
+  <md-divider inset></md-divider>
+  <md-list-item headline="Security Update" supporting-text="All packages upgraded to v2.0" trailing-supporting-text="Yesterday" interactive>
+    <md-icon slot="start" name="shield" size="32"></md-icon>
+  </md-list-item>
+</md-list>
+```
+
+---
+
+#### Table & Data Table (`md-table`)
+
+- **Subpath**: `@francofantomius/material-components/table`
+- **Description**: Data tables display information in a structured grid of rows and columns, featuring automatic sorting, pagination, zebra striping, loading states, and multi-row selection.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `bordered` | `boolean` | `false` | Adds outer container and cell grid borders |
+| `elevated` | `boolean` | `false` | Applies Material elevation shadow |
+| `striped` | `boolean` | `false` | Zebra stripes alternating rows |
+| `hoverable` | `boolean` | `true` | Highlights rows on mouse hover |
+| `dense` | `boolean` | `false` | Compact cell and row padding |
+| `sticky-header` | `boolean` | `false` | Pins table header during scroll |
+| `loading` | `boolean` | `false` | Displays indeterminate top progress bar |
+| `selectable` | `boolean` | `false` | Enables row selection checkboxes |
+| `columns` | `TableColumn[]` | `[]` | Data-driven column configuration array |
+| `rows` | `Record<string, any>[]` | `[]` | Data-driven row data array |
+| `paginated` | `boolean` | `false` | Renders built-in pagination footer |
+| `page` | `number` | `1` | Active page index (1-based) |
+| `page-size` | `number` | `10` | Items per page |
+| `total` | `number` | `0` | Total row count |
+
+##### Events
+- `sort-change`: Fired when column sorting is toggled (`detail: { column: string, direction: "asc" | "desc" | "none" }`).
+- `row-click`: Fired when a row is clicked (`detail: { row: any, index: number }`).
+- `selection-change`: Fired when row selection changes (`detail: { selectedRows: any[] }`).
+- `page-change`: Fired when page changes (`detail: { page: number, pageSize: number }`).
+
+##### Code Example
+```html
+<md-table
+  id="demo-table"
+  bordered
+  striped
+  hoverable
+  elevated
+  selectable
+  paginated
+  page-size="5"
+  style="width: 100%;"
+></md-table>
+
+<script>
+  const table = document.getElementById('demo-table');
+  table.columns = [
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'role', label: 'Role', sortable: true },
+    { key: 'status', label: 'Status' }
+  ];
+  table.rows = [
+    { name: 'Alice Smith', role: 'Architect', status: 'Active' },
+    { name: 'Bob Jones', role: 'Developer', status: 'Away' }
+  ];
+</script>
+```
+
+---
+
+#### Side Sheet (`md-side-sheet`)
+
+- **Subpath**: `@francofantomius/material-components/side-sheet`
+- **Description**: Side sheets display secondary content anchored to the side of the screen, supporting standard in-flow side panels and modal overlays with backdrop scrims.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Reflects open/closed state of the side sheet |
+| `type` | `'standard' \| 'modal'` | `'standard'` | Presentation mode: in-flow side panel or modal overlay |
+| `modal` | `boolean` | `false` | Enables modal overlay mode with backdrop scrim |
+| `side` | `'start' \| 'end' \| 'left' \| 'right'` | `'end'` | Screen side placement (start / left or end / right) |
+| `headline` | `string` | `''` | Header title text |
+| `subhead` | `string` | `''` | Header subtitle text |
+| `hide-close-button` | `boolean` | `false` | Hides the default close icon button in the header |
+| `divider` | `boolean` | `false` | Renders a divider line below the header |
+
+##### Slots
+- `header`: Full custom header area.
+- `headline`: Custom headline / title content.
+- `subhead`: Custom subtitle / subhead content.
+- `header-actions`: Actions next to the close button in the header.
+- `close-button`: Custom close button element.
+- `(default)`: Main scrollable body content.
+- `footer`: Bottom footer / actions section.
+- `actions`: Action buttons inside the footer.
+
+##### Events
+- `open`: Dispatched when the side sheet opens.
+- `close`: Dispatched when the side sheet closes.
+- `cancel`: Dispatched when dismissed via Escape key in modal mode.
+- `scrim-click`: Dispatched when the modal scrim backdrop is clicked.
+- `close-click`: Dispatched when the header close button is clicked.
+
+##### Code Example
+```html
+<!-- Modal Side Sheet -->
+<md-button variant="filled" id="open-sheet-btn">Open Filters</md-button>
+
+<md-side-sheet id="filters-sheet" type="modal" headline="Filters" subhead="Refine product listing">
+  <md-checkbox checked>In Stock</md-checkbox>
+  <md-checkbox>Free Shipping</md-checkbox>
+  <div slot="actions">
+    <md-button variant="text">Reset</md-button>
+    <md-button variant="filled">Apply</md-button>
+  </div>
+</md-side-sheet>
+
+<!-- Standard In-Flow Side Sheet -->
+<div style="display: flex; height: 400px;">
+  <div style="flex: 1; padding: 16px;">Main Page Content</div>
+  <md-side-sheet open headline="Details" divider>
+    <p>Contextual tool details and metadata.</p>
+  </md-side-sheet>
+</div>
+```
+
+---
+
+#### Bottom Sheet (`md-bottom-sheet`)
+
+- **Subpath**: `@francofantomius/material-components/bottom-sheet`
+- **Description**: Bottom sheets display supplementary content anchored to the bottom of the screen, supporting standard (docked) and modal (overlay with backdrop scrim) modes, drag handle gestures, touch swipe-to-dismiss, and customizable headers and footers.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Reflects open/closed state of the bottom sheet |
+| `type` | `'standard' \| 'modal'` | `'standard'` | Presentation mode: standard in-flow panel or modal overlay |
+| `modal` | `boolean` | `false` | Enables modal overlay mode with backdrop scrim |
+| `headline` | `string` | `''` | Header title text |
+| `subhead` | `string` | `''` | Header subtitle text |
+| `hide-drag-handle` | `boolean` | `false` | Hides the top drag handle bar |
+| `hide-close-button` | `boolean` | `false` | Hides the default close icon button in the header |
+| `divider` | `boolean` | `false` | Renders a divider line below the header |
+| `fullscreen` | `boolean` | `false` | Expands bottom sheet to full viewport height |
+
+##### Slots
+- `drag-handle`: Custom drag handle element.
+- `header`: Full custom header area.
+- `headline`: Custom headline / title content.
+- `subhead`: Custom subtitle / subhead content.
+- `header-actions`: Actions next to the close button in the header.
+- `close-button`: Custom close button element.
+- `(default)`: Main scrollable body content.
+- `footer`: Bottom footer / actions section.
+- `actions`: Action buttons inside the footer.
+
+##### Events
+- `open`: Dispatched when the bottom sheet opens.
+- `close`: Dispatched when the bottom sheet closes.
+- `cancel`: Dispatched when dismissed via Escape key in modal mode.
+- `scrim-click`: Dispatched when the modal scrim backdrop is clicked.
+- `close-click`: Dispatched when the header close button is clicked.
+- `drag-start`: Dispatched when drag gesture begins.
+- `drag-end`: Dispatched when drag gesture ends.
+- `drag-dismiss`: Dispatched when dismissed via downward drag gesture.
+
+##### Code Example
+```html
+<!-- Modal Bottom Sheet with Drag Dismissal -->
+<md-button variant="filled" id="open-sheet-btn">Open Bottom Sheet</md-button>
+
+<md-bottom-sheet id="demo-bottom-sheet" type="modal" headline="Share" subhead="Select a sharing option">
+  <div style="display: flex; gap: 16px; padding: 12px 0;">
+    <md-icon-button icon="link" aria-label="Copy link"></md-icon-button>
+    <md-icon-button icon="mail" aria-label="Email"></md-icon-button>
+    <md-icon-button icon="chat" aria-label="Messages"></md-icon-button>
+  </div>
+  <div slot="actions">
+    <md-button variant="text">Cancel</md-button>
+  </div>
+</md-bottom-sheet>
+
+<!-- Standard Docked Bottom Sheet -->
+<md-bottom-sheet open headline="Now Playing" subhead="Song queue" divider>
+  <p>Track 1: Ambient Horizon (3:42)</p>
+</md-bottom-sheet>
+```
+
+---
+
+#### Carousel (`md-carousel`, `md-carousel-item`)
+
+- **Subpath**: `@francofantomius/material-components/carousel`
+- **Description**: Carousels present an interactive scrollable collection of items with support for multi-browse, hero, and full-width layouts, smooth scrolling, next/prev navigation buttons, swipe/drag gestures, and pagination indicators.
+
+##### Properties & Attributes (`<md-carousel>`)
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `layout` | `'multi-browse' \| 'hero' \| 'full-width' \| 'uncontained'` | `'multi-browse'` | Layout arrangement and sizing for carousel items |
+| `active-index` | `number` | `0` | 0-based index of the currently active item |
+| `hide-controls` | `boolean` | `false` | Hides next and previous navigation arrow buttons |
+| `hide-indicators` | `boolean` | `false` | Hides bottom pagination indicator dots |
+| `loop` | `boolean` | `false` | Enables continuous infinite wrap-around navigation |
+| `autoplay` | `boolean` | `false` | Automatically advances slides periodically |
+| `autoplay-interval` | `number` | `5000` | Autoplay transition interval in milliseconds |
+| `item-spacing` | `string \| number` | `'8px'` | Gap between carousel items |
+| `item-width` | `string` | `''` | Custom width applied to each item |
+| `item-height` | `string` | `''` | Custom height applied to each item |
+
+##### Properties & Attributes (`<md-carousel-item>`)
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `src` | `string` | `''` | Image source URL for the carousel item media |
+| `alt` | `string` | `''` | Alt text for image media |
+| `headline` | `string` | `''` | Title or headline overlay text |
+| `subhead` | `string` | `''` | Subtitle or description overlay text |
+| `href` | `string` | `''` | Optional navigation link URL |
+| `target` | `string` | `''` | Link target when href is set |
+| `interactive` | `boolean` | `false` | Enables ripple and hover interactive state |
+| `disabled` | `boolean` | `false` | Disables item interactions |
+| `snap-align` | `'start' \| 'center' \| 'end'` | `'start'` | Scroll snap alignment point |
+
+##### Methods (`<md-carousel>`)
+- `next()`: Scrolls to the next slide in the carousel.
+- `previous()`: Scrolls to the previous slide in the carousel.
+- `scrollToIndex(index: number, smooth: boolean = true)`: Smoothly scrolls to a specific item index.
+
+##### Events
+- `change`: Fired when the active slide changes (`detail: { activeIndex: number, item: MdCarouselItem }`).
+- `carousel-item-click`: Fired when an item is clicked (`detail: { item: MdCarouselItem }`).
+
+##### Slots (`<md-carousel>`)
+- `(default)`: Slot for `<md-carousel-item>` elements.
+- `prev-button`: Custom previous navigation button.
+- `next-button`: Custom next navigation button.
+
+##### Slots (`<md-carousel-item>`)
+- `(default)`: Custom card/slide body content.
+- `media`: Custom media element (image, video).
+- `headline`: Custom headline text element.
+- `subhead`: Custom subhead text element.
+
+##### Code Examples
+
+```html
+<!-- Multi-Browse Layout (Default) -->
+<md-carousel>
+  <md-carousel-item
+    src="https://images.unsplash.com/photo-1579546929518-9e396f3cc809?w=600&auto=format&fit=crop&q=80"
+    headline="Colorful Gradients"
+    subhead="Modern vibrant colors"
+  ></md-carousel-item>
+  <md-carousel-item
+    src="https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=600&auto=format&fit=crop&q=80"
+    headline="Abstract Waves"
+    subhead="Smooth fluid motion"
+  ></md-carousel-item>
+  <md-carousel-item
+    src="https://images.unsplash.com/photo-1550684848-fac1c5b4e853?w=600&auto=format&fit=crop&q=80"
+    headline="Dark Aesthetics"
+    subhead="Geometric lighting"
+  ></md-carousel-item>
+</md-carousel>
+
+<!-- Hero Layout with Loop -->
+<md-carousel layout="hero" loop>
+  <md-carousel-item
+    src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=800&auto=format&fit=crop&q=80"
+    headline="Mountain Exploration"
+    subhead="Scenic landscapes and trails"
+  ></md-carousel-item>
+  <md-carousel-item
+    src="https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=800&auto=format&fit=crop&q=80"
+    headline="Forest Pathways"
+    subhead="Lush greenery and walks"
+  ></md-carousel-item>
+</md-carousel>
+
+<!-- Full-Width Layout with Autoplay -->
+<md-carousel layout="full-width" autoplay autoplay-interval="4000">
+  <md-carousel-item
+    src="https://images.unsplash.com/photo-1518770660439-4636190af475?w=1000&auto=format&fit=crop&q=80"
+    headline="Circuit Technology"
+    subhead="Microchip architecture"
+  ></md-carousel-item>
+  <md-carousel-item
+    src="https://images.unsplash.com/photo-1526374965328-7f61d4dc18c5?w=1000&auto=format&fit=crop&q=80"
+    headline="Data Matrix"
+    subhead="Cybersecurity networks"
+  ></md-carousel-item>
+</md-carousel>
+```
+
+---
+
+### Communication & Feedback
+
+#### Badge (`md-badge`)
+
+- **Subpath**: `@francofantomius/material-components/badge`
+- **Description**: Badges show notification counts, alert statuses, or small indicators anchored to icon buttons or list elements.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `string` | `''` | Badge numeric or text value |
+| `dot` | `boolean` | `false` | Renders a small 6px dot without text |
+
+##### Code Example
+```html
+<div style="display: flex; gap: 24px; align-items: center;">
+  <md-badge value="4">
+    <md-icon-button icon="mail" aria-label="Mail"></md-icon-button>
+  </md-badge>
+  <md-badge value="99+">
+    <md-icon-button icon="notifications" aria-label="Notifications"></md-icon-button>
+  </md-badge>
+  <md-badge dot>
+    <md-icon-button icon="chat" aria-label="Messages"></md-icon-button>
+  </md-badge>
+</div>
+```
+
+---
+
+#### Progress Indicators (`md-progress`)
+
+- **Subpath**: `@francofantomius/material-components/progress`
+- **Description**: Progress indicators express an unspecified wait time or display the length of a process in linear and circular formats, featuring Material 3 wavy lines for determinate values.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `type` | `'linear' \| 'circular'` | `'linear'` | Indicator shape |
+| `value` | `number \| null` | `null` | Determinate value between 0 and 1. `null` indicates indeterminate. |
+| `max` | `number` | `1` | Maximum progress value |
+| `buffer` | `number` | `1` | Buffer value for linear progress indicator |
+| `wavy` | `boolean` | `true` | Enables Material 3 wavy line for determinate values |
+
+##### Code Example
+```html
+<!-- Linear Progress with Wavy Line -->
+<md-progress type="linear" value="0.7"></md-progress>
+<md-progress type="linear"></md-progress>
+
+<!-- Circular Progress with Wavy Line -->
+<md-progress type="circular" value="0.65"></md-progress>
+<md-progress type="circular"></md-progress>
+```
+
+---
+
+#### Loading Indicator (`md-loading-indicator`)
+
+- **Subpath**: `@francofantomius/material-components/loading-indicator`
+- **Description**: Loading indicators express an unspecified wait time for short operations with Material Design 3 Expressive animated morphing shapes and optional contained containers.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Visual size of the indicator |
+| `contained` | `boolean` | `false` | Encloses indicator within a contained surface container |
+| `shape` | `'morph' \| 'square' \| 'circle' \| 'clover' \| 'star'` | `'morph'` | Shape animation style |
+| `paused` | `boolean` | `false` | Pauses shape animation |
+| `label` | `string` | `'Loading'` | Accessible label for screen readers |
+
+##### Code Example
+```html
+<!-- Standard morphing loading indicators -->
+<div style="display: flex; gap: 24px; align-items: center;">
+  <md-loading-indicator size="small"></md-loading-indicator>
+  <md-loading-indicator size="medium"></md-loading-indicator>
+  <md-loading-indicator size="large"></md-loading-indicator>
+</div>
+
+<!-- Contained loading indicators -->
+<div style="display: flex; gap: 24px; align-items: center; margin-top: 16px;">
+  <md-loading-indicator contained size="small"></md-loading-indicator>
+  <md-loading-indicator contained size="medium"></md-loading-indicator>
+  <md-loading-indicator contained size="large"></md-loading-indicator>
+</div>
+```
+
+---
+
+#### Snackbar (`md-snackbar`)
+
+- **Subpath**: `@francofantomius/material-components/snackbar`
+- **Description**: Snackbars provide brief feedback about an operation through an elevated message toast at the bottom of the viewport.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Visibility state |
+| `message` | `string` | `''` | Message toast content |
+| `action-text` | `string` | `''` | Action button label |
+| `closeable` | `boolean` | `false` | Renders a close icon button |
+| `timeout-ms` | `number` | `4000` | Auto-dismiss timeout in milliseconds (0 for indefinite) |
+
+##### Events
+- `open`: Fired when snackbar appears.
+- `close`: Fired when snackbar dismisses.
+- `action`: Fired when user clicks action button.
+
+##### Code Example
+```html
+<md-button variant="tonal" id="show-toast-btn">Show Snackbar</md-button>
+<md-snackbar id="demo-toast" message="Email message moved to Trash." action-text="Undo" closeable></md-snackbar>
+
+<script>
+  document.getElementById('show-toast-btn').addEventListener('click', () => {
+    document.getElementById('demo-toast').open = true;
+  });
+</script>
+```
+
+---
+
+#### Tooltip (`md-tooltip`)
+
+- **Subpath**: `@francofantomius/material-components/tooltip`
+- **Description**: Tooltips display informative text when users hover over, focus on, or tap an element. Plain tooltips describe an element briefly, while rich tooltips provide detailed context, headlines, and action buttons.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Visibility state of the tooltip |
+| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Preferred placement relative to anchor target |
+| `rich` | `boolean` | `false` | Enables rich tooltip styling with headline, supporting text, and actions |
+| `for` | `string` | `''` | ID of the target anchor element |
+| `value` | `string` | `''` | Plain tooltip label or rich tooltip supporting text |
+| `headline` | `string` | `''` | Headline / subhead for rich tooltips |
+| `action-text` | `string` | `''` | Action button label for rich tooltips |
+| `show-delay` | `number` | `500` | Delay in milliseconds before showing tooltip on hover |
+| `hide-delay` | `number` | `150` | Delay in milliseconds before hiding tooltip after pointer leaves |
+| `persistent` | `boolean` | `false` | Keeps rich tooltip open until dismissed explicitly |
+| `has-caret` | `boolean` | `false` | Renders a directional pointing caret |
+| `disabled` | `boolean` | `false` | Disables tooltip triggering |
+
+##### Events
+- `open`: Dispatched when tooltip becomes visible (`{ target: MdTooltip }`).
+- `close`: Dispatched when tooltip is dismissed (`{ target: MdTooltip }`).
+- `action`: Dispatched when rich tooltip action button is clicked (`{ target: MdTooltip }`).
+
+##### Slots
+- `(default)`: Plain tooltip text or rich tooltip supporting content.
+- `headline`: Custom headline or rich header element.
+- `actions`: Custom action buttons for rich tooltips.
+- `anchor`: Slotted anchor element (optional).
+
+##### Code Example
+```html
+<!-- Plain Tooltips on Icon Buttons -->
+<div style="display: flex; gap: 24px; align-items: center;">
+  <div>
+    <md-icon-button id="fav-btn" icon="favorite" aria-label="Favorite"></md-icon-button>
+    <md-tooltip for="fav-btn" value="Add to favorites" position="bottom"></md-tooltip>
+  </div>
+
+  <div>
+    <md-icon-button id="share-btn" icon="share" aria-label="Share"></md-icon-button>
+    <md-tooltip for="share-btn" value="Share link" position="top"></md-tooltip>
+  </div>
+</div>
+
+<!-- Rich Tooltip with Headline and Action -->
+<div>
+  <md-button id="help-btn" variant="tonal" icon="help_outline">Permissions</md-button>
+  <md-tooltip
+    for="help-btn"
+    rich
+    has-caret
+    position="bottom"
+    headline="Access Permissions"
+    value="Members with View permissions can read and comment on documents without editing."
+    action-text="Learn more"
+  ></md-tooltip>
+</div>
+```
+
+---
+
+### Navigation
+
+#### Navigation Bar (`md-navigation-bar`, `md-navigation-bar-item`)
+
+- **Subpath**: `@francofantomius/material-components/navigation-bar`
+- **Description**: Navigation bars let users switch between 3 to 5 top-level destinations at the bottom of the screen with active indicator pills, badge notifications, and label visibility modes (`alwaysShow`, `selectedShow`, `hidden`).
+
+##### `<md-navigation-bar>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `active-index` | `number` | `0` | Zero-based index of the currently active destination |
+| `value` | `string` | `''` | Value of the currently active destination |
+| `label-mode` | `'alwaysShow' \| 'selectedShow' \| 'hidden'` | `'alwaysShow'` | Controls label visibility across destination items |
+| `hide-inactive-labels` | `boolean` | `false` | Hides labels on inactive items (`selectedShow` behavior) |
+| `disabled` | `boolean` | `false` | Disables interaction on all items |
+
+##### `<md-navigation-bar-item>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `icon` | `string` | `''` | Material Symbols destination icon |
+| `active-icon` | `string` | `''` | Optional icon displayed when item is active |
+| `label` | `string` | `''` | Destination title text |
+| `badge` | `string` | `''` | Numeric, text, or `"dot"` badge indicator |
+| `active` | `boolean` | `false` | Highlights item with active indicator pill |
+| `disabled` | `boolean` | `false` | Disables item interactions |
+| `value` | `string` | `''` | Value identifier for destination |
+| `href` | `string` | `''` | Optional navigation hyperlink |
+| `label-mode` | `'alwaysShow' \| 'selectedShow' \| 'hidden'` | `'alwaysShow'` | Per-item label visibility mode |
+
+##### Events
+- `change`: Dispatched on `<md-navigation-bar>` when the active destination changes (`{ activeIndex, selectedIndex, index, value, item }`).
+- `item-click`: Dispatched on `<md-navigation-bar-item>` when clicked (`{ item, value, label, active }`).
+
+##### Code Example
+```html
+<md-navigation-bar active-index="0" id="bottom-nav">
+  <md-navigation-bar-item icon="home" label="Home" value="home"></md-navigation-bar-item>
+  <md-navigation-bar-item icon="explore" label="Explore" value="explore"></md-navigation-bar-item>
+  <md-navigation-bar-item icon="mail" label="Mail" badge="12" value="mail"></md-navigation-bar-item>
+  <md-navigation-bar-item icon="chat" label="Chat" badge="dot" value="chat"></md-navigation-bar-item>
+  <md-navigation-bar-item icon="person" label="Profile" value="profile"></md-navigation-bar-item>
+</md-navigation-bar>
+```
+
+---
+
+#### Navigation Drawer (`md-navigation-drawer`, `md-navigation-drawer-item`)
+
+- **Subpath**: `@francofantomius/material-components/navigation-drawer`
+- **Description**: Navigation drawers provide side navigation access to top-level destinations and app features in standard or modal configurations.
+
+##### `<md-navigation-drawer>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Reflects open/closed state |
+| `type` | `'modal' \| 'standard' \| 'responsive'` | `'modal'` | Drawer presentation mode |
+| `responsive` | `boolean` | `false` | Enables responsive mode (docked on desktop >960px, modal on mobile) |
+| `pivot` | `'left' \| 'right'` | `'left'` | Anchoring screen edge |
+| `headline` | `string` | `''` | Drawer title header |
+
+##### `<md-navigation-drawer-item>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `icon` | `string` | `''` | Material Symbols destination icon |
+| `label` | `string` | `''` | Destination title |
+| `badge` | `string` | `''` | Trailing counter or status badge |
+| `active` | `boolean` | `false` | Highlights item with active pill indicator |
+| `disabled` | `boolean` | `false` | Disables item |
+| `href` | `string` | `''` | Optional navigation link |
+
+##### Events
+- `open`: Dispatched when drawer opens.
+- `close`: Dispatched when drawer closes.
+- `item-click`: Dispatched when a drawer item is selected.
+
+##### Code Example
+```html
+<md-navigation-drawer id="demo-drawer" headline="Mail Destinations">
+  <md-navigation-drawer-item icon="inbox" label="Inbox" badge="12" active></md-navigation-drawer-item>
+  <md-navigation-drawer-item icon="star" label="Starred"></md-navigation-drawer-item>
+  <md-navigation-drawer-item icon="send" label="Sent"></md-navigation-drawer-item>
+  <md-navigation-drawer-item icon="drafts" label="Drafts" badge="2"></md-navigation-drawer-item>
+  <div slot="footer">
+    <md-navigation-drawer-item icon="settings" label="Settings"></md-navigation-drawer-item>
+  </div>
+</md-navigation-drawer>
+```
+
+---
+
+#### Navigation Rail (`md-navigation-rail`, `md-navigation-rail-item`)
+
+- **Subpath**: `@francofantomius/material-components/navigation-rail`
+- **Description**: Navigation rails provide side navigation access to primary destinations in apps on mid-sized to large screens (tablets, desktops), supporting leading menu/header/fab slots, active indicator pill destinations, badges, and top/center/bottom alignment.
+
+##### `<md-navigation-rail>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `alignment` | `'top' \| 'center' \| 'bottom'` | `'top'` | Vertical alignment of destination items |
+| `hide-labels` | `boolean` | `false` | Hides all destination text labels |
+| `active-index` | `number` | `-1` | Zero-based index of the currently active destination |
+
+##### `<md-navigation-rail-item>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `icon` | `string` | `''` | Material Symbols destination icon |
+| `active-icon` | `string` | `''` | Material Symbols icon displayed when active |
+| `label` | `string` | `''` | Destination title |
+| `badge` | `string` | `''` | Numeric or text badge indicator |
+| `badge-dot` | `boolean` | `false` | Small circular status dot badge |
+| `active` | `boolean` | `false` | Highlights destination with active indicator pill |
+| `disabled` | `boolean` | `false` | Disables destination interaction |
+| `hide-label` | `boolean` | `false` | Hides text label for this item |
+| `href` | `string` | `''` | Optional navigation hyperlink |
+| `value` | `string` | `''` | Custom item value identifier |
+
+##### Slots
+- `header`: Top header section (logo, title).
+- `menu`: Top menu button slot.
+- `fab`: Slotted Floating Action Button (FAB).
+- `(default)`: Main destination items (`md-navigation-rail-item`).
+- `footer`: Bottom actions or user profile slot.
+
+##### Events
+- `change`: Dispatched when active destination in the rail changes (`detail: { activeIndex: number, item: MdNavigationRailItem, value: string }`).
+- `item-click`: Dispatched when an individual rail item is clicked (`detail: { label: string, icon: string, active: boolean, value: string, item: MdNavigationRailItem }`).
+
+##### Code Example
+```html
+<md-navigation-rail alignment="top">
+  <md-icon-button slot="menu" icon="menu" aria-label="Menu"></md-icon-button>
+  <md-fab slot="fab" size="small" icon="edit" aria-label="Compose"></md-fab>
+
+  <md-navigation-rail-item icon="inbox" label="Inbox" badge="3" active></md-navigation-rail-item>
+  <md-navigation-rail-item icon="star" label="Starred"></md-navigation-rail-item>
+  <md-navigation-rail-item icon="send" label="Sent"></md-navigation-rail-item>
+  <md-navigation-rail-item icon="chat" label="Chat" badge-dot></md-navigation-rail-item>
+
+  <div slot="footer">
+    <md-icon-button icon="settings" aria-label="Settings"></md-icon-button>
+  </div>
+</md-navigation-rail>
+```
+
+---
+
+#### Top App Bar (`md-top-app-bar`)
+
+- **Subpath**: `@francofantomius/material-components/top-app-bar`
+- **Description**: Top app bars display branding, titles, navigation controls, and actions at the top of a screen across small, center-aligned, medium, and large variants.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'center-aligned' \| 'small' \| 'medium' \| 'large'` | `'center-aligned'` | Layout format of the top bar |
+| `headline` | `string` | `''` | Main title headline |
+| `subtitle` | `string` | `''` | Secondary supporting text |
+| `elevated` | `boolean` | `false` | Applies elevation shadow and surface container color |
+| `fixed` | `boolean` | `false` | Pins app bar to top of viewport (sticky) |
+
+##### Slots
+- `navigation`: Leading icon button (e.g. Hamburger menu or back arrow).
+- `actions`: Trailing action buttons and overflow menu triggers.
+
+##### Code Example
+```html
+<md-top-app-bar variant="small" headline="Inbox" subtitle="3 unread messages">
+  <md-icon-button slot="navigation" icon="menu" aria-label="Menu"></md-icon-button>
+  <md-icon-button slot="actions" icon="search" aria-label="Search"></md-icon-button>
+  <md-icon-button slot="actions" icon="more_vert" aria-label="More"></md-icon-button>
+</md-top-app-bar>
+
+<md-top-app-bar variant="center-aligned" headline="Settings" elevated>
+  <md-icon-button slot="navigation" icon="arrow_back" aria-label="Back"></md-icon-button>
+  <md-icon-button slot="actions" icon="help" aria-label="Help"></md-icon-button>
+</md-top-app-bar>
+```
+
+---
+
+#### Tabs (`md-tabs`, `md-tab`)
+
+- **Subpath**: `@francofantomius/material-components/tabs`
+- **Description**: Tabs organize content across different screens, data sets, and other interactions with smooth sliding active indicator bars.
+
+##### `<md-tabs>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `active-index` | `number` | `0` | 0-based index of currently active tab |
+
+##### `<md-tab>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `label` | `string` | `''` | Tab text title |
+| `icon` | `string` | `''` | Material Symbols icon |
+| `active` | `boolean` | `false` | Active selection state |
+| `disabled` | `boolean` | `false` | Disables tab selection |
+
+##### Events
+- `change`: Fired when active tab selection changes (`detail: { activeIndex: number }`).
+
+##### Code Example
+```html
+<md-tabs active-index="0" id="demo-tab-bar">
+  <md-tab icon="home" label="Home"></md-tab>
+  <md-tab icon="explore" label="Explore"></md-tab>
+  <md-tab icon="person" label="Profile"></md-tab>
+  <md-tab icon="settings" label="Settings"></md-tab>
+</md-tabs>
+```
+
+---
+
+#### App Drawer (`md-app-drawer`, `md-app-drawer-item`)
+
+- **Subpath**: `@francofantomius/material-components/app-drawer`
+- **Description**: App drawers provide a popover grid menu of applications, shortcuts, and services, typically positioned next to the account avatar or in top app bars. Includes drag-and-drop & keyboard reordering.
+
+##### `<md-app-drawer>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Controls whether app drawer popover is open |
+| `headline` | `string` | `''` | Optional header title displayed at the top |
+| `icon` | `string` | `'apps'` | Material icon name for default trigger button |
+| `aria-label` | `string` | `'App launcher'` | Accessible label for trigger button & popover |
+| `trigger` | `boolean` | `true` | Whether to render built-in trigger icon button |
+| `alignment` | `'start' \| 'end'` | `'end'` | Horizontal alignment of popover relative to trigger |
+| `pivot` | `'left' \| 'right'` | `'right'` | Anchor pivot edge |
+| `modal` | `boolean` | `false` | Shows dimming modal backdrop when open |
+| `fullscreen` | `boolean` | `false` | Forces full-screen display (automatic on mobile viewports) |
+| `columns` | `number` | `3` | Number of columns in app grid |
+| `reorderable` | `boolean` | `true` | Enables drag-and-drop and keyboard reordering of apps |
+| `editable` | `boolean` | `true` | Shows edit icon button on top-right to toggle reordering |
+| `editing` | `boolean` | `false` | Controls whether app drawer is in reordering/editing mode |
+| `storage-key` | `string` | `''` | Custom localStorage key for persisting app order |
+| `disable-storage` | `boolean` | `false` | Disables automatic saving and loading of app order |
+
+##### `<md-app-drawer-item>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `label` | `string` | `''` | Primary label for app |
+| `headline` | `string` | `''` | Alias for label |
+| `icon` | `string` | `''` | Material Symbols icon name |
+| `src` | `string` | `''` | Optional image or logo URL |
+| `badge` | `string` | `''` | Optional counter or notification badge |
+| `href` | `string` | `''` | Navigation URL |
+| `target` | `string` | `''` | Link target attribute |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+| `active` | `boolean` | `false` | Active / highlighted state |
+
+##### Slots
+- `trigger`: Custom trigger element replacing default icon button.
+- `back-button`: Custom back/close button element for full-screen/mobile view.
+- `header`: Header content above app grid.
+- `edit-button`: Custom edit button replacing header reorder toggle button.
+- `reset-button`: Custom reset button restoring default order.
+- `(default)`: Container for `md-app-drawer-item` elements.
+- `footer`: Footer content below app grid.
+
+##### Events
+- `open`: Dispatched when app drawer opens.
+- `close`: Dispatched when app drawer closes.
+- `item-click`: Dispatched when an app item is selected.
+- `reorder`: Dispatched when apps are reordered.
+- `reset`: Dispatched when app order is reset to default.
+- `edit-toggle`: Dispatched when reordering edit mode is toggled.
+
+##### Code Example
+```html
+<md-app-drawer id="demo-app-drawer" headline="Apps">
+  <md-app-drawer-item icon="mail" label="Mail" badge="5"></md-app-drawer-item>
+  <md-app-drawer-item icon="calendar_today" label="Calendar"></md-app-drawer-item>
+  <md-app-drawer-item icon="folder" label="Drive"></md-app-drawer-item>
+  <md-app-drawer-item icon="chat" label="Chat"></md-app-drawer-item>
+  <md-app-drawer-item icon="videocam" label="Meet"></md-app-drawer-item>
+  <md-app-drawer-item icon="contacts" label="Contacts"></md-app-drawer-item>
+  <div slot="footer" style="padding: 4px 0; display: flex; justify-content: center;">
+    <md-button variant="outlined">More apps</md-button>
+  </div>
+</md-app-drawer>
+```
+
+---
+
+#### Account Menu (`md-account-menu`, `md-account-item`)
+
+- **Subpath**: `@francofantomius/material-components/account-menu`
+- **Description**: Profile menu and account switcher that displays user credentials, role details, security status, storage quotas, and multiple account management.
+
+##### `<md-account-menu>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Controls whether account menu popover is open |
+| `name` | `string` | `'Franco Fantomius'` | Display name of active user |
+| `email` | `string` | `'franco.fantomius@example.com'` | Primary email address |
+| `avatar` | `string` | `''` | URL to avatar image |
+| `initials` | `string` | `''` | Fallback initials if avatar is not set |
+| `headline` | `string` | `'Account'` | Header text |
+| `manage-text` | `string` | `'Manage your Account'` | Label for main account management button |
+| `manage-url` | `string` | `''` | Navigation URL for account management |
+| `organization` | `string` | `'Material Components'` | Company or organization name |
+| `role-title` | `string` | `'Lead Architect'` | User role or job title |
+| `status` | `string` | `'Active'` | Account status badge |
+| `storage-used` | `string` | `'10.4 GB'` | Storage amount currently used |
+| `storage-total` | `string` | `'15 GB'` | Total storage capacity |
+| `storage-progress` | `number` | `0.69` | Storage usage ratio between 0 and 1 |
+| `security-status` | `string` | `'Protected'` | Security and 2FA status |
+| `show-tabs` | `boolean` | `true` | Renders Overview, Security, Storage, and Accounts tabs |
+| `alignment` | `'start' \| 'end'` | `'end'` | Horizontal alignment of popover relative to trigger |
+| `pivot` | `'left' \| 'right'` | `'right'` | Anchor pivot edge |
+| `modal` | `boolean` | `false` | Shows dimming modal backdrop when open |
+| `fullscreen` | `boolean` | `false` | Forces full-screen display (automatic on mobile viewports) |
+
+##### `<md-account-item>` Properties
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `string` | `''` | Account profile name |
+| `email` | `string` | `''` | Account email address |
+| `avatar` | `string` | `''` | Avatar image URL |
+| `initials` | `string` | `''` | Avatar initials |
+| `icon` | `string` | `''` | Icon name |
+| `active` | `boolean` | `false` | Marks account as currently active |
+| `action` | `boolean` | `false` | Action item mode (e.g. Add another account) |
+| `disabled` | `boolean` | `false` | Disables interaction |
+
+##### Slots
+- `trigger`: Custom trigger element replacing default avatar button.
+- `back-button`: Custom back/close button element for full-screen/mobile view.
+- `header`: Custom header content.
+- `overview`: Custom content for Overview tab.
+- `security`: Custom content for Security tab.
+- `storage`: Custom content for Storage tab.
+- `accounts`: Container for `md-account-item` instances.
+- `footer`: Custom footer content (e.g. Sign out action).
+
+##### Events
+- `open`: Dispatched when account menu opens.
+- `close`: Dispatched when account menu closes.
+- `tab-change`: Dispatched when user switches tabs (`detail: { tab }`).
+- `account-select`: Dispatched when an account profile is chosen.
+- `manage-click`: Dispatched when Manage Account button is clicked.
+- `sign-out`: Dispatched when Sign out button is clicked.
+- `edit-avatar`: Dispatched when avatar photo edit button is clicked.
+
+##### Code Example
+```html
+<md-account-menu
+  id="demo-account-menu"
+  name="Franco Fantomius"
+  email="franco.fantomius@example.com"
+  initials="F"
+  role-title="Lead Architect"
+  organization="Material Components Team"
+  storage-used="10.4 GB"
+  storage-total="15 GB"
+  storage-progress="0.69"
+>
+  <md-account-item
+    slot="accounts"
+    name="Franco Fantomius"
+    email="franco.fantomius@example.com"
+    initials="F"
+    active
+  ></md-account-item>
+  <md-account-item
+    slot="accounts"
+    name="Work Workspace"
+    email="franco.dev@work.corp"
+    initials="W"
+  ></md-account-item>
+  <md-account-item
+    slot="accounts"
+    name="Add another account"
+    icon="person_add"
+    action
+  ></md-account-item>
+</md-account-menu>
+```
+
+---
+
+### Media & Playback
+
+#### Player (`md-player`)
+
+- **Subpath**: `@francofantomius/material-components/player`
+- **Description**: Material Design 3 media player component supporting audio and video playback, responsive compact and large-screen layouts, artwork/posters, interactive progress scrubbing, always-visible volume controls, queue toggle, playback rates, and keyboard shortcuts.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `src` | `string` | `''` | Media source URL for audio or video playback |
+| `type` | `'audio' \| 'video'` | `'audio'` | Type of media to render |
+| `variant` | `'elevated' \| 'filled' \| 'outlined' \| 'compact' \| 'full'` | `'elevated'` | Surface container style or layout variant |
+| `track-title` | `string` | `''` | Title of current track or video |
+| `artist` | `string` | `''` | Artist or author name |
+| `album` | `string` | `''` | Album or series name |
+| `poster` | `string` | `''` | Artwork / poster image URL |
+| `currentTime` | `number` | `0` | Current playback position in seconds |
+| `duration` | `number` | `0` | Total media duration in seconds |
+| `volume` | `number` | `1` | Audio volume level (0.0 to 1.0) |
+| `muted` | `boolean` | `false` | Mutes media audio output |
+| `playback-rate` | `number` | `1` | Speed multiplier (0.5x to 2x) |
+| `paused` | `boolean` | `true` | Playback pause state |
+| `loop` | `boolean` | `false` | Repeats track when finished |
+| `autoplay` | `boolean` | `false` | Automatically begins playback on load |
+| `compact` | `boolean` | `false` | Forces minimal single-row bar layout |
+| `show-skip` | `boolean` | `true` | Shows previous and next track buttons |
+| `show-seek` | `boolean` | `true` | Shows rewind and fast-forward 10s buttons |
+| `show-volume` | `boolean` | `true` | Shows always-visible volume button and slider |
+| `show-playback-rate` | `boolean` | `true` | Shows playback rate cycle button |
+| `show-queue` | `boolean` | `true` | Shows music queue toggle button |
+| `seek-step` | `number` | `10` | Seconds to skip with rewind/forward controls |
+
+##### Slots
+- `media`: Custom native `<audio>` or `<video>` element.
+- `artwork`: Custom album artwork or video thumbnail element.
+- `title`: Custom title header content.
+- `artist`: Custom artist or subtitle content.
+- `actions`: Custom action buttons (like, share, playlist).
+- `(default)`: Additional content below controls (lyrics, playlist).
+
+##### Events
+- `play`: Fired when playback begins.
+- `pause`: Fired when playback is paused.
+- `timeupdate`: Fired periodically as time updates (`detail: { currentTime: number, duration: number, progress: number }`).
+- `seeked`: Fired after seeking (`detail: { currentTime: number }`).
+- `volumechange`: Fired when volume or mute changes (`detail: { volume: number, muted: boolean }`).
+- `ratechange`: Fired when playback rate is modified (`detail: { playbackRate: number }`).
+- `queue`: Fired when queue button is toggled (`detail: { open: boolean }`).
+- `previous`: Fired on previous button click.
+- `next`: Fired on next button click.
+- `ended`: Fired when media playback ends.
+- `fullscreenchange`: Fired when fullscreen state changes in video mode (`detail: { fullscreen: boolean }`).
+
+##### JavaScript API Methods
+- `play()`: Begins or resumes playback.
+- `pause()`: Pauses active playback.
+- `togglePlay()`: Toggles between play and pause.
+- `seek(timeInSeconds)`: Jumps directly to timestamp.
+- `seekBy(deltaSeconds)`: Relative seek forward/backward.
+- `setVolume(level)`: Sets volume (0.0 to 1.0).
+- `toggleMute()`: Toggles audio mute state.
+- `toggleQueue()`: Toggles music queue state.
+- `cyclePlaybackRate()`: Cycles speed rates (0.5x, 0.75x, 1x, 1.25x, 1.5x, 2x).
+- `toggleFullscreen()`: Toggles fullscreen video mode.
+
+##### Code Example
+```html
+<!-- Full Audio Player -->
+<md-player
+  track-title="Midnight City Dreams"
+  artist="Synthetic Horizons"
+  album="Future Echoes (2026)"
+  poster="https://picsum.photos/seed/music/300/300"
+  duration="214"
+  current-time="45"
+></md-player>
+
+<!-- Compact Bar Player -->
+<md-player
+  compact
+  variant="outlined"
+  track-title="Episode 42: Modern Web Design"
+  artist="Tech Talk Daily"
+  poster="https://picsum.photos/seed/podcast/200/200"
+  duration="1820"
+></md-player>
+
+<!-- Video Player Mode -->
+<md-player
+  type="video"
+  src="https://example.com/sample.mp4"
+  track-title="Material Design 3 Interactive Experience"
+  poster="https://picsum.photos/seed/video/800/450"
+></md-player>
+```
+
+---
+
+### Utilities & Data
+
+#### Icon (`md-icon`)
+
+- **Subpath**: `@francofantomius/material-components/icon`
+- **Description**: Icons visually communicate meaning, actions, and status using Google Material Symbols variable font glyphs or custom slotted SVGs.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `string` | `''` | Material Symbols font glyph identifier |
+| `filled` | `boolean` | `false` | Enables filled variation in variable font |
+| `size` | `string` | `''` | Custom CSS font size (e.g. `32`, `2rem`) |
+
+##### Code Example
+```html
+<md-icon name="favorite"></md-icon>
+<md-icon name="favorite" filled style="color: var(--md-sys-color-error);"></md-icon>
+<md-icon name="settings" size="32"></md-icon>
+<md-icon name="rocket_launch" size="48" style="color: var(--md-sys-color-primary);"></md-icon>
+```
+
+---
+
+#### Code Block & Highlighter (`md-code`)
+
+- **Subpath**: `@francofantomius/material-components/code`
+- **Description**: Code component with syntax highlighting for popular languages, real-time multi-language linting diagnostics, line numbers, line highlighting, and one-click copy to clipboard.
+
+##### Properties & Attributes
+| Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `code` | `string` | `''` | Source code content string (falls back to slot/textContent) |
+| `language` / `lang` | `string` | `'plaintext'` | Syntax language: `javascript`, `typescript`, `html`, `css`, `json`, `python`, `bash`, `sql`, `yaml`, `markdown` |
+| `label` / `filename` | `string` | `''` | Header label or filename (e.g. `"button.ts"`, `"package.json"`) |
+| `lint` | `boolean` | `false` | Enables built-in real-time multi-language syntax linting |
+| `diagnostics` | `LintDiagnostic[]` | `[]` | Array of custom diagnostic issues to display (`{ line, column, message, severity, rule }`) |
+| `show-lint-summary` | `boolean` | `true` | Whether to show the collapsible lint issues summary footer bar |
+| `line-numbers` | `boolean` | `false` | Renders line numbers gutter |
+| `highlight-lines` | `string` | `''` | Comma-separated line numbers or ranges to highlight (e.g. `"1, 3-5, 8"`) |
+| `copyable` | `boolean` | `true` | Enables clipboard copying functionality |
+| `hide-copy-button` | `boolean` | `false` | Hides the copy button from the header |
+| `wrap-lines` | `boolean` | `false` | Wraps long lines instead of horizontal scrolling |
+| `max-height` | `string` | `''` | Maximum height of code scroll area (e.g. `"300px"`) |
+
+##### Slots
+- `(default)`: Source code text when `code` property is omitted.
+- `actions`: Additional action buttons placed in header bar.
+
+##### Events
+- `copy`: Fired when code is copied to clipboard (`detail: { code: string }`).
+- `lint-complete`: Fired after linting finishes (`detail: { diagnostics: LintDiagnostic[], isValid: boolean }`).
+
+##### CSS Variables
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `--md-code-bg` | `var(--md-sys-color-surface-container)` | Background color of code block |
+| `--md-code-header-bg` | `var(--md-sys-color-surface-container-high)` | Background color of header bar |
+| `--md-code-border` | `var(--md-sys-color-outline-variant)` | Border color of container |
+| `--md-code-color` | `var(--md-sys-color-on-surface)` | Default text color of code tokens |
+| `--md-code-gutter-color` | `var(--md-sys-color-outline)` | Text color of line numbers |
+| `--md-code-radius` | `var(--md-sys-shape-corner-medium, 12px)` | Corner border radius |
+| `--md-code-font-size` | `13.5px` | Font size of the code |
+| `--md-code-line-height` | `1.6` | Line height multiplier |
+
+##### Code Example
+```html
+<md-code
+  language="typescript"
+  label="src/index.ts"
+  line-numbers
+  highlight-lines="4, 7-9"
+>
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+@customElement('my-counter')
+export class MyCounter extends LitElement {
+  @property({ type: Number }) count = 0;
+
+  private increment() {
+    this.count += 1;
+  }
+
+  render() {
+    return html`<button @click=${this.increment}>Count: ${this.count}</button>`;
+  }
+}
+</md-code>
+
+<!-- Real-time Linting -->
+<md-code language="json" label="package.json" line-numbers lint>
+{
+  "name": "@francofantomius/material-components",
+  "version": "1.0.0"
+}
+</md-code>
+```
+