Spaces:
Running
Running
| # WebUI Components DOX | |
| ## Purpose | |
| - Own self-contained Alpine.js components, component stores, and component-local styles. | |
| - Keep component lifecycle, store registration, and nested component loading consistent. | |
| ## Ownership | |
| - Each subdirectory owns a UI feature area such as sidebar, settings, projects, notifications, plugins, canvas, or welcome screens. | |
| - `*-store.js` files own component state and actions. | |
| - Component HTML files own their markup, local module imports, and local scoped styles. | |
| - `_examples/` contains reference implementations for component and store shape. | |
| - Modal components normally live under `modals/<name>/<name>.html`; settings components live under `settings/`. | |
| ## Local Contracts | |
| - Module imports belong in the component `<head>`. | |
| - Module scripts must use `type="module"` and import stores before Alpine evaluates bindings. | |
| - Rendered content belongs in the component `<body>`. | |
| - Wrap store-dependent content with `x-data` and a `template x-if="$store.name"` gate. | |
| - A gated `<template>` must contain one root element. | |
| - Keep component-specific styles in the component `<style>` block; use shared CSS only for primitives that are genuinely reused. | |
| - Use CSS variables from `index.css` for color, spacing, typography, borders, and transitions. | |
| - Use `x-create` for per-mount setup and `x-destroy` for cleanup; do not call long-lived store `init()` from `x-init`. | |
| - Store `init()` must be idempotent and guarded when it registers global listeners, intervals, or one-time data. | |
| - 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. | |
| - Use `globalThis.xAttrs(element)` only for explicit parent `<x-component>` attribute inheritance. | |
| - Use shared API, modal, notification, confirmation, and store helpers instead of ad hoc globals. | |
| - 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. | |
| - Components that use polling directives may use `x-every-second`, `x-every-minute`, or `x-every-hour` only while mounted. | |
| - Use `$confirmClick` for destructive two-click confirmations where the existing UI pattern fits. | |
| - Name component files `feature-name.html` and stores `feature-store.js` or `feature-name-store.js`. | |
| ## Work Guidance | |
| - Keep component stores cohesive and avoid cross-component state mutation unless a shared store owns that state. | |
| - Prefer nested `<x-component path="...">` for reusable UI pieces. | |
| - Use absolute imports such as `/components/...` and `/js/...` so loader-generated module URLs resolve reliably. | |
| - Preserve flex layouts through loader wrappers with `display: contents` on the specific wrapper chain when needed. | |
| - Use `callJsonApi()` for JSON-in/JSON-out calls and `fetchApi()` for raw fetches that still need CSRF handling. | |
| - Use `openModal(path)` for modal entry points; modal titles come from component `<title>`. | |
| - Add modal footers with `data-modal-footer` so `modals.js` can move them to the pinned footer slot. | |
| - Keep modal footer elements stable after load; conditional footers should not be repeatedly created and destroyed. | |
| - 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. | |
| - Do not add `document.addEventListener("alpine:init", ...)` blocks inside component HTML. | |
| - Do not use legacy `x-teleport` plus `.modal-overlay` modal patterns for new work. | |
| - Do not introduce a second modal overlay system or manually reshape `.modal-inner`, `.modal-scroll`, or `.modal-footer-slot`. | |
| - Do not hide fetch, import, or lifecycle errors with broad `.catch(() => null)` handlers; surface failures through notifications or console errors as appropriate. | |
| - Do not store sensitive modal values in long-lived stores without explicit cleanup on close. | |
| ## Verification | |
| - Manually exercise the affected component in the WebUI for visible or lifecycle changes. | |
| - Run targeted tests for settings, plugins, notifications, projects, state sync, or other touched flows when available. | |
| - For modal changes, verify open, close button, Escape, click-outside, stacked modal, scroll, and pinned footer behavior. | |
| ## Child DOX Index | |
| Direct child DOX files: | |
| | Child | Scope | | |
| | --- | --- | | |
| | [_examples/AGENTS.md](_examples/AGENTS.md) | Reference component and store examples. | | |
| | [canvas/AGENTS.md](canvas/AGENTS.md) | Right-canvas component surface and store. | | |
| | [chat/AGENTS.md](chat/AGENTS.md) | Chat composer, attachments, queue, navigation, and top-section components. | | |
| | [dropdown/AGENTS.md](dropdown/AGENTS.md) | Shared dropdown component. | | |
| | [messages/AGENTS.md](messages/AGENTS.md) | Message rendering helpers, action buttons, process groups, and resize behavior. | | |
| | [modals/AGENTS.md](modals/AGENTS.md) | Modal component workflows loaded through the shared modal stack. | | |
| | [notifications/AGENTS.md](notifications/AGENTS.md) | Toasts, notification modal, icons, and notification store. | | |
| | [plugins/AGENTS.md](plugins/AGENTS.md) | Plugin settings, info, list, execution, and toggle components. | | |
| | [projects/AGENTS.md](projects/AGENTS.md) | Project creation, selection, edit, secrets, model, skill, and file-structure components. | | |
| | [settings/AGENTS.md](settings/AGENTS.md) | Settings shell and built-in settings subsections. | | |
| | [sidebar/AGENTS.md](sidebar/AGENTS.md) | Left sidebar layout, chat/task lists, top actions, and preferences. | | |
| | [sync/AGENTS.md](sync/AGENTS.md) | WebUI sync status component and store. | | |
| | [tooltips/AGENTS.md](tooltips/AGENTS.md) | Shared tooltip store and behavior. | | |
| | [welcome/AGENTS.md](welcome/AGENTS.md) | Welcome screen, discovery cards, banners, and welcome state. | | |