micro-contracts 0.12.3 → 0.14.0

package/docs/screen-spec.md

@@ -0,0 +1,547 @@
+# Screen Spec — Frontend Screen Contracts in OpenAPI
+
+The Screen Spec feature repurposes standard OpenAPI constructs (`paths`, `schemas`, `links`, `security`) to declaratively define **frontend screen contracts** — bridging the API layer and UI components. A single YAML file drives frontend types, test scaffolding, and quality analysis.
+
+```
+Screen Spec (OpenAPI YAML)
+  ├── micro-contracts generate ──┬── ViewModel Types (type-safe)
+  │                              ├── Navigation Map (typed routing)
+  │                              └── Event Hooks (typed analytics)
+  ├── E2E scaffold ─── Playwright test stubs + coverage
+  └── Data lineage ─── ViewModel → API → DB traceability
+```
+
+> **Important**: This is NOT "auto-generated UI from schema" but rather **screen-level contract definition**, which aligns with micro-contracts' "Contract-first vertical slices" philosophy.
+
+---
+
+## The HTTP-Screen Analogy
+
+Standard OpenAPI semantics map directly to screen specification concepts:
+
+| OpenAPI Construct      | API Usage              | Screen Spec Usage                                       |
+| ---------------------- | ---------------------- | ------------------------------------------------------- |
+| `paths: /home`         | Endpoint               | React/Vue route                                         |
+| `GET /home`            | Fetch resource         | **Render screen** — what the user sees                  |
+| `POST /home`           | Create/modify resource | **User action** — what the user can do                  |
+| `parameters`           | Filter/identify        | **Screen init params** — route/query params             |
+| `responses.200.schema` | Response shape         | **ViewModel** — typed interface for the screen          |
+| `requestBody`          | Submitted data shape   | **Action payload** — typed user action interface        |
+| `links`                | HATEOAS related resources | **Forward navigation** — statically known screen targets |
+| `security`             | Auth requirement       | **Auth guard** — does the screen require login?         |
+
+All standard OpenAPI tooling works out of the box: linters, documentation generators, and diff tools.
+
+---
+
+## Required Extensions (`x-*`)
+
+Only concerns with **no OpenAPI-native representation** need extensions:
+
+| Extension           | Required | Purpose                                   | Justification                                                   |
+| ------------------- | -------- | ----------------------------------------- | --------------------------------------------------------------- |
+| `x-screen-const`    | Yes*     | Stable constant name (e.g., `HOME`)       | No OpenAPI equivalent for generated symbol names                |
+| `x-screen-id`       | Yes      | Traceability ID (e.g., `SCR-001`)         | Links to requirements and E2E annotations                       |
+| `x-screen-name`     | Yes*     | Generated symbol name (e.g., `HomePage`)  | Drives `use{Name}Events()`, `wrap{Name}ViewModel()`            |
+| `x-back-navigation` | No       | History-based back navigation support     | `links` only cover forward navigation with known targets        |
+| `x-event`           | No       | Inline analytics event declaration        | Type auto-inferred from placement; supports string, object, `$ref` |
+| `x-interactions`    | No       | In-page interaction bindings              | Declares non-navigation UI interactions (swipe, selection, etc.) |
+| `x-view-model`      | No       | Explicit ViewModel schema name            | Alternative to auto-inference from `$ref`                       |
+| `x-view-props`      | No       | ViewProps interface name                  | For framework-specific wrapper generation                       |
+
+**Deprecated extensions:**
+
+| Extension   | Status | Migration |
+| ----------- | ------ | --------- |
+| `x-events`  | Deprecated (v0.14) — removed in v0.15 | Replace with inline `x-event` on GET, links, actions, or interactions |
+
+\* When `x-screen-id` is present, `x-screen-const` and `x-screen-name` are required (enforced by lint).
+
+---
+
+## Quick Start
+
+### 1. Initialize a Screen Module
+
+```bash
+npx micro-contracts init myScreens --screens
+```
+
+This command generates:
+- `spec/myScreens/openapi/myScreens.yaml` — Starter screen spec (2-screen scaffold)
+- `spec/default/templates/screen-navigation.hbs` — Navigation map template
+- `spec/default/templates/screen-events.hbs` — Event hooks template
+- `micro-contracts.config.yaml` — Module config with `screen: true`
+
+### 2. Edit the Screen Spec
+
+Edit `spec/myScreens/openapi/myScreens.yaml` to add your screen definitions.
+
+### 3. Generate Code
+
+```bash
+npx micro-contracts generate
+```
+
+Generated artifacts:
+- `packages/contract/myScreens/schemas/types.ts` — ViewModel TypeScript types
+- `frontend/src/screens/navigation.generated.ts` — Navigation map
+- `frontend/src/screens/events.generated.ts` — Analytics event hooks
+
+---
+
+## Configuration
+
+### `micro-contracts.config.yaml`
+
+Screen modules are enabled with the `screen: true` flag:
+
+```yaml
+modules:
+  myScreens:
+    openapi: spec/myScreens/openapi/myScreens.yaml
+    screen: true
+    outputs:
+      frontend-api:
+        enabled: false      # Not needed for screen modules
+      screen-navigation:
+        output: frontend/src/screens/navigation.generated.ts
+        template: screen-navigation.hbs
+      screen-events:
+        output: frontend/src/screens/events.generated.ts
+        template: screen-events.hbs
+```
+
+Effects of `screen: true`:
+- Suppresses `x-micro-contracts-service` / `x-micro-contracts-method` lint warnings
+- Populates `TemplateContext.screens` with pre-parsed `ScreenContext[]`
+- Enables screen-specific lint rules (`x-screen-id` requires `x-screen-const`/`x-screen-name`)
+
+---
+
+## Screen Spec YAML Structure
+
+### Basic Example (inline `x-event`)
+
+```yaml
+openapi: '3.1.0'
+info:
+  title: App Screen Specification
+  version: '1.0.0'
+  description: Screen contracts — not a server API
+servers:
+  - url: /
+    description: Screen routes (client-side)
+
+paths:
+  /home:
+    get:
+      operationId: renderHomePage
+      security: [{session: []}]
+      x-screen-const: HOME
+      x-screen-id: SCR-001
+      x-screen-name: HomePage
+      x-back-navigation: false
+      x-event: home_view                   # → type: "screen_view" (auto-inferred)
+      x-interactions:
+        - name: daySwipe
+          description: Horizontal day-by-day swipe
+          x-event:
+            name: day_swipe
+            params:
+              direction: string
+      summary: Render home page
+      responses:
+        '200':
+          description: Home page ViewModel
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HomePageViewModel'
+          links:
+            goToSettings:
+              operationId: renderSettingsPage
+            goToDetail:
+              operationId: renderDetailPage
+              x-event:                      # → type: "user_action" (auto-inferred)
+                $ref: '#/components/x-event-defs/itemTap'
+    post:
+      operationId: actionHomePage
+      x-event: mode_switch                  # → type: "user_action" (auto-inferred)
+      responses:
+        '200':
+          description: OK
+
+components:
+  x-event-defs:
+    itemTap:
+      name: item_tap
+      params:
+        itemId: string
+```
+
+### `x-event` — Three Forms
+
+```yaml
+# 1. String form (most common)
+x-event: home_view
+
+# 2. Object form (type override / extra params)
+x-event:
+  name: oauth_callback_result
+  type: system
+  params:
+    success: boolean
+
+# 3. $ref form (reusable definitions)
+x-event:
+  $ref: '#/components/x-event-defs/itemTap'
+```
+
+`$ref` resolves to `#/components/x-event-defs/*` (local references only).
+
+### `x-event` Placement and Type Inference
+
+| Placement | Inferred `type` | Params auto-derivation |
+|-----------|-----------------|------------------------|
+| `get` operation | `screen_view` | From path parameters (e.g., `/calendar/{yearMonth}` → `{ yearMonth: string }`) |
+| `responses.200.links.*` | `user_action` | From target route's path parameters |
+| `post` / `put` / `patch` / `delete` | `user_action` | None — specify explicitly in `params` |
+| `x-interactions.*` | `user_action` | None — specify explicitly in `params` |
+
+`type` can be overridden explicitly in object form. Recognized values: `screen_view`, `user_action`, `system`.
+
+### `x-interactions`
+
+Declares in-page interaction bindings that don't map to HTTP operations or link navigations.
+
+```yaml
+x-interactions:
+  - name: daySwipe
+    description: Horizontal day-by-day swipe navigation
+    x-event:
+      name: day_swipe
+      params:
+        direction: string
+  - name: itemSelect
+    description: Select an item from choices
+    x-event:
+      name: item_select
+      params:
+        itemId: string
+    module: '@ui/selector'    # project-specific field (passed through)
+```
+
+Required field: `name`. All other fields are optional. Project-specific fields (e.g., `module`, `factory`) are passed through to templates in `extras`.
+
+### Reusable Event Definitions
+
+```yaml
+components:
+  x-event-defs:
+    itemTap:
+      name: item_tap
+      params:
+        itemId: string
+```
+
+Referenced with `$ref: '#/components/x-event-defs/itemTap'` from any `x-event` placement.
+
+### Field Reference
+
+**`operationId`** — Unique identifier referenced by generated code. The naming convention `render` + screen name + `Page` is recommended.
+
+**`security`** — Auth guard. `[{session: []}]` means authentication is required; `[]` means no authentication needed.
+
+**`x-screen-const`** — SCREAMING_SNAKE_CASE name used for constant access like `SCREENS.HOME`.
+
+**`x-screen-id`** — Unique ID for requirements and test traceability. The format `SCR-{domain}-{number}` is recommended.
+
+**`x-screen-name`** — PascalCase name for generated symbols like `useHomePageEvents()`.
+
+**`x-back-navigation`** — When `true`, declares that the screen supports browser back or UI back button navigation. Unlike forward navigation covered by `links`, the back destination is determined at runtime.
+
+**`x-event`** — Inline analytics event. Type is auto-inferred from placement. Supports string, object (with `name`, `type?`, `params?`), and `$ref` forms. Params are auto-derived from path parameters for `get` and `links` placements; for actions and interactions, specify params explicitly.
+
+**`x-interactions`** — Array of in-page interaction bindings. Each entry has `name` (required), `description` (recommended), optional `x-event`, and any project-specific fields.
+
+**`responses.200.links`** — Forward navigation targets. References target screens by `operationId`. Each link may have an optional `x-event`.
+
+**`POST` / `PUT` / `PATCH` / `DELETE` operations** — Mutation operations on the same path define user actions (form submissions, button taps, deletions, etc.). Each may have an optional `x-event`.
+
+---
+
+## TemplateContext.screens
+
+When `screen: true` is enabled, `TemplateContext` includes a pre-parsed `screens: ScreenContext[]`. This eliminates the need to iterate over deeply nested `spec.paths` in templates.
+
+```typescript
+interface ScreenContext {
+  route: string;                         // '/home'
+  screenConst: string;                   // 'HOME'
+  screenId: string;                      // 'SCR-001'
+  screenName: string;                    // 'HomePage'
+  operationId: string;                   // 'renderHomePage'
+  supportsBack: boolean;                 // false
+  viewModelSchema: string;               // 'HomePageViewModel'
+  links: ScreenLink[];                   // forward navigation targets
+  requiresAuth: boolean;                 // true
+  pathParams: string[];                  // ['yearMonth'] for /calendar/{yearMonth}
+
+  // Inline x-event (v0.14+)
+  screenEvent?: InlineEventDefinition;   // GET x-event (screen_view)
+  actions: ScreenAction[];               // post/put/patch/delete with events
+  interactions: ScreenInteraction[];     // x-interactions with events
+
+  /** @deprecated Use screenEvent / links[].event / actions[].event instead */
+  events: ScreenEventDefinition[];       // legacy x-events (backward compat)
+}
+
+interface ScreenLink {
+  name: string;                          // 'goToSettings'
+  targetRoute: string;                   // '/settings'
+  targetOperationId: string;             // 'renderSettingsPage'
+  event?: InlineEventDefinition;         // link x-event (user_action)
+}
+
+interface ScreenAction {
+  method: string;                        // 'post', 'put', 'patch', 'delete'
+  operationId: string;                   // 'actionHomePage'
+  summary: string;
+  schemaRef: string;                     // request body $ref name
+  event?: InlineEventDefinition;         // action x-event (user_action)
+}
+
+interface ScreenInteraction {
+  name: string;                          // 'daySwipe'
+  description: string;                   // 'Horizontal day-by-day swipe'
+  event?: InlineEventDefinition;         // interaction x-event (user_action)
+  extras: Record<string, unknown>;       // project-specific fields
+}
+
+interface InlineEventDefinition {
+  name: string;                          // 'home_view'
+  type: string;                          // 'screen_view' | 'user_action' | 'system'
+  params?: Record<string, string>;       // auto-derived or explicit
+}
+```
+
+### Template Usage Comparison
+
+**Using `screens[]` (recommended):**
+
+```handlebars
+{{#each screens}}
+  {{screenConst}}: { id: '{{screenId}}', route: '{{route}}' },
+{{/each}}
+```
+
+**Iterating `spec.paths` directly (not recommended):**
+
+```handlebars
+{{#each spec.paths}}
+{{#each this}}
+{{#unless (eq @key "parameters")}}
+{{#unless (eq @key "servers")}}
+{{#unless (eq @key "summary")}}
+{{#unless (eq @key "description")}}
+{{#if this.x-screen-id}}
+  {{this.x-screen-const}}: { id: '{{this.x-screen-id}}', route: '{{@../key}}' },
+{{/if}}
+{{/unless}}
+{{/unless}}
+{{/unless}}
+{{/unless}}
+{{/each}}
+{{/each}}
+```
+
+---
+
+## Default Templates
+
+### screen-navigation.hbs
+
+Generates a navigation map. Outputs a `SCREENS` constant and `*_PAGE_LINKS` for each screen.
+
+Example output:
+
+```typescript
+const _OP_ROUTES = {
+  renderHomePage: '/home',
+  renderSettingsPage: '/settings',
+  renderChatPage: '/chat',
+} as const;
+
+export const SCREENS = {
+  HOME: { id: 'SCR-001' as const, route: _OP_ROUTES.renderHomePage, supportsBack: false } as const,
+  SETTINGS: { id: 'SCR-002' as const, route: _OP_ROUTES.renderSettingsPage, supportsBack: true } as const,
+} as const;
+
+export const HOME_PAGE_LINKS = {
+  goToSettings: _OP_ROUTES.renderSettingsPage,
+  goToChat: _OP_ROUTES.renderChatPage,
+} as const;
+```
+
+### screen-events.hbs (inline x-event)
+
+Generates analytics event hooks using the new inline `x-event` structure. Templates can use `screenEvent`, `links[].event`, `actions[].event`, and `interactions[].event`.
+
+Example template:
+
+```handlebars
+{{#each screens}}
+{{#if screenEvent}}
+export function use{{screenName}}ScreenView() {
+  const tracked = useRef(false);
+  useEffect(() => {
+    if (tracked.current) return;
+    tracked.current = true;
+    trackEvent('{{screenEvent.name}}', '{{screenEvent.type}}', {});
+  }, []);
+}
+{{/if}}
+
+{{#each links}}
+{{#if this.event}}
+export function navigateVia{{capitalize this.name}}(
+  {{eventParamsSignature this.event.params}}
+) {
+  trackEvent('{{this.event.name}}', '{{this.event.type}}',
+    { {{#each this.event.params}}{{@key}}{{#unless @last}}, {{/unless}}{{/each}} });
+  return '{{this.targetRoute}}';
+}
+{{/if}}
+{{/each}}
+
+{{#each actions}}
+{{#if this.event}}
+export function track{{capitalize this.operationId}}Event(
+  {{eventParamsSignature this.event.params}}
+) {
+  trackEvent('{{this.event.name}}', '{{this.event.type}}',
+    { {{#each this.event.params}}{{@key}}{{#unless @last}}, {{/unless}}{{/each}} });
+}
+{{/if}}
+{{/each}}
+{{/each}}
+```
+
+### Handlebars Helpers
+
+| Helper | Description | Example |
+|--------|-------------|---------|
+| `hasEvent` | Returns `true` if the screen has any events (screenEvent, link events, action events, or interaction events) | `{{#if (hasEvent this)}}...{{/if}}` |
+| `eventParamsSignature` | Expands params map to TypeScript argument list | `{{eventParamsSignature screenEvent.params}}` → `yearMonth: string` |
+
+### Legacy screen-events.hbs (deprecated x-events)
+
+The legacy `x-events` array is still available in `events` for backward compatibility:
+
+```typescript
+export function useHomePageEvents() {
+  return {
+    trackView: () =>
+      trackEvent('home_view', 'screen_view', {}),
+    trackSignOut: () =>
+      trackEvent('sign_out', 'user_action', {}),
+  };
+}
+```
+
+---
+
+## Lint Rules
+
+`micro-contracts lint` performs the following screen-specific checks:
+
+| Code                             | Level   | Description                                                    |
+| -------------------------------- | ------- | -------------------------------------------------------------- |
+| `SCREEN_MISSING_CONST`           | Error   | `x-screen-id` present but `x-screen-const` missing            |
+| `SCREEN_MISSING_NAME`            | Error   | `x-screen-id` present but `x-screen-name` missing             |
+| `SCREEN_MISSING_OPERATION_ID`    | Error   | Screen operation missing `operationId`                         |
+| `SCREEN_INVALID_X_EVENT`         | Error   | `x-event` is not a string, `{name}` object, or `{$ref}`       |
+| `SCREEN_CONFLICTING_EVENT_DEFS`  | Error   | `x-events` and `x-event` coexist on the same operation        |
+| `SCREEN_INVALID_INTERACTIONS`    | Error   | `x-interactions` is not an array                               |
+| `SCREEN_INVALID_INTERACTION`     | Error   | `x-interactions` entry missing `name`                          |
+| `SCREEN_DEPRECATED_X_EVENTS`     | Warning | `x-events` (flat list) is deprecated — use inline `x-event`   |
+| `SCREEN_INVALID_EVENTS`          | Error   | `x-events` is not an array (legacy validation)                 |
+| `SCREEN_INVALID_EVENT`           | Error   | `x-events` item missing `name` or `type` (legacy validation)  |
+
+In `screen: true` modules, `MISSING_X_SERVICE` / `MISSING_X_METHOD` warnings are suppressed (screen specs do not need service/method declarations).
+
+---
+
+## Custom Templates
+
+You can extend the default templates or create new ones for additional generated artifacts. All `ScreenContext` fields are available in templates.
+
+### ViewProps Template Example
+
+`spec/default/templates/screen-view-props.hbs`:
+
+```handlebars
+{{#each screens}}
+export interface {{screenName}}ViewProps {
+  // ViewModel: {{viewModelSchema}}
+  // Screen ID: {{screenId}}
+}
+{{/each}}
+```
+
+Add to config:
+
+```yaml
+outputs:
+  screen-view-props:
+    output: frontend/src/screens/view-props.generated.ts
+    template: screen-view-props.hbs
+```
+
+### Available Template Context
+
+| Field             | Type      | Description                                        |
+| ----------------- | --------- | -------------------------------------------------- |
+| `screens`         | array     | `ScreenContext[]` — array of screen definitions    |
+| `screens[].screenEvent` | object? | `InlineEventDefinition` — GET screen_view event |
+| `screens[].actions` | array   | `ScreenAction[]` — mutation operations with events |
+| `screens[].interactions` | array | `ScreenInteraction[]` — interaction bindings with events |
+| `screens[].pathParams` | string[] | Path parameter names for this route              |
+| `screens[].links[].event` | object? | `InlineEventDefinition` — link navigation event |
+| `spec`            | object    | Raw OpenAPI spec (for direct access when needed)   |
+| `title`           | string    | OpenAPI title                                      |
+| `version`         | string    | OpenAPI version                                    |
+| `moduleName`      | string    | Module name                                        |
+| `contractPackage` | string    | Contract package import path                       |
+| `schemaNames`     | string[]  | All schema names                                   |
+
+---
+
+## Tiered Integration
+
+### Tier 1 — Core (built into micro-contracts)
+
+- Type definitions: `x-screen-*`, `x-event`, `x-interactions` on `OperationObject`
+- Screen context extraction: `TemplateContext.screens` (with `screenEvent`, `actions`, `interactions`, `pathParams`)
+- `$ref` resolution: `components.x-event-defs` local references
+- Params auto-derivation: path params for `get` and `links` placements
+- Lint rules: Screen spec consistency, inline event validation, interaction validation
+- `init --screens`: Starter file generation
+- Default templates: `screen-navigation.hbs`, `screen-events.hbs`
+- Handlebars helpers: `hasEvent`, `eventParamsSignature`
+
+### Tier 2 — Optional Packages / Official Recipes (future)
+
+| Package                        | Purpose                                                                  |
+| ------------------------------ | ------------------------------------------------------------------------ |
+| `@micro-contracts/e2e-scaffold`| Parse screen spec to generate Playwright test stubs with coverage         |
+| ViewProp / data-testid pattern | Derive stable test IDs from ViewModel fields + `x-screen-const`         |
+
+### Tier 3 — Documentation Only (future)
+
+| Pattern                   | Description                                                          |
+| ------------------------- | -------------------------------------------------------------------- |
+| Design tool integration   | Link screen IDs to design tool frames via `x-pen-node` or similar   |
+| Requirements traceability | Link screens to user stories via `x-satisfies`                      |
+| Data lineage declarations | Declare upstream API/DB origins on ViewModel schemas via `x-lineage-source` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micro-contracts",
-  "version": "0.12.3",
+  "version": "0.14.0",
   "description": "Contract-first OpenAPI toolchain that keeps TypeScript UI and microservices aligned via code generation",
   "type": "module",
   "main": "dist/index.js",