120 lines
6.3 KiB
Markdown
120 lines
6.3 KiB
Markdown
---
|
|
name: semantics-frontend
|
|
description: Core protocol for Svelte 5 (Runes) Components, UX State Machines, and Visual-Interactive Validation.
|
|
---
|
|
|
|
# [DEF:Std:Semantics:Frontend]
|
|
# @COMPLEXITY 5
|
|
# @PURPOSE Canonical GRACE-Poly protocol for Svelte 5 (Runes) Components, UX State Machines, and Project UI Architecture backed by Python APIs.
|
|
# @RELATION DEPENDS_ON ->[Std:Semantics:Core]
|
|
# @INVARIANT Frontend components MUST be verifiable by an automated GUI Judge Agent (e.g., Playwright).
|
|
# @INVARIANT Use Tailwind CSS exclusively. Native `fetch` is forbidden.
|
|
|
|
## 0. SVELTE 5 PARADIGM & UX PHILOSOPHY
|
|
- **STRICT RUNES ONLY:** You MUST use Svelte 5 Runes for reactivity: `$state()`, `$derived()`, `$effect()`, `$props()`, `$bindable()`.
|
|
- **FORBIDDEN SYNTAX:** Do NOT use `export let`, `on:event` (use `onclick`), or the legacy `$:` reactivity.
|
|
- **UX AS A STATE MACHINE:** Every component is a Finite State Machine (FSM). You MUST declare its visual states in the contract BEFORE writing implementation.
|
|
- **RESOURCE-CENTRIC:** Navigation and actions revolve around Resources. Every action MUST be traceable.
|
|
- **PYTHON BACKEND INTEGRATION:** All API calls target a Python backend. Use the internal `requestApi` / `fetchApi` wrappers. The backend uses FastAPI or similar Python web frameworks.
|
|
|
|
## I. PROJECT ARCHITECTURAL INVARIANTS
|
|
You are bound by strict repository-level design rules. Violating these causes instant PR rejection.
|
|
1. **Styling:** Tailwind CSS utility classes are MANDATORY. Minimize scoped `<style>`. If custom CSS is absolutely necessary, use `@apply` directives.
|
|
2. **Localization:** All user-facing text MUST use the `$t` store from `src/lib/i18n`. No hardcoded UI strings.
|
|
3. **API Layer:** You MUST use the internal `requestApi` / `fetchApi` wrappers. Using native `fetch()` is a fatal violation. The backend API is written in Python (FastAPI, Django, or Flask).
|
|
|
|
## II. UX CONTRACTS (STRICT UI BEHAVIOR)
|
|
Every component MUST define its behavioral contract in the header.
|
|
- **`@UX_STATE:`** Maps FSM state names to visual behavior.
|
|
*Example:* `@UX_STATE Loading -> Spinner visible, btn disabled, aria-busy=true`.
|
|
- **`@UX_FEEDBACK:`** Defines external system reactions (Toast, Shake, RedBorder).
|
|
- **`@UX_RECOVERY:`** Defines the user's recovery path from errors (e.g., `Retry button`, `Clear Input`).
|
|
- **`@UX_REACTIVITY:`** Explicitly declares the state source.
|
|
*Example:* `@UX_REACTIVITY: Props -> $props(), LocalState -> $state(...)`.
|
|
- **`@UX_TEST:`** Defines the interaction scenario for the automated Judge Agent.
|
|
*Example:* `@UX_TEST: Idle -> {click: submit, expected: Loading}`.
|
|
|
|
## III. STATE MANAGEMENT & STORE TOPOLOGY
|
|
- **Subscription:** Use the `$` prefix for reactive store access (e.g., `$sidebarStore`).
|
|
- **Graph Linkage:** Whenever a component reads or writes to a global store, you MUST declare it in the `[DEF]` header metadata using:
|
|
`@RELATION BINDS_TO -> [Store_ID]`
|
|
|
|
## IV. IMPLEMENTATION & ACCESSIBILITY (A11Y)
|
|
1. **Event Handling:** Use native attributes (e.g., `onclick={handler}`).
|
|
2. **Transitions:** Use Svelte's built-in transitions for UI state changes to ensure smooth UX.
|
|
3. **Async Logic:** Any async task (API calls to Python backend) MUST be handled within a `try/catch` block that explicitly triggers an `@UX_STATE` transition to `Error` on failure and provides `@UX_FEEDBACK` (e.g., Toast).
|
|
4. **A11Y:** Ensure proper ARIA roles (`aria-busy`, `aria-invalid`) and keyboard navigation. Use semantic HTML (`<nav>`, `<main>`).
|
|
|
|
## V. LOGGING (MOLECULAR TOPOLOGY FOR UI)
|
|
Frontend logging bridges the gap between your logic and the Judge Agent's vision system.
|
|
- **[EXPLORE]:** Log branching user paths or caught UI errors.
|
|
- **[REASON]:** Log the intent *before* an API invocation to the Python backend.
|
|
- **[REFLECT]:** Log visual state updates (e.g., "Toast displayed", "Drawer opened").
|
|
- **Syntax:** `console.info("[ComponentID][MARKER] Message", {extra_data})` — Prefix MUST be manually applied.
|
|
|
|
## VI. PYTHON BACKEND INTEGRATION PATTERNS
|
|
When implementing API interactions in Svelte components:
|
|
1. **Request wrappers:** Always use `requestApi(path, options)` or `fetchApi(path, options)` — never raw `fetch()`.
|
|
2. **DTO alignment:** Frontend request/response shapes MUST match the Python backend's Pydantic models or dataclass schemas.
|
|
3. **Error handling:** Python backend may return structured error responses (e.g., `{"detail": "Validation error", "errors": [...]}`). Parse and surface these to the user via `@UX_FEEDBACK`.
|
|
4. **Authentication:** Use the centralized auth store. Python backend tokens (JWT, session cookies) are managed transparently by the API wrappers.
|
|
|
|
## VII. CANONICAL SVELTE 5 COMPONENT TEMPLATE
|
|
You MUST strictly adhere to this AST boundary format:
|
|
|
|
```html
|
|
<!-- [DEF:ComponentName:Component] -->
|
|
<script>
|
|
/**
|
|
* @COMPLEXITY [1-5]
|
|
* @PURPOSE Brief description of the component purpose.
|
|
* @LAYER UI
|
|
* @SEMANTICS list, of, keywords
|
|
* @RELATION DEPENDS_ON -> [OtherComponent]
|
|
* @RELATION BINDS_TO -> [GlobalStore]
|
|
*
|
|
* @UX_STATE Idle -> Default view.
|
|
* @UX_STATE Loading -> Button disabled, spinner active.
|
|
* @UX_FEEDBACK Toast notification on success/error.
|
|
* @UX_REACTIVITY Props -> $props(), State -> $state().
|
|
* @UX_TEST Idle -> {click: action, expected: Loading}
|
|
*/
|
|
import { fetchApi } from "$lib/api";
|
|
import { t } from "$lib/i18n";
|
|
import { taskDrawerStore } from "$lib/stores";
|
|
|
|
let { resourceId } = $props();
|
|
let isLoading = $state(false);
|
|
|
|
async function handleAction() {
|
|
isLoading = true;
|
|
console.info("[ComponentName][REASON] Opening task drawer for resource", { resourceId });
|
|
try {
|
|
taskDrawerStore.open(resourceId);
|
|
// Calls Python backend endpoint (e.g., FastAPI route)
|
|
await fetchApi(`/api/resource/${resourceId}/process`);
|
|
console.info("[ComponentName][REFLECT] Process completed successfully");
|
|
} catch (e) {
|
|
console.error("[ComponentName][EXPLORE] Action failed", { error: e });
|
|
} finally {
|
|
isLoading = false;
|
|
}
|
|
}
|
|
</script>
|
|
|
|
<div class="flex flex-col p-4 bg-white rounded-lg shadow-md">
|
|
<button
|
|
class="btn-primary"
|
|
onclick={handleAction}
|
|
disabled={isLoading}
|
|
aria-busy={isLoading}
|
|
>
|
|
{#if isLoading} <span class="spinner"></span> {/if}
|
|
{$t('actions.start')}
|
|
</button>
|
|
</div>
|
|
<!--[/DEF:ComponentName:Component] -->
|
|
```
|
|
# [/DEF:Std:Semantics:Frontend]
|
|
**[SYSTEM: END OF FRONTEND DIRECTIVE. ENFORCE STRICT UI COMPLIANCE.]**
|