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

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

@@ -0,0 +1,259 @@
+# Trait Patterns
+
+## What Traits Are
+
+Traits are composable behaviors that attach to any HTML element via `defineTrait()`.
+They follow a factory pattern: call the trait function to get an instance, connect it
+to an element, disconnect when done.
+
+```js
+import { pressable, focusable } from '@adiahealth/web-components/traits';
+
+const btn = document.querySelector('#my-btn');
+const inst = pressable();
+inst.connect(btn);
+btn.addEventListener('press', () => console.log('pressed!'));
+// Later: inst.disconnect(btn);
+```
+
+On AdiaElement subclasses:
+```js
+class MyWidget extends AdiaElement {
+  static traits = [pressable, focusable];  // auto-connect on mount
+}
+// Or at runtime:
+myElement.addTrait(draggable);
+```
+
+### Conventions
+
+- Every trait sets/removes `data-{trait-name}-{state}` attributes
+- Cleanup on `disconnect()` removes all managed attributes and listeners
+- Traits compose — multiple traits on the same element
+- Traits never modify innerHTML — attributes and listeners only
+- Schema available via `trait.schema`
+
+---
+
+## Interaction Traits
+
+### pressable
+Dispatches `press` event. Sets `data-pressable-pressed` during press.
+```js
+inst.connect(el);
+el.addEventListener('press', () => { /* handle */ });
+```
+
+### hoverable
+Sets `data-hoverable-hovered`. Fires `hover-start` / `hover-end`.
+
+### focusable
+Focus ring management. Sets `data-focusable-focused`.
+
+### draggable
+Makes element draggable. Sets `data-draggable-dragging`.
+Events: `drag-start`, `drag-move` (with `dx`, `dy`), `drag-end`.
+```js
+el.addEventListener('drag-move', (e) => console.log(e.detail.dx, e.detail.dy));
+```
+
+### inertia-drag
+Like draggable but with momentum/velocity after release. Element continues moving with deceleration.
+
+### resizable
+Adds resize handles. Sets `data-resizable-resizing` during resize.
+
+### tossable
+Fling/throw physics — element can be tossed with velocity.
+
+### scale-press
+Scales element down on press (tactile feedback). Sets `data-scale-press-active`.
+
+---
+
+## Focus & Keyboard Traits
+
+### focus-trap
+Traps Tab focus within a container (modals, dialogs):
+```js
+focusTrap().connect(modalElement);
+```
+
+### keyboard-nav
+Roving focus with arrow keys inside a container:
+```js
+keyboardNav().connect(listElement);
+```
+
+### hotkey
+Bind keyboard shortcuts:
+```js
+const inst = hotkey();
+inst.connect(el, { key: 'mod+k' });
+el.addEventListener('hotkey', () => openPalette());
+```
+`mod` = Cmd on Mac, Ctrl on Windows/Linux.
+
+### roving-tabindex
+Manages tabindex across a group of focusable elements. Only one active at a time.
+
+### typeahead
+Type-ahead search within a list — focuses matching item as user types.
+
+---
+
+## Form Traits
+
+### form-associated
+Makes non-form element participate in `<form>` submission.
+
+### dirty-state
+Tracks if value changed from initial. Sets `data-dirty-state-dirty`.
+
+### disabled-state
+Manages `data-disabled-state-disabled` with pointer/keyboard blocking.
+
+### resettable
+Restores initial value on form reset.
+
+### validation
+Reads rules from `data-validate="required,minlength:3,pattern:..."`.
+Sets `data-validation-invalid`, `data-validation-valid`, `data-validation-message`.
+Dispatches `validated` event with `{ valid, errors }`.
+
+### value-sync
+Syncs attribute `value`, property `value`, and controller state.
+Dispatches `value-change` with `{ value, oldValue, source }`.
+
+---
+
+## Animation Traits
+
+### fade-presence
+Animate in/out with opacity transition. Set `data-fade-presence-visible` to trigger.
+
+### count-up
+Animate number from 0 to target:
+```js
+el.setAttribute('data-count-up-target', '1000');
+el.setAttribute('data-count-up-active', '');
+```
+
+### attention-pulse
+Pulsing glow to draw attention.
+
+### glow-focus
+Glowing focus ring effect (alternative to default outline).
+
+### gradient-shift
+Animated gradient background shift.
+
+### confetti / confetti-burst
+Particle celebration effects:
+```js
+confetti().connect(el);
+el.setAttribute('data-confetti-active', '');
+```
+
+### spring-animate
+Spring physics animation (bounce, overshoot).
+
+### shimmer-loading
+Shimmer/skeleton loading effect overlay.
+
+### ripple
+Material-style ripple on click/press.
+
+---
+
+## Layout & Positioning Traits
+
+### anchor-positioning
+Position element relative to an anchor (popovers, tooltips):
+```js
+anchorPositioning().connect(popover, { anchor: triggerEl });
+```
+
+### portal
+Teleport element to a different DOM location (overlays):
+```js
+portal().connect(el, { target: document.body });
+```
+
+### parallax
+Scroll-linked parallax movement.
+
+### magnetic-hover
+Element subtly follows cursor on hover.
+
+### snap-to-grid
+Snaps drag position to a grid:
+```js
+snapToGrid().connect(el, { gridSize: 16 });
+```
+
+### scroll-lock
+Prevents body scroll (used with modals/drawers).
+
+---
+
+## Observer Traits
+
+### intersection-observer-trait
+Element visibility tracking:
+```js
+intersectionObserverTrait().connect(el);
+el.addEventListener('intersect', (e) => console.log(e.detail.isIntersecting));
+```
+
+### resize-observer-trait
+Element resize tracking:
+```js
+resizeObserverTrait().connect(el);
+el.addEventListener('resize', (e) => console.log(e.detail.width, e.detail.height));
+```
+
+---
+
+## Visual Traits
+
+### noise-texture
+Subtle noise overlay on element background.
+
+### drag-ghost
+Custom drag ghost image during drag operations.
+
+### haptic-feedback
+Vibration feedback on interaction (mobile).
+
+### tilt-hover
+3D tilt effect following cursor position on hover.
+
+### sound-feedback
+Play audio on interaction events.
+
+---
+
+## State Traits
+
+### active-state
+Toggles `data-active-state-active`. Useful for selection:
+```js
+activeState().connect(el);
+el.addEventListener('click', () => el.toggleAttribute('data-active-state-active'));
+```
+
+---
+
+## Full Trait Inventory (44)
+
+| Category | Traits |
+|----------|--------|
+| Interaction | pressable, hoverable, focusable, draggable, resizable, inertia-drag, tossable, scale-press |
+| Focus/Keyboard | focus-trap, keyboard-nav, hotkey, roving-tabindex, typeahead |
+| Form | form-associated, dirty-state, disabled-state, resettable, validation, value-sync |
+| Animation | fade-presence, count-up, attention-pulse, glow-focus, gradient-shift, confetti, confetti-burst, spring-animate, shimmer-loading, ripple |
+| Layout | anchor-positioning, portal, parallax, magnetic-hover, snap-to-grid, scroll-lock |
+| Observer | intersection-observer-trait, resize-observer-trait |
+| Visual | noise-texture, drag-ghost, haptic-feedback, tilt-hover, sound-feedback |
+| State | active-state |

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

@@ -0,0 +1,339 @@
+# Wiring, Manifests & Evolution Patterns
+
+## Wiring Contract (A007)
+
+Surfaces connect to live data, state, and actions via `wireComponents` messages.
+Always sent AFTER `updateComponents` — hosts must exist before wiring attaches.
+
+### Complete Wired Form
+
+```json
+[
+  { "type": "createSurface", "surfaceId": "profile" },
+  {
+    "type": "updateComponents",
+    "surfaceId": "profile",
+    "components": [
+      { "id": "root", "component": "Card", "size": "lg", "children": ["hdr", "form", "ftr"] },
+      { "id": "hdr", "component": "Header", "children": ["title"] },
+      { "id": "title", "component": "Text", "variant": "h3", "textContent": "Edit Profile" },
+      { "id": "form", "component": "FormContainer", "children": ["fields"] },
+      { "id": "fields", "component": "Column", "gap": "md", "children": ["name", "email"] },
+      { "id": "name", "component": "TextField", "label": "Name", "name": "name", "value": { "path": "/user/name" }, "required": true },
+      { "id": "email", "component": "TextField", "label": "Email", "name": "email", "type": "email", "value": { "path": "/user/email" } },
+      { "id": "ftr", "component": "Footer", "children": ["cancel", "save"] },
+      { "id": "cancel", "component": "Button", "text": "Cancel", "variant": "outline" },
+      { "id": "save", "component": "Button", "text": "Save", "variant": "primary" }
+    ]
+  },
+  {
+    "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-ctrl", "type": "FormController", "host": "form", "config": { "validateOn": "blur" } }
+      ]
+    },
+    "actions": [
+      {
+        "event": "form-submit", "source": "form",
+        "handler": "submit-resource", "method": "PUT", "uri": "resource://users/{userId}",
+        "body": { "from": "event-detail", "key": "data" },
+        "onSuccess": { "notify": "Profile saved", "refresh-source": "user" },
+        "onError": { "notify": "Save failed. Please try again." }
+      },
+      { "event": "click", "source": "cancel", "handler": "navigate-back" }
+    ]
+  }
+]
+```
+
+### Four Wiring Blocks (all optional)
+
+**data** — Where content comes from:
+```json
+"data": {
+  "sources": [
+    { "id": "patient", "path": "/patient", "uri": "resource://patients/{id}", "refresh": "on-focus" },
+    { "id": "types", "path": "/visitTypes", "uri": "resource://visit-types", "refresh": "once" }
+  ],
+  "params": { "id": { "from": "route", "key": "patientId" } }
+}
+```
+
+**state** — Controllers for lifecycle management:
+```json
+"state": {
+  "controllers": [
+    { "id": "form", "type": "FormController", "host": "form-root", "config": { "validateOn": "blur" } },
+    { "id": "stream", "type": "DataStreamController", "host": "chart", "config": { "max": 60, "throttle": 500 } }
+  ]
+}
+```
+
+**actions** — Event -> handler bindings:
+```json
+"actions": [
+  {
+    "event": "form-submit", "source": "form-root",
+    "handler": "submit-resource", "method": "POST", "uri": "resource://checkins",
+    "body": { "from": "event-detail", "key": "data" },
+    "onSuccess": { "notify": "Done", "navigate": "/patients/{id}/visits" },
+    "onError": { "notify": "Failed" }
+  }
+]
+```
+
+**provides** — Context for child surfaces:
+```json
+"provides": {
+  "context": "patient-ctx",
+  "host": "root",
+  "shape": { "patient": { "path": "/patient" }, "appointments": { "path": "/appointments" } }
+}
+```
+
+### Child Context Consumption
+
+Children consume from a provider without fetching:
+```json
+{
+  "type": "wireComponents",
+  "surfaceId": "insurance-card",
+  "data": {
+    "sources": [
+      { "id": "insurance", "path": "/insurance", "from-context": "patient-ctx", "key": "patient.insurance" }
+    ]
+  }
+}
+```
+
+No fetch — reads from the nearest ancestor provider with that context name.
+
+### Built-in Handlers
+
+| Handler | Purpose | Required fields |
+|---------|---------|-----------------|
+| `submit-resource` | POST/PUT/DELETE to resource URI | `uri`, `method` |
+| `update-model` | Update data model at a path | `path` |
+| `navigate` | Route navigation (`{param}` templates) | `navigate` value |
+| `navigate-back` | Browser history back | — |
+| `controller-command` | Invoke controller command | `controllerId`, `command` |
+| `emit-event` | Re-emit as named CustomEvent | `eventName` |
+| `refresh-source` | Re-fetch a data source | `sourceId` |
+| `notify` | Show toast notification | `message` |
+
+### Built-in Controllers
+
+| Type | Manages | Commands |
+|------|---------|----------|
+| `FormController` | Validation, dirty/pristine | `validate`, `reset`, `setFieldError` |
+| `DataStreamController` | Live data buffer | `push`, `connect`, `poll`, `stop`, `clear` |
+| `SelectionController` | Selected items | `select`, `deselect`, `toggle`, `selectAll`, `clear` |
+| `ToggleController` | Boolean on/off | `toggle`, `set` |
+| `AccordionController` | Panel expand/collapse | `open`, `close`, `toggle` |
+
+### Value Extraction
+
+```json
+{ "from": "event-detail", "key": "data" }       // e.detail.data
+{ "from": "event-target", "key": "value" }       // e.target.value
+{ "from": "model", "path": "/patient/name" }     // data model lookup
+{ "from": "literal", "value": "scheduled" }      // static value
+{ "from": "param", "key": "patientId" }          // resolved route param
+```
+
+### Refresh Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `once` | Fetch on initial wire |
+| `on-focus` | Re-fetch on window focus |
+| `interval:{ms}` | Poll at interval |
+| `stream` | Live via DataStreamController |
+| `on-action:{name}` | Re-fetch after action completes |
+
+### Custom Registration
+
+```js
+import { registerController, registerHandler, registerResolver } from '@adiahealth/a2ui';
+
+registerController('CheckinController', async () => (await import('./checkin-ctrl.js')).CheckinController);
+registerHandler('show-modal', async (ctx) => { ctx.source.closest('modal-ui').show = true; });
+registerResolver('fhir', async (uri) => (await fetch(uri.replace('fhir://', 'https://fhir.api/'))).json());
+```
+
+---
+
+## Surface Manifests (A008)
+
+Multiple surfaces declare relationships via a typed manifest.
+
+### Building a Manifest
+
+```js
+import { SurfaceManifest, ManifestRuntime, sharedContextStore } from '@adiahealth/a2ui';
+
+const manifest = new SurfaceManifest({ id: 'checkin-flow', name: 'Patient Check-in' });
+
+// Add surfaces
+manifest.addSurface('schedule', {
+  name: "Today's Schedule",
+  route: '/schedule',
+  entryPoint: true,
+  consumes: { 'patient-ctx': { keys: ['appointments'] } },
+});
+
+manifest.addSurface('checkin', {
+  name: 'Patient Check-in',
+  route: '/patients/:patientId/checkin',
+  requiredParams: ['patientId'],
+  produces: { 'checkin-result': { type: 'object' } },
+  consumes: { 'patient-ctx': { keys: ['patient'] } },
+});
+
+// Define shared context
+manifest.defineSharedContext('patient-ctx', {
+  shape: { patient: { type: 'object' }, appointments: { type: 'array' } },
+  source: { uri: 'resource://patients/{patientId}', refresh: 'on-focus' },
+});
+
+// Add associations
+manifest.addAssociation({ type: 'routes-to', from: 'schedule', to: 'checkin', trigger: 'action:begin-checkin' });
+manifest.addAssociation({ type: 'shares-context', from: 'schedule', to: 'checkin', context: 'patient-ctx' });
+manifest.addAssociation({ type: 'feeds', from: 'checkin', to: 'summary', trigger: 'action:submit-checkin',
+  mapping: { '/visit': { from: 'action-result' } }
+});
+manifest.addAssociation({ type: 'triggers', from: 'checkin', to: 'schedule', trigger: 'action:submit-checkin',
+  effect: 'refresh-source:appointments'
+});
+
+// Validate
+const { valid, issues } = manifest.validate();
+
+// Serialize / restore
+const json = manifest.toJSON();
+const restored = SurfaceManifest.fromJSON(json);
+```
+
+### ManifestRuntime
+
+```js
+const runtime = new ManifestRuntime(manifest);
+
+await runtime.onSurfaceMount('schedule', { patientId: '123' });
+runtime.onSurfaceUnmount('schedule');
+
+// Action fires cross-surface triggers
+await runtime.onActionComplete('checkin', 'submit-checkin', { id: 'visit-456' });
+// -> navigates to summary, feeds data, refreshes schedule
+
+const targets = runtime.getNavigationTargets('schedule');
+// -> [{ surfaceId: 'checkin', route: '/patients/:id/checkin', trigger: 'action:begin-checkin' }]
+```
+
+### ContextStore
+
+```js
+sharedContextStore.define('patient-ctx', { shape: { patient: {} } });
+sharedContextStore.update('patient-ctx', { patient: { name: 'Jane Doe' } });
+sharedContextStore.read('patient-ctx', 'patient.name');  // -> 'Jane Doe'
+
+const unsub = sharedContextStore.subscribe('patient-ctx', (data) => console.log(data));
+await sharedContextStore.join('patient-ctx', 'checkin-surface', fetchFn, params);
+sharedContextStore.leave('patient-ctx', 'checkin-surface');
+```
+
+### Association Types
+
+| Type | Direction | When to use |
+|------|-----------|-------------|
+| `routes-to` | A -> B | User navigates from A to B |
+| `feeds` | A -> B | A's output becomes B's input |
+| `shares-context` | A <-> B | Both read the same store |
+| `depends-on` | A -> B | A can't render until B is ready |
+| `triggers` | A -> B | A's action causes side effect on B |
+| `contains` | A -> B | B renders inside A |
+| `slots-into` | A -> B | A declares placement preference in B |
+
+---
+
+## Evolution Engine
+
+### Pattern Export & Import
+
+```js
+import { savePattern, importPattern, buildPatternJSON } from '@adia-ai/a2ui-compose';
+
+// Build pattern from generation
+const pattern = buildPatternJSON('login-form', {
+  components: result.messages[0].components,
+  intent: 'login form with email and password',
+  domain: 'forms',
+});
+
+// Save (downloads .json + .html in browser)
+savePattern('login-form', {
+  messages: result.messages,
+  validation: result.validation,
+  intent: 'login form',
+  canvasHTML: canvas.getHTML(),
+});
+
+// Import at runtime
+importPattern(patternJSON);  // -> { success: true, name: 'login-form' }
+```
+
+### Feedback Collection
+
+```js
+import { FeedbackCollector } from '@adia-ai/a2ui-compose';
+
+const fb = new FeedbackCollector();
+fb.initFromGeneration(execId, { intent, domain, mode, messages, validation });
+fb.collectFeedback(execId, {
+  rating: 5, intentAlignment: 5, visualQuality: 4, componentChoice: 5, userEdited: false, notes: 'Perfect',
+});
+fb.collectPatternFeedback(execId, { shouldBePattern: true, suggestedName: 'login-basic' });
+fb.exportFeedback();  // downloads training JSON
+```
+
+### Pattern Promotion
+
+```js
+import { evaluatePromotion } from '@adia-ai/a2ui-compose';
+
+const result = evaluatePromotion({
+  score: 98, feedback: { rating: 5, shouldBePattern: true },
+  alignment: { score: 0.9 }, componentTypes: ['Card', 'TextField', 'Button'], intent: 'login form',
+});
+// -> { shouldPromote: true, confidence: 0.97, suggestedName: 'login-form' }
+```
+
+Promotion criteria: `score >= 95 AND rating >= 4 AND alignment >= 0.8`.
+
+### Intent Alignment
+
+```js
+import { checkIntentAlignment } from '@adia-ai/a2ui-compose';
+
+const alignment = checkIntentAlignment('login form with email, password, submit', components);
+// -> { score: 0.83, checks: [...], gaps: ['Missing action: "submit"'] }
+```
+
+### Intent Decomposition
+
+```js
+import { decomposeIntent, composeSubtasks } from '@adia-ai/a2ui-compose';
+
+const decomp = decomposeIntent('settings page with profile, notifications, security, billing');
+// -> { shouldDecompose: true, subtasks: [{ intent: '...', label: 'Profile' }, ...], layout: { component: 'Tabs', child: 'Tab' } }
+
+const composed = composeSubtasks(decomp.layout, subtaskResults);
+```