vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-07-09 17:08:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
agent-zero/webui/components/AGENTS.md
frdel e138e33ca9 Add file-level DOX docs & update AGENTS indexes 
Add comprehensive file-level DOX documentation across the repo and update directory AGENTS.md indexes. Many new `*.py.dox.md` files were added under api, helpers, tools, plugins, extensions, webui, and other dirs to document endpoint purpose, ownership, runtime contracts, work guidance, and verification. Several AGENTS.md files were created or updated (agents profiles, api, docker, extensions, helpers, plugins, skills, webui components, etc.) to list child DOX files and clarify documentation/work guidance. Also add example and bundled profile DOX files (agent0, default, developer, hacker, researcher) and minor updates to helpers/dirty_json.py and its tests. These changes improve on-disk documentation coverage and establish the convention that each direct runtime file should have a matching `*.dox.md` describing its contracts and verification steps.
2026-06-08 12:41:53 +02:00

5.5 KiB
Raw Permalink Blame History

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.
  • 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 Reference component and store examples.
canvas/AGENTS.md Right-canvas component surface and store.
chat/AGENTS.md Chat composer, attachments, queue, navigation, and top-section components.
dropdown/AGENTS.md Shared dropdown component.
messages/AGENTS.md Message rendering helpers, action buttons, process groups, and resize behavior.
modals/AGENTS.md Modal component workflows loaded through the shared modal stack.
notifications/AGENTS.md Toasts, notification modal, icons, and notification store.
plugins/AGENTS.md Plugin settings, info, list, execution, and toggle components.
projects/AGENTS.md Project creation, selection, edit, secrets, model, skill, and file-structure components.
settings/AGENTS.md Settings shell and built-in settings subsections.
sidebar/AGENTS.md Left sidebar layout, chat/task lists, top actions, and preferences.
sync/AGENTS.md WebUI sync status component and store.
tooltips/AGENTS.md Shared tooltip store and behavior.
welcome/AGENTS.md Welcome screen, discovery cards, banners, and welcome state.