| 1 | # WebUI Components DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own self-contained Alpine.js components, component stores, and component-local styles. |
| 6 | - Keep component lifecycle, store registration, and nested component loading consistent. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Each subdirectory owns a UI feature area such as sidebar, settings, projects, notifications, plugins, canvas, or welcome screens. |
| 11 | - `*-store.js` files own component state and actions. |
| 12 | - Component HTML files own their markup, local module imports, and local scoped styles. |
| 13 | - `_examples/` contains reference implementations for component and store shape. |
| 14 | - Modal components normally live under `modals/<name>/<name>.html`; settings components live under `settings/`. |
| 15 | |
| 16 | ## Local Contracts |
| 17 | |
| 18 | - Module imports belong in the component `<head>`. |
| 19 | - Module scripts must use `type="module"` and import stores before Alpine evaluates bindings. |
| 20 | - Rendered content belongs in the component `<body>`. |
| 21 | - Wrap store-dependent content with `x-data` and a `template x-if="$store.name"` gate. |
| 22 | - A gated `<template>` must contain one root element. |
| 23 | - Keep component-specific styles in the component `<style>` block; use shared CSS only for primitives that are genuinely reused. |
| 24 | - Use CSS variables from `index.css` for color, spacing, typography, borders, and transitions. |
| 25 | - Use `x-create` for per-mount setup and `x-destroy` for cleanup; do not call long-lived store `init()` from `x-init`. |
| 26 | - Store `init()` must be idempotent and guarded when it registers global listeners, intervals, or one-time data. |
| 27 | - Store state can be read as `$store.name` in templates and through direct module imports in JavaScript; avoid `window.Alpine.store()` lookups in component code. |
| 28 | - Use `globalThis.xAttrs(element)` only for explicit parent `<x-component>` attribute inheritance. |
| 29 | - Use shared API, modal, notification, confirmation, and store helpers instead of ad hoc globals. |
| 30 | - Author Material Symbols as empty `<x-icon name="lowercase_snake_case"></x-icon>` elements. Bind changing icons through `:name`, keep accessible text on the owning control, and do not add new ligature-text spans or `x-text` icon bindings. |
| 31 | - Components that use polling directives may use `x-every-second`, `x-every-minute`, or `x-every-hour` only while mounted. |
| 32 | - Use `$confirmClick` for destructive two-click confirmations where the existing UI pattern fits. |
| 33 | - Name component files `feature-name.html` and stores `feature-store.js` or `feature-name-store.js`. |
| 34 | |
| 35 | ## Work Guidance |
| 36 | |
| 37 | - Keep component stores cohesive and avoid cross-component state mutation unless a shared store owns that state. |
| 38 | - Prefer nested `<x-component path="...">` for reusable UI pieces. |
| 39 | - Use absolute imports such as `/components/...` and `/js/...` so loader-generated module URLs resolve reliably. |
| 40 | - Preserve flex layouts through loader wrappers with `display: contents` on the specific wrapper chain when needed. |
| 41 | - Use `callJsonApi()` for JSON-in/JSON-out calls and `fetchApi()` for raw fetches that still need CSRF handling. |
| 42 | - Use `openModal(path)` for modal entry points; modal titles come from component `<title>`. |
| 43 | - Add modal footers with `data-modal-footer` so `modals.js` can move them to the pinned footer slot. |
| 44 | - Keep modal footer elements stable after load; conditional footers should not be repeatedly created and destroyed. |
| 45 | - Use `.modal-floating` only for non-blocking utility panels where page clicks must pass through; do not use it for destructive confirmations, settings, auth, import/export, or required workflows. |
| 46 | - Do not add `document.addEventListener("alpine:init", ...)` blocks inside component HTML. |
| 47 | - Do not use legacy `x-teleport` plus `.modal-overlay` modal patterns for new work. |
| 48 | - Do not introduce a second modal overlay system or manually reshape `.modal-inner`, `.modal-scroll`, or `.modal-footer-slot`. |
| 49 | - Do not hide fetch, import, or lifecycle errors with broad `.catch(() => null)` handlers; surface failures through notifications or console errors as appropriate. |
| 50 | - Do not store sensitive modal values in long-lived stores without explicit cleanup on close. |
| 51 | |
| 52 | ## Verification |
| 53 | |
| 54 | - Manually exercise the affected component in the WebUI for visible or lifecycle changes. |
| 55 | - Run targeted tests for settings, plugins, notifications, projects, state sync, or other touched flows when available. |
| 56 | - For modal changes, verify open, close button, Escape, click-outside, stacked modal, scroll, and pinned footer behavior. |
| 57 | |
| 58 | ## Child DOX Index |
| 59 | |
| 60 | Direct child DOX files: |
| 61 | |
| 62 | | Child | Scope | |
| 63 | | --- | --- | |
| 64 | | [_examples/AGENTS.md](_examples/AGENTS.md) | Reference component and store examples. | |
| 65 | | [canvas/AGENTS.md](canvas/AGENTS.md) | Right-canvas component surface and store. | |
| 66 | | [chat/AGENTS.md](chat/AGENTS.md) | Chat composer, attachments, queue, navigation, and top-section components. | |
| 67 | | [dropdown/AGENTS.md](dropdown/AGENTS.md) | Shared dropdown component. | |
| 68 | | [messages/AGENTS.md](messages/AGENTS.md) | Message rendering helpers, action buttons, process groups, and resize behavior. | |
| 69 | | [modals/AGENTS.md](modals/AGENTS.md) | Modal component workflows loaded through the shared modal stack. | |
| 70 | | [notifications/AGENTS.md](notifications/AGENTS.md) | Toasts, notification modal, icons, and notification store. | |
| 71 | | [plugins/AGENTS.md](plugins/AGENTS.md) | Plugin settings, info, list, execution, and toggle components. | |
| 72 | | [projects/AGENTS.md](projects/AGENTS.md) | Project creation, selection, edit, secrets, model, skill, and file-structure components. | |
| 73 | | [settings/AGENTS.md](settings/AGENTS.md) | Settings shell and built-in settings subsections. | |
| 74 | | [sidebar/AGENTS.md](sidebar/AGENTS.md) | Left sidebar layout, chat/task lists, top actions, and preferences. | |
| 75 | | [sync/AGENTS.md](sync/AGENTS.md) | WebUI sync status component and store. | |
| 76 | | [tooltips/AGENTS.md](tooltips/AGENTS.md) | Shared tooltip store and behavior. | |
| 77 | | [welcome/AGENTS.md](welcome/AGENTS.md) | Welcome screen, discovery cards, banners, and welcome state. | |