backlog-ui-framework

name	backlog-ui-framework
description	Reactive web component framework guidelines for the backlog viewer. This skill should be used when writing, reviewing, migrating, or refactoring components in `packages/viewer/components/` that use `@nisli/core`. Triggers on tasks involving component creation, signal-based state, template rendering, dependency injection, emitter events, or query-based data loading.
license	MIT
metadata	{"author":"backlog-team","version":"1.0.0"}

Backlog UI Framework — Agent Skill

Comprehensive guide for building reactive web components using @nisli/core. Contains rules across 9 categories covering component authoring, reactivity, templates, dependency injection, events, data loading, error handling, migration, and testing.

When to Apply

Reference these guidelines when:

• Creating new web components in viewer/components/
• Migrating existing HTMLElement-based components to the reactive framework
• Writing or reviewing signal-based reactive state
• Implementing html tagged templates with bindings and @event handlers
• Using inject() / provide() for dependency injection
• Setting up query() for declarative data loading
• Wiring typed Emitter events between components
• Reviewing code for memory leaks, XSS, or lifecycle issues
• Writing tests for framework components

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Component Authoring	CRITICAL	comp-
2	Signals & Reactivity	CRITICAL	signal-
3	Template Engine	HIGH	tmpl-
4	Dependency Injection	HIGH	di-
5	Typed Emitters	MEDIUM-HIGH	emitter-
6	Declarative Data Loading	MEDIUM-HIGH	query-
7	Error Handling & Resilience	MEDIUM	error-
8	Migration & Interop	MEDIUM	migration-
9	Testing	LOW-MEDIUM	test-

Quick Reference

1. Component Authoring (CRITICAL)

• comp-setup-sync - Setup function MUST be synchronous; capture services sync, use them async
• comp-props-signals - All props are Signal<T> in setup; factories accept T | Signal<T> inputs
• comp-factory-composition - ALL custom elements MUST use factory composition; HTML tag syntax is ONLY for native elements (div, span, button)
• comp-html-for-vanilla - HTML tag syntax (<tag>) is ONLY for native HTML elements; never for custom elements
• comp-no-this - No this in components; use pure functions with props and host
• comp-no-innerhtml - Never use innerHTML; use html tagged templates for targeted DOM patching
• comp-host-escape-hatch - host is the second param; use it only for imperative DOM access
• comp-no-class-authoring - Never extend HTMLElement directly for new components; use component()
• comp-host-attrs - Use second factory arg { class: '...' } for host-level CSS classes (ADR 0009)
• comp-prop-input - Factory props accept T | Signal<T> — plain values are auto-wrapped (ADR 0009)

2. Signals & Reactivity (CRITICAL)

• signal-value-read - Always use .value in JS code; signals are implicit in html templates
• signal-immutable-writes - Mutating objects doesn't trigger updates; assign a new reference
• signal-computed-derived - Use computed() for derived state, not manual sync in effects
• signal-effect-side-effects - Effects are for side effects only (DOM, network, localStorage)
• signal-coalesced-writes - Multiple synchronous writes coalesce automatically; use flush() only when synchronous effects are needed
• signal-no-async-in-setup-context - inject(), effect(), emitter.on() must be called synchronously in setup
• signal-untrack - Use untrack() to read signals without tracking them as dependencies (ADR 0009)
• signal-conditional-deps - Dependencies are re-tracked on every run; conditional reads track correctly
• signal-equality-object-is - Signal equality uses Object.is(), not ===

3. Template Engine (HIGH)

• tmpl-implicit-signals - Write ${count} not ${count.value} in templates
• tmpl-event-colocated - Use @click=${handler} on the element, not detached listeners
• tmpl-event-modifiers - Use .stop, .prevent, .once, .enter, .escape modifiers
• tmpl-class-directive - Use class:name=${signal} for conditional classes, not ternary soup
• tmpl-class-attribute-safe - Reactive class attributes use classList, safe alongside class:name directives (ADR 0007)
• tmpl-computed-views - Use computed() for multi-branch conditional rendering
• tmpl-when-simple - Use when() only for simple single-branch toggles
• tmpl-xss-safe - Text bindings use textNode.data; never parse user input as HTML
• tmpl-comment-markers - Framework uses <!--bk-N--> markers; avoid this pattern in content

4. Dependency Injection (HIGH)

• di-class-as-token - Use the class itself as the injection token; no createToken() for services
• di-auto-singleton - inject(Class) auto-creates a singleton; no registration needed
• di-provide-for-overrides - provide() is for testing and subtree overrides only
• di-sync-only - inject() must be called synchronously during setup
• di-bootstrap-eager - Bootstrap services (SSE, etc.) must be eagerly created in main.ts
• di-no-failed-cache - Failed construction is never cached; next inject() retries

5. Typed Emitters (MEDIUM-HIGH)

• emitter-typed-events - Extend Emitter<T> with a typed event map; no CustomEvent strings
• emitter-inject-singleton - Inject emitters via DI; they are auto-singleton services
• emitter-auto-dispose - on() inside component context auto-disposes on disconnect
• emitter-to-signal - Use toSignal() to bridge events into the reactive system
• emitter-copy-on-emit - emit() iterates a copy; safe to unsubscribe during callback

6. Declarative Data Loading (MEDIUM-HIGH)

• query-key-function - First arg is a key function returning an array; signals inside are tracked
• query-cache-key - Same cache key = same cached result; design keys for proper deduplication
• query-generation-guard - Stale responses are discarded via generation counter; no race conditions
• query-enabled-guard - Use enabled option to conditionally skip fetches
• query-invalidate-prefix - invalidate(['tasks']) matches all keys starting with ['tasks']
• query-disposed-check - All async writes check !disposed before updating signals

7. Error Handling & Resilience (MEDIUM)

• error-setup-boundary - Setup errors render a fallback; sibling components unaffected
• error-effect-survives - Effect errors are logged, not thrown; the effect stays alive
• error-effect-loop-guard - Effects that re-run >100 times in 2s are auto-disposed (ADR 0009)
• error-handler-wrapped - @event handlers are try/caught; broken handlers don't crash the UI
• error-cleanup-swallowed - Cleanup/disposer errors are swallowed; disposal always completes
• error-circular-detection - Both computed and DI have circular dependency detection

8. Migration & Interop (MEDIUM)

• migration-same-tag - Keep the same custom element tag name after migration
• migration-same-events - Dispatch document CustomEvents until all listeners migrate
• migration-same-api - Maintain public method signatures via (host as any).method = ...
• migration-hack-tags - Tag every backward-compat hack: HACK:EXPOSE, HACK:DOC_EVENT, HACK:REF
• migration-auto-resolve - Template auto-resolves _setProp vs setAttribute; class uses classList (ADR 0007)

9. Testing (LOW-MEDIUM)

• test-flush-effects - Call flushEffects() after signal changes to run pending effects
• test-cascading-flush - Cascading effects need multiple flushEffects() calls
• test-provide-mock - Use provide(Class, () => mock) before inject() in tests
• test-reset-injector - Call resetInjector() between tests to clear singleton cache
• test-query-client-isolated - Provide a fresh QueryClient in tests for cache isolation

How to Use

Read the full compiled document for detailed explanations and code examples: AGENTS.md

Each section contains:

• The invariant or rule explained
• Why it matters (the bug it prevents)
• Incorrect code example with explanation
• Correct code example with explanation
• References to framework source files