@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/references/patterns-forms.md

@@ -0,0 +1,223 @@
+# Form Patterns
+
+## Basic Form
+
+```html
+<card-ui>
+  <header>
+    <span slot="heading" variant="section">Create Account</span>
+    <span slot="description">Fill in your details</span>
+  </header>
+  <section>
+    <form>
+      <col-ui gap="4">
+        <input-ui label="Full Name" name="name" required placeholder="Jane Doe"></input-ui>
+        <input-ui label="Email" name="email" type="email" required placeholder="jane@example.com"></input-ui>
+        <input-ui label="Password" name="password" type="password" required minlength="8"></input-ui>
+        <field-ui label="Bio">
+          <textarea-ui name="bio" placeholder="Tell us about yourself"></textarea-ui>
+        </field-ui>
+        <select-ui label="Role" name="role">
+          <option value="developer">Developer</option>
+          <option value="designer">Designer</option>
+          <option value="manager">Manager</option>
+        </select-ui>
+        <check-ui name="terms" label="I agree to the terms"></check-ui>
+        <button-ui text="Create Account" variant="primary" type="submit" stretch></button-ui>
+      </col-ui>
+    </form>
+  </section>
+</card-ui>
+```
+
+## Key Rules
+
+- Use a raw `<form>` element to wrap fields for native submit serialization
+- Every field needs a `name` for form data collection
+- Use `label` attribute (not a separate `<label>` element)
+- Use `required`, `minlength`, `maxlength`, `pattern` for constraint validation
+- Custom error messages: `data-msg-required="Please enter your name"` etc.
+- `<button-ui type="submit">` triggers submission
+- `form-submit` event: `{ detail: { action, method, data } }`
+- Form validates on submit automatically — surfaces errors on invalid fields
+- On input after error: re-validates to clear as soon as value is valid
+
+## Validation
+
+```html
+<!-- Built-in constraints -->
+<input-ui label="Email" name="email" type="email" required
+  data-msg-required="Email is required"
+  data-msg-pattern="Enter a valid email">
+</input-ui>
+
+<input-ui label="Username" name="user" required minlength="3" maxlength="20"
+  pattern="[a-z0-9_]+"
+  data-msg-pattern="Only lowercase letters, numbers, and underscores">
+</input-ui>
+```
+
+Programmatic validation:
+```js
+const field = document.querySelector('input-ui[name="email"]');
+field.validate();           // returns boolean, surfaces error
+field.setInvalid('Custom error message');
+field.setValid();
+```
+
+## Login Form
+
+```html
+<card-ui size="lg" style="max-width:400px">
+  <header center>
+    <span slot="heading" variant="section">Welcome back</span>
+    <span slot="description">Sign in to your account</span>
+  </header>
+  <section>
+    <form action="/api/login" method="post">
+      <col-ui gap="4">
+        <input-ui label="Email" name="email" type="email" required prefix="envelope"></input-ui>
+        <input-ui label="Password" name="password" type="password" required suffix="eye"></input-ui>
+        <row-ui justify="between" align="center">
+          <check-ui name="remember" label="Remember me"></check-ui>
+          <a href="/forgot" style="font-size:var(--a-font-size-xs)">Forgot password?</a>
+        </row-ui>
+        <button-ui text="Sign In" variant="primary" type="submit" stretch></button-ui>
+      </col-ui>
+    </form>
+  </section>
+</card-ui>
+```
+
+## Settings Panel with Toggles
+
+```html
+<card-ui>
+  <header divider>
+    <span slot="heading" variant="section">Notifications</span>
+    <span slot="description">Manage how you receive notifications</span>
+  </header>
+  <section>
+    <col-ui gap="4">
+      <row-ui justify="between" align="center">
+        <col-ui gap="1">
+          <strong>Email notifications</strong>
+          <small style="color:var(--a-canvas-text-subtle)">Receive updates via email</small>
+        </col-ui>
+        <switch-ui name="email-notif"></switch-ui>
+      </row-ui>
+      <divider-ui></divider-ui>
+      <row-ui justify="between" align="center">
+        <col-ui gap="1">
+          <strong>Push notifications</strong>
+          <small style="color:var(--a-canvas-text-subtle)">Browser push alerts</small>
+        </col-ui>
+        <switch-ui name="push-notif"></switch-ui>
+      </row-ui>
+    </col-ui>
+  </section>
+</card-ui>
+```
+
+## Input with Icons
+
+```html
+<input-ui label="Search" prefix="magnifying-glass" placeholder="Search..."></input-ui>
+<input-ui label="Amount" prefix="currency-dollar" placeholder="0.00"></input-ui>
+<input-ui label="Password" type="password" suffix="eye"></input-ui>
+```
+
+## Where field affordances go — status text vs buttons vs captions
+
+Three different homes. Pick by what the affordance **is**, not where it visually sits:
+
+| Affordance | Home | Result |
+|---|---|---|
+| Short **status / label text** — "Required", "Results: 12", "Light", "USD" | input-ui `prefix=` / `suffix=` (string props) | renders **inside** the input chrome, before/after the value; input stays full-width |
+| **Interactive controls** — clear, copy, ⌘K hint, open-in-modal | `<button-ui slot="leading">` / `slot="trailing">` (or `<kbd-ui slot="trailing">`) **inside `<input-ui>`** | installed into the chrome; DOM order `prefix → leading → value → suffix → trailing` |
+| A caption / count / submit **beside** the field (outside the input box) | `slot="trailing"` / `slot="action"` on the **`<field-ui>`** (not the input) | sits next to the input row, not inside the chrome |
+
+```html
+<!-- status text in-chrome → input suffix; clear button → input trailing slot -->
+<field-ui inline label="Filter">
+  <input-ui placeholder="Name or tag" suffix="Results: 12">
+    <button-ui slot="trailing" icon="x" variant="ghost" aria-label="Clear"></button-ui>
+  </input-ui>
+</field-ui>
+```
+
+**Don't** put short status text in a `slot="trailing"` element — the affordance slots are for interactive controls; text belongs in `suffix`/`prefix` so it stays in-chrome and the input keeps full width. (bug-55 / bug-60.)
+
+## Raw Input (embedded in custom container)
+
+```html
+<card-ui>
+  <section>
+    <row-ui gap="2" align="center">
+      <icon-ui name="magnifying-glass"></icon-ui>
+      <input-ui raw placeholder="Search anything..." style="flex:1"></input-ui>
+    </row-ui>
+  </section>
+</card-ui>
+```
+
+`raw` strips background, border, padding, radius, outline, and height from `input-ui`.
+
+## OTP Input
+
+```html
+<card-ui size="lg" style="max-width:400px;text-align:center">
+  <header center>
+    <span slot="heading" variant="section">Verify your email</span>
+    <span slot="description">Enter the 6-digit code</span>
+  </header>
+  <section>
+    <col-ui gap="4" style="align-items:center">
+      <otp-input-ui length="6"></otp-input-ui>
+      <button-ui text="Verify" variant="primary" stretch></button-ui>
+    </col-ui>
+  </section>
+</card-ui>
+```
+
+## Wired Form (with A007)
+
+A form that fetches data, validates, and submits via wiring:
+
+```json
+{
+  "type": "wireComponents",
+  "surfaceId": "profile",
+  "data": {
+    "sources": [{ "id": "user", "path": "/user", "uri": "resource://users/{userId}", "refresh": "once" }],
+    "params": { "userId": { "from": "route", "key": "id" } }
+  },
+  "state": {
+    "controllers": [{ "id": "form", "type": "FormController", "host": "form-root", "config": { "validateOn": "blur" } }]
+  },
+  "actions": [{
+    "event": "form-submit", "source": "form-root",
+    "handler": "submit-resource", "method": "PUT", "uri": "resource://users/{userId}",
+    "body": { "from": "event-detail", "key": "data" },
+    "onSuccess": { "notify": "Profile saved" },
+    "onError": { "notify": "Save failed" }
+  }]
+}
+```
+
+Fields bind to the data model: `"value": { "path": "/user/name" }` — auto-populated from fetch.
+
+## Date, Color, Slider
+
+```html
+<field-ui label="Appointment">
+  <datetime-picker-ui name="appt"></datetime-picker-ui>
+</field-ui>
+<field-ui label="Date of Birth">
+  <calendar-picker-ui name="dob"></calendar-picker-ui>
+</field-ui>
+<field-ui label="Brand Color">
+  <color-picker-ui name="color"></color-picker-ui>
+</field-ui>
+<slider-ui min="0" max="100" value="50"></slider-ui>
+```

package/skills/adia-ui-kit/references/patterns-layout.md

@@ -0,0 +1,326 @@
+# Layout Patterns
+
+## Card — The Universal Container
+
+Every surface is built from cards. The content model is mandatory.
+
+```html
+<card-ui>
+  <header>
+    <span slot="icon"><icon-ui name="users"></icon-ui></span>
+    <span slot="heading" variant="section">Team Members</span>
+    <span slot="description">Active members in your workspace</span>
+    <button-ui slot="action" text="Add" variant="ghost" icon="plus" size="sm"></button-ui>
+  </header>
+  <section>
+    <col-ui gap="2">
+      <!-- content always inside col-ui -->
+    </col-ui>
+  </section>
+  <footer divider>
+    <span slot="description">12 members total</span>
+    <button-ui slot="action" text="View All" size="sm"></button-ui>
+  </footer>
+</card-ui>
+```
+
+Header grid adapts to present slots:
+- `icon` + `action`: `max-content 1fr max-content`
+- `icon` only: `max-content 1fr`
+- `action` only: `1fr max-content`
+- Neither: `1fr`
+
+`[divider]` on header/footer adds a border separator with padding.
+`[center]` on header centers text and items.
+`[bleed]` on section removes padding (edge-to-edge content like images or tables).
+
+## Card Sizes
+
+```html
+<card-ui size="xl">Hero-level — largest inset, biggest radius</card-ui>
+<card-ui size="lg">Spacious — old default card scale</card-ui>
+<card-ui>Default (md) — standard card</card-ui>
+<card-ui size="sm">Compact — row-level density</card-ui>
+<card-ui size="xs">Ultra-dense — minimal inset</card-ui>
+```
+
+Each size sets: `--inset` (padding), `--radius`, `--gap`, and all heading/text font sizes.
+
+## Card Variants
+
+```html
+<card-ui variant="outlined">Visible border, transparent background, no shadow</card-ui>
+<card-ui variant="filled">Filled background</card-ui>
+<card-ui variant="ghost">Transparent background and border</card-ui>
+<card-ui raw>No background, border, or shadow — structural wrapper only</card-ui>
+<card-ui elevation="0">Flat (no shadow)</card-ui>
+<card-ui elevation="2">Medium shadow</card-ui>
+<card-ui elevation="3">Strong shadow</card-ui>
+```
+
+`raw` strips all chrome. The card's content model (header/section/footer) still applies.
+
+## Stack Layout
+
+```html
+<!-- Vertical stack -->
+<col-ui gap="4">
+  <input-ui label="Name"></input-ui>
+  <input-ui label="Email"></input-ui>
+  <button-ui text="Submit" variant="primary"></button-ui>
+</col-ui>
+
+<!-- Horizontal row -->
+<row-ui gap="2" justify="between" align="center">
+  <span>Total: $49.99</span>
+  <button-ui text="Pay Now" variant="primary"></button-ui>
+</row-ui>
+
+<!-- Nested: action bar -->
+<row-ui justify="between">
+  <button-ui text="Back" variant="ghost"></button-ui>
+  <row-ui gap="2">
+    <button-ui text="Cancel"></button-ui>
+    <button-ui text="Save" variant="primary"></button-ui>
+  </row-ui>
+</row-ui>
+```
+
+`justify` values: `start`, `end`, `center`, `between`, `around`, `evenly`.
+`align` values: `start`, `end`, `center`, `stretch`, `baseline`.
+
+All three string props (`gap`, `align`, `justify`) on `col-ui` and `row-ui` accept `@bp` responsive notation — see **Responsive Layout** below.
+
+## Grid
+
+```html
+<!-- Equal columns -->
+<grid-ui columns="3" gap="4">
+  <card-ui>Card 1</card-ui>
+  <card-ui>Card 2</card-ui>
+  <card-ui>Card 3</card-ui>
+</grid-ui>
+
+<!-- Asymmetric: 3:2 split -->
+<grid-ui columns="5" gap="4">
+  <card-ui span="3">Wide</card-ui>
+  <card-ui span="2">Narrow</card-ui>
+</grid-ui>
+```
+
+Canonical ratios: `2:1 → columns="3" + span="2"` · `3:2 → columns="5" + span="3"+"2"` · `4:1 → columns="5" + span="4"` · `3:1 → columns="4" + span="3"`.
+
+Never set `grid-template-columns` via inline style — use `columns=` and child `span=` instead. `columns` and `gap` both accept `@bp` notation.
+
+> ⚠️ **`gap=` and `columns=` take NUMERIC tokens, NOT size keywords.** Valid: `gap="3"`, `gap="4"`, `gap="6"`, `columns="3"`, `columns="2 4@md"`. **Invalid**: `gap="md"`, `gap="lg"`, `gap="small"`, `columns="auto"`. The numbers map to `--a-space-N` density tokens — `gap="4"` resolves to `var(--a-space-4)`. Size keywords are a `<button-ui size="sm">` / `<badge-ui size="lg">` convention; layout primitives use numeric density tokens. Same rule applies to `col-ui` and `row-ui` `gap=`. Anti-pattern visible in agent-generated DOM: `<grid-ui columns="3" gap="md">` — renders without gap (invalid token falls back to default 0 or browser default).
+
+## Responsive Layout
+
+Props on `grid-ui`, `col-ui`, `row-ui`, `text-ui`, and `block-ui` accept `@bp` annotations for viewport-driven layout. No media queries, no utility classes, no hidden elements.
+
+### Syntax
+
+Append `@breakpoint` to any value that should apply from that breakpoint upward. The unannotated value is the mobile-first base (smallest screens). The largest annotation that is ≤ the active breakpoint wins.
+
+```
+columns="1 2@sm 4@lg"   →  1 at xs · 2 at sm/md · 4 at lg/xl
+gap="2 4@md"            →  2 below md · 4 from md up
+justify="start between@md"
+```
+
+### Breakpoint scale
+
+| Name | Min-width | Typical target |
+|---|---|---|
+| `xs` | 0 px | Portrait phone (base — no annotation needed) |
+| `sm` | 480 px | Large phone / portrait tablet |
+| `md` | 768 px | Landscape tablet |
+| `lg` | 1024 px | Small desktop |
+| `xl` | 1280 px | Standard desktop+ |
+
+### Supported props
+
+| Component | Responsive props |
+|---|---|
+| `grid-ui` | `columns`, `gap` |
+| `col-ui` | `gap`, `align`, `justify` |
+| `row-ui` | `gap`, `align`, `justify`; `wrap-at="bp"` for responsive wrap |
+| `text-ui` | `size` |
+| `block-ui` | `padding`, `margin` |
+
+### Common patterns
+
+```html
+<!-- Dashboard KPI grid: 2×2 on mobile, 4-up from tablet -->
+<grid-ui columns="2 4@md" gap="4">
+  <card-ui>...</card-ui>
+  <card-ui>...</card-ui>
+  <card-ui>...</card-ui>
+  <card-ui>...</card-ui>
+</grid-ui>
+
+<!-- Chart + sidebar: stacked on mobile, 3:2 split from tablet -->
+<grid-ui columns="1 5@md" gap="4">
+  <card-ui span="3">Chart</card-ui>
+  <card-ui span="2">Sidebar</card-ui>
+</grid-ui>
+
+<!-- 3-up strip: stacked on mobile, side-by-side from tablet -->
+<grid-ui columns="1 3@md" gap="4">
+  <card-ui>Team</card-ui>
+  <card-ui>Actions</card-ui>
+  <card-ui>Storage</card-ui>
+</grid-ui>
+
+<!-- Toolbar: stacked + tight on mobile, spread + roomy on desktop -->
+<row-ui gap="2 4@md" justify="start between@md" align="start center@md" wrap>
+  <text-ui strong>Recent transactions</text-ui>
+  <row-ui gap="2">
+    <button-ui text="Export"></button-ui>
+    <button-ui text="+ New" variant="primary"></button-ui>
+  </row-ui>
+</row-ui>
+
+<!-- Responsive text size -->
+<text-ui variant="heading" size="sm md@lg">Welcome back</text-ui>
+
+<!-- Less padding on mobile -->
+<block-ui padding="sm md@lg">...</block-ui>
+```
+
+**Responsive wrap** — boolean attrs like `wrap` can't use `@bp` value syntax; use `wrap-at="bp"` instead:
+
+```html
+&lt;!-- Toolbar: single row on desktop, wraps on mobile --&gt;
+&lt;row-ui gap="2 3@md" wrap-at="sm"&gt;
+  &lt;input-ui placeholder="Search..."&gt;&lt;/input-ui&gt;
+  &lt;button-ui text="Export"&gt;&lt;/button-ui&gt;
+  &lt;button-ui text="+ New" variant="primary"&gt;&lt;/button-ui&gt;
+&lt;/row-ui&gt;
+```
+
+**Anti-pattern:** never write `@media` blocks, inline `style=`, or hidden-element tricks for layout breakpoints on these components. The `@bp` attribute is the canonical path and is understood by the A2UI generation pipeline.
+
+## App Shell
+
+Full application layout with sidebar, header bar, and content area.
+
+```html
+<admin-shell mode="sidebar">
+  <nav slot="sidebar">
+    <sidebar-ui>
+      <header><span slot="heading" variant="section">MyApp</span></header>
+      <nav-ui>
+        <a href="/" data-active>Dashboard</a>
+        <a href="/settings">Settings</a>
+        <a href="/team">Team</a>
+      </nav-ui>
+    </sidebar-ui>
+  </nav>
+  <header slot="header">
+    <row-ui justify="between" align="center" style="padding:var(--a-space-2) var(--a-space-4)">
+      <h3 variant="section">Dashboard</h3>
+      <avatar-ui text="Jane" size="sm"></avatar-ui>
+    </row-ui>
+  </header>
+  <main slot="content">
+    <!-- page content -->
+  </main>
+</app-shell-ui>
+```
+
+Modes: `sidebar` (default), `sidebar-collapsed`, `header-only`, `minimal`.
+
+**Pitfall — flat CSS selector collapses shell layout (FB-04):**
+Consumer boilerplate sometimes includes a `/* Shell fill */` block:
+```css
+/* ❌ collapses the shell */
+admin-shell { display: block; height: 100dvh; }
+```
+Because `admin-shell` is a custom element, a flat CSS selector on the tag name wins the cascade when imported after the shell's own stylesheet (`display: flex` from the component). The entire sidebar + content grid collapses to a block stack. **Never set `display` on `admin-shell` directly.** The shell already manages its own display. To fill the viewport, set `height: 100dvh` on the `<body>` or a wrapping `<div>` instead, or use `min-height`:
+```css
+/* ✅ safe */
+body { margin: 0; height: 100dvh; display: flex; flex-direction: column; }
+admin-shell { flex: 1; min-height: 0; }
+```
+To adjust shell geometry, override the shell's CSS custom properties (e.g. `--page-sidebar-width-leading`, `--page-header-height`) rather than the component's structural CSS.
+
+## Tabs
+
+Tabs are a button strip. Content panels are **siblings**, not children.
+
+```html
+<col-ui gap="4">
+  <tabs-ui value="profile">
+    <tab-ui value="profile" text="Profile"></tab-ui>
+    <tab-ui value="security" text="Security"></tab-ui>
+    <tab-ui value="billing" text="Billing"></tab-ui>
+  </tabs-ui>
+  <!-- Panels shown/hidden based on active tab -->
+  <card-ui><!-- profile panel --></card-ui>
+</col-ui>
+```
+
+Variants: `line` (underline indicator) or `pill` (filled background).
+
+## Modal / Dialog / Drawer
+
+Modal is a chromeless overlay — child content owns all visual styling:
+
+```html
+<modal-ui open size="md">
+  <card-ui>
+    <header><span slot="heading" variant="section">Confirm</span></header>
+    <section><p>Are you sure?</p></section>
+    <footer>
+      <button-ui text="Cancel"></button-ui>
+      <button-ui text="Confirm" variant="primary"></button-ui>
+    </footer>
+  </card-ui>
+</modal-ui>
+```
+
+Dialog for simple confirmations (uses `<confirm-dialog-ui>` from web-modules/feedback):
+```html
+<confirm-dialog-ui title="Delete?" description="This cannot be undone." confirm-text="Delete" cancel-text="Keep"></confirm-dialog-ui>
+```
+
+Drawer slides from an edge:
+```html
+<drawer-ui open side="right">
+  <header><span slot="heading" variant="section">Details</span></header>
+  <section>Content</section>
+</drawer-ui>
+```
+
+## Theming
+
+```html
+<!-- CSS-only preset (zero JS) -->
+<div theme="ocean">
+  <card-ui>Ocean themed</card-ui>
+</div>
+
+<!-- Interactive theme switcher (renders preset buttons + optional sliders) -->
+<popover-ui>
+  <button-ui slot="trigger" text="Theme"></button-ui>
+  <theme-panel slot="content" parametric presets scheme-toggle></theme-panel>
+</popover-ui>
+```
+
+Presets: default, ocean, forest, sunset, lavender, rose, slate, midnight.
+
+Parametric tuning (applied as CSS custom properties on the wrapping element when `[parametric]` is set on `<theme-panel>`): `--a-density`, `--a-radius-k`, `--a-chroma`, `--a-space-scale`, `--a-shadow-scale`, `--a-motion-scale`.
+
+## Headings
+
+Use `[variant]` for visual emphasis — `<h1>`-`<h6>` are purely structural:
+
+```html
+<h1 variant="display">Hero text</h1>
+<h2 variant="title">Page title</h2>
+<h3 variant="section">Section heading</h3>
+<span variant="label">Label text</span>
+<span variant="eyebrow">Overline</span>
+<span variant="caption">Caption</span>
+```