microui-wc 0.1.0

package/docs/component-schema.md

@@ -0,0 +1,231 @@
+# Component Schema Specification
+
+> **Version**: 1.0.0-draft  
+> **Status**: Planning Phase
+
+---
+
+## Overview
+
+microUI components are defined via **JSON schemas** that are compiled at definition-time into optimized render functions. This approach is AI-optimal because:
+
+1. **Structured**: Entirely JSON-serializable, easy to generate/modify
+2. **Introspectable**: Full metadata available at runtime
+3. **Validated**: Schema errors caught at definition-time, not render-time
+4. **Zero-cost**: Compilation eliminates runtime overhead
+
+---
+
+## Schema Structure
+
+```javascript
+{
+  // Required
+  "name": "Button",              // PascalCase, unique identifier
+  
+  // Optional metadata
+  "description": "Interactive button component",
+  "category": "input",           // layout|input|feedback|overlay|data|nav
+  "version": "1.0.0",
+  
+  // Props definition
+  "props": {
+    "propName": { /* PropDefinition */ }
+  },
+  
+  // Slots definition
+  "slots": {
+    "slotName": { /* SlotDefinition */ }
+  },
+  
+  // CrossBus messages
+  "messages": {
+    "emit": ["category:component:action"],
+    "listen": ["category:component:action"]
+  },
+  
+  // CSS Variables used (for documentation/theming)
+  "cssVars": [
+    "--mu-color-primary",
+    "--mu-radius-md"
+  ]
+}
+```
+
+---
+
+## PropDefinition
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `PropType` | ✅ | Data type |
+| `required` | `boolean` | ❌ | Default: `false` |
+| `default` | `any` | ❌ | Default value |
+| `values` | `string[]` | ❌ | For `enum` type only |
+| `description` | `string` | ❌ | Human/AI readable |
+| `validate` | `function` | ❌ | Custom validator |
+
+### PropType Values
+
+| Type | Description | Example Default |
+|------|-------------|-----------------|
+| `string` | Text value | `""` |
+| `number` | Numeric value | `0` |
+| `boolean` | True/false | `false` |
+| `object` | Object/map | `{}` |
+| `array` | Array/list | `[]` |
+| `function` | Callback | `() => {}` |
+| `enum` | One of `values` | First value |
+| `action` | Event handler (semantic) | `null` |
+| `node` | uhtml template/component | `null` |
+
+---
+
+## Complete Example: Button
+
+```javascript
+const ButtonSchema = {
+  name: "Button",
+  description: "Primary action trigger",
+  category: "input",
+  
+  props: {
+    // Content
+    label: {
+      type: "string",
+      required: true,
+      description: "Button text"
+    },
+    
+    // Appearance
+    variant: {
+      type: "enum",
+      values: ["primary", "secondary", "ghost", "danger"],
+      default: "primary",
+      description: "Visual style variant"
+    },
+    size: {
+      type: "enum",
+      values: ["sm", "md", "lg"],
+      default: "md",
+      description: "Size preset"
+    },
+    
+    // State
+    disabled: {
+      type: "boolean",
+      default: false,
+      description: "Disable interaction"
+    },
+    loading: {
+      type: "boolean",
+      default: false,
+      description: "Show loading state"
+    },
+    
+    // Behavior
+    type: {
+      type: "enum",
+      values: ["button", "submit", "reset"],
+      default: "button",
+      description: "HTML button type"
+    },
+    
+    // Events (semantic actions)
+    onClick: {
+      type: "action",
+      description: "Click handler"
+    }
+  },
+  
+  slots: {
+    default: {
+      description: "Button content (overrides label)"
+    },
+    icon: {
+      description: "Leading icon"
+    },
+    iconEnd: {
+      description: "Trailing icon"
+    }
+  },
+  
+  messages: {
+    emit: [
+      "ui:button:click",
+      "ui:button:focus",
+      "ui:button:blur"
+    ],
+    listen: [
+      "ui:button:setLoading",
+      "ui:button:setDisabled"
+    ]
+  },
+  
+  cssVars: [
+    "--mu-color-primary",
+    "--mu-color-primary-dark",
+    "--mu-radius-md",
+    "--mu-font-weight-medium",
+    "--mu-shadow-sm",
+    "--mu-duration-fast"
+  ]
+};
+```
+
+---
+
+## Schema Compilation
+
+At definition-time, the schema compiles into:
+
+1. **Default resolver function**: Pre-computed defaults object
+2. **Prop validator**: DEV-only validation (stripped in prod)
+3. **Message bindings**: Auto-wired CrossBus listeners
+4. **CSS class generator**: Based on variant/size props
+
+```javascript
+// Compilation output (conceptual)
+{
+  defaults: { variant: "primary", size: "md", disabled: false, loading: false, type: "button" },
+  required: ["label"],
+  variantClasses: { primary: "mu-btn--primary", secondary: "mu-btn--secondary", ... },
+  sizeClasses: { sm: "mu-btn--sm", md: "mu-btn--md", lg: "mu-btn--lg" }
+}
+```
+
+---
+
+## Initial Component Library (10 Components)
+
+| Component | Category | Priority | Schema Complexity |
+|-----------|----------|----------|-------------------|
+| `Button` | input | P0 | Medium |
+| `Input` | input | P0 | High |
+| `Stack` | layout | P0 | Low |
+| `Text` | typography | P0 | Low |
+| `Card` | layout | P1 | Low |
+| `Modal` | overlay | P1 | High |
+| `Alert` | feedback | P1 | Medium |
+| `Spinner` | feedback | P1 | Low |
+| `Select` | input | P2 | High |
+| `Tabs` | nav | P2 | High |
+
+---
+
+## Validation Rules
+
+### Name Pattern
+- Must be PascalCase: `/^[A-Z][a-zA-Z0-9]+$/`
+- Must be unique in registry
+
+### Props
+- `required` cannot have `default`
+- `enum` must have non-empty `values`
+- `action` type implies event handler semantics
+
+### Messages
+- Format: `category:component:action`
+- Categories: `ui`, `state`, `nav`, `app`
+- Actions use past tense for emits: `clicked`, `changed`
+- Actions use imperative for listens: `setLoading`, `focus`

package/docs/components.md

@@ -0,0 +1,269 @@
+# Components Reference
+
+microUI includes 49 Web Components following Material Design 3.
+
+## Form Components
+
+### mu-button
+Interactive button with MD3 styling and ripple effect.
+
+```html
+<mu-button variant="filled">Primary</mu-button>
+<mu-button variant="tonal">Tonal</mu-button>
+<mu-button variant="elevated">Elevated</mu-button>
+<mu-button variant="outlined">Outlined</mu-button>
+<mu-button variant="text">Text</mu-button>
+<mu-button disabled>Disabled</mu-button>
+```
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `variant` | `filled`, `tonal`, `elevated`, `outlined`, `text` | `filled` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `disabled` | boolean | `false` |
+
+### mu-input
+Text input with floating label.
+
+```html
+<mu-input label="Email" type="email" placeholder="Enter email"></mu-input>
+<mu-input variant="outlined" label="Password" type="password"></mu-input>
+```
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `type` | `text`, `email`, `password`, `number`, `tel` | `text` |
+| `label` | string | - |
+| `variant` | `filled`, `outlined` | `filled` |
+| `disabled`, `required` | boolean | `false` |
+
+**Events:** `mu-input`, `mu-change`
+
+### mu-checkbox
+Checkbox for multiple selections.
+
+```html
+<mu-checkbox>Option 1</mu-checkbox>
+<mu-checkbox checked>Selected</mu-checkbox>
+```
+
+### mu-switch
+Toggle switch for on/off states.
+
+```html
+<mu-switch label="Dark mode"></mu-switch>
+<mu-switch checked>Enabled</mu-switch>
+```
+
+### mu-radio
+Radio buttons for single selection.
+
+```html
+<mu-radio name="size" value="sm">Small</mu-radio>
+<mu-radio name="size" value="md" checked>Medium</mu-radio>
+<mu-radio name="size" value="lg">Large</mu-radio>
+```
+
+### mu-dropdown
+Dropdown select menu.
+
+```html
+<mu-dropdown placeholder="Select option">
+    <mu-option value="1">Option 1</mu-option>
+    <mu-option value="2">Option 2</mu-option>
+</mu-dropdown>
+```
+
+---
+
+## Layout Components
+
+### mu-stack
+Flexbox layout container.
+
+```html
+<mu-stack direction="row" gap="md" align="center">
+    <div>Item 1</div>
+    <div>Item 2</div>
+</mu-stack>
+```
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `direction` | `row`, `column` | `column` |
+| `gap` | `xs`, `sm`, `md`, `lg`, `xl` | `md` |
+| `align` | `start`, `center`, `end`, `stretch` | `stretch` |
+| `justify` | `start`, `center`, `end`, `space-between` | `start` |
+| `wrap` | boolean | `false` |
+
+### mu-grid
+CSS Grid layout.
+
+```html
+<mu-grid cols="3" gap="md">
+    <mu-card>1</mu-card>
+    <mu-card>2</mu-card>
+    <mu-card>3</mu-card>
+</mu-grid>
+```
+
+### mu-container
+Centered content container with max-width.
+
+```html
+<mu-container size="md">
+    <!-- content -->
+</mu-container>
+```
+
+---
+
+## Display Components
+
+### mu-card
+Container for related content.
+
+```html
+<mu-card variant="elevated">
+    <h3>Title</h3>
+    <p>Content</p>
+</mu-card>
+```
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `variant` | `elevated`, `filled`, `outlined` | `elevated` |
+
+### mu-tabs
+Tabbed content navigation.
+
+```html
+<mu-tabs>
+    <mu-tab label="Tab 1" active>Content 1</mu-tab>
+    <mu-tab label="Tab 2">Content 2</mu-tab>
+</mu-tabs>
+```
+
+### mu-avatar
+User avatar with image or initials.
+
+```html
+<mu-avatar src="photo.jpg"></mu-avatar>
+<mu-avatar initials="JD"></mu-avatar>
+```
+
+### mu-badge
+Count or status indicator.
+
+```html
+<mu-badge count="5">Notifications</mu-badge>
+<mu-badge dot>Updates</mu-badge>
+```
+
+### mu-chip
+Compact interactive element.
+
+```html
+<mu-chip>Tag</mu-chip>
+<mu-chip removable>Removable</mu-chip>
+```
+
+### mu-icon
+SVG icon from built-in set.
+
+```html
+<mu-icon name="check"></mu-icon>
+<mu-icon name="close"></mu-icon>
+<mu-icon name="menu"></mu-icon>
+```
+
+---
+
+## Feedback Components
+
+### mu-alert
+Static message display.
+
+```html
+<mu-alert variant="info">Information</mu-alert>
+<mu-alert variant="success">Success!</mu-alert>
+<mu-alert variant="warning">Warning</mu-alert>
+<mu-alert variant="error">Error</mu-alert>
+```
+
+### mu-modal
+Dialog overlay.
+
+```html
+<mu-modal id="my-modal" title="Dialog">
+    <p>Modal content</p>
+</mu-modal>
+<mu-button onclick="document.getElementById('my-modal').open()">Open</mu-button>
+```
+
+**Methods:** `.open()`, `.close()`
+
+### mu-toast
+Brief notification (via JavaScript).
+
+```javascript
+import { showToast } from 'microui-wc';
+showToast('Success!', { variant: 'success', duration: 3000 });
+```
+
+### mu-progress
+Progress indicator.
+
+```html
+<mu-progress value="50"></mu-progress>
+<mu-progress indeterminate></mu-progress>
+```
+
+### mu-spinner
+Loading spinner.
+
+```html
+<mu-spinner size="md"></mu-spinner>
+```
+
+---
+
+## Navigation Components
+
+### mu-navbar
+Top navigation bar.
+
+```html
+<mu-navbar title="My App">
+    <mu-nav-item href="/">Home</mu-nav-item>
+    <mu-nav-item href="/about">About</mu-nav-item>
+</mu-navbar>
+```
+
+### mu-router
+Page routing (see [Page-Based Development](../AGENTS.md#page-based-app-development-v32)).
+
+```html
+<mu-router base="/app/pages" default="home"></mu-router>
+```
+
+---
+
+## Utility Components
+
+### mu-theme-toggle
+Light/dark mode toggle.
+
+```html
+<mu-theme-toggle></mu-theme-toggle>
+```
+
+### mu-virtual-list
+Virtualized list for large datasets.
+
+```javascript
+const list = document.querySelector('mu-virtual-list');
+list.items = largeArray;
+list.itemHeight = 50;
+list.renderItem = (item) => `<div>${item.name}</div>`;
+```

package/docs/design-system.md

@@ -0,0 +1,183 @@
+# Design System
+
+microUI implements Material Design 3 (Material You) tokens and styling.
+
+## Color Tokens
+
+### System Colors
+
+```css
+/* Primary */
+--md-sys-color-primary
+--md-sys-color-on-primary
+--md-sys-color-primary-container
+--md-sys-color-on-primary-container
+
+/* Secondary */
+--md-sys-color-secondary
+--md-sys-color-on-secondary
+
+/* Tertiary */
+--md-sys-color-tertiary
+--md-sys-color-on-tertiary
+
+/* Error */
+--md-sys-color-error
+--md-sys-color-on-error
+
+/* Surface */
+--md-sys-color-surface
+--md-sys-color-on-surface
+--md-sys-color-surface-variant
+--md-sys-color-surface-container
+--md-sys-color-surface-container-low
+--md-sys-color-surface-container-high
+
+/* Outline */
+--md-sys-color-outline
+--md-sys-color-outline-variant
+```
+
+### Usage
+
+```html
+<div style="background: var(--md-sys-color-primary); color: var(--md-sys-color-on-primary);">
+    Primary surface
+</div>
+```
+
+---
+
+## Typography
+
+### Type Scale
+
+```css
+/* Display */
+--md-sys-typescale-display-large-size: 57px;
+--md-sys-typescale-display-medium-size: 45px;
+--md-sys-typescale-display-small-size: 36px;
+
+/* Headline */
+--md-sys-typescale-headline-large-size: 32px;
+--md-sys-typescale-headline-medium-size: 28px;
+--md-sys-typescale-headline-small-size: 24px;
+
+/* Title */
+--md-sys-typescale-title-large-size: 22px;
+--md-sys-typescale-title-medium-size: 16px;
+--md-sys-typescale-title-small-size: 14px;
+
+/* Body */
+--md-sys-typescale-body-large-size: 16px;
+--md-sys-typescale-body-medium-size: 14px;
+--md-sys-typescale-body-small-size: 12px;
+
+/* Label */
+--md-sys-typescale-label-large-size: 14px;
+--md-sys-typescale-label-medium-size: 12px;
+--md-sys-typescale-label-small-size: 11px;
+```
+
+---
+
+## Shape (Border Radius)
+
+```css
+--md-sys-shape-corner-none: 0;
+--md-sys-shape-corner-extra-small: 4px;
+--md-sys-shape-corner-small: 8px;
+--md-sys-shape-corner-medium: 12px;
+--md-sys-shape-corner-large: 16px;
+--md-sys-shape-corner-extra-large: 28px;
+--md-sys-shape-corner-full: 9999px;
+```
+
+---
+
+## Elevation (Shadows)
+
+```css
+--md-sys-elevation-level0: none;
+--md-sys-elevation-level1: 0 1px 2px rgba(0,0,0,0.3), 0 1px 3px 1px rgba(0,0,0,0.15);
+--md-sys-elevation-level2: 0 1px 2px rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15);
+--md-sys-elevation-level3: 0 1px 3px rgba(0,0,0,0.3), 0 4px 8px 3px rgba(0,0,0,0.15);
+--md-sys-elevation-level4: 0 2px 3px rgba(0,0,0,0.3), 0 6px 10px 4px rgba(0,0,0,0.15);
+--md-sys-elevation-level5: 0 4px 4px rgba(0,0,0,0.3), 0 8px 12px 6px rgba(0,0,0,0.15);
+```
+
+---
+
+## Motion
+
+```css
+/* Duration */
+--md-sys-motion-duration-short1: 50ms;
+--md-sys-motion-duration-short2: 100ms;
+--md-sys-motion-duration-medium1: 250ms;
+--md-sys-motion-duration-medium2: 300ms;
+
+/* Easing */
+--md-sys-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1);
+--md-sys-motion-easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
+```
+
+---
+
+## Spacing
+
+```css
+--mu-spacing-1: 4px;
+--mu-spacing-2: 8px;
+--mu-spacing-3: 12px;
+--mu-spacing-4: 16px;
+--mu-spacing-6: 24px;
+--mu-spacing-8: 32px;
+```
+
+---
+
+## Dark Mode
+
+Dark mode is automatic based on system preference, or can be forced:
+
+```html
+<!-- Force dark -->
+<html data-theme="dark">
+
+<!-- Force light -->
+<html data-theme="light">
+
+<!-- System (default) -->
+<html>
+```
+
+Toggle programmatically:
+
+```javascript
+import { Theme } from 'microui-wc';
+Theme.toggle();
+```
+
+Or use the component:
+
+```html
+<mu-theme-toggle></mu-theme-toggle>
+```
+
+---
+
+## Customizing Tokens
+
+Override tokens in your CSS:
+
+```css
+:root {
+    /* Custom primary color */
+    --md-ref-palette-primary40: #1976D2;
+    --md-ref-palette-primary80: #90CAF9;
+    
+    /* Custom font */
+    --md-sys-typescale-font: 'Inter', sans-serif;
+}
+```