@lssm/lib.contracts-spec 17.3.2

package/dist/docs/docs.feature.d.ts

@@ -0,0 +1,14 @@
+import type { DocBlock } from './types.js';
+export declare const DocsFeature: import("..").FeatureModuleSpec;
+export declare const DocsSystemDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const accessibility_wcag_compliance_specs_DocBlocks: DocBlock[];
+export declare const metaDocs: DocBlock[];

package/dist/docs/docs.feature.js

@@ -0,0 +1,365 @@
+import{defineFeature as e}from"../features/index.js";import{DOCS_DOMAIN as n,DOCS_OWNERS as t,DOCS_STABILITY as a,DOCS_TAGS as o}from"./constants.js";export const DocsFeature=e({meta:{key:"platform.docs",version:"1.0.0",title:"Documentation System",description:"Generate, publish, search, and reference contract documentation and DocBlocks",domain:n,owners:t,tags:[...o],stability:a},operations:[{key:"docs.generate",version:"1.0.0"},{key:"docs.publish",version:"1.0.0"},{key:"docs_search",version:"1.0.0"},{key:"docs.contract.reference",version:"1.0.0"}],events:[{key:"docs.generated",version:"1.0.0"},{key:"docs.published",version:"1.0.0"}],presentations:[{key:"docs.layout",version:"1.0.0"},{key:"docs.reference.page",version:"1.0.0"}],capabilities:{provides:[{key:"docs.system",version:"1.0.0"}]},dataViews:[{key:"docs.index.view",version:"1.0.0"},{key:"docs.contract.reference.view",version:"1.0.0"},{key:"docs.examples.catalog.view",version:"1.0.0"}],forms:[{key:"docs_search.form",version:"1.0.0"}]});export const DocsSystemDocBlock={id:"docs.tech.docs-system",title:"Docs system overview",summary:"How ContractSpec generates, indexes, and presents documentation.",kind:"reference",visibility:"public",route:"/docs/tech/docs/system",tags:["docs","system","contracts"],body:`# Docs system overview
+
+ContractSpec treats documentation as a first-class output of your specs. The docs system combines contracts, DocBlocks, manifests, and presentations into a consistent docs surface.
+`};export const accessibility_wcag_compliance_specs_DocBlocks=[{id:"docs.accessibility_wcag_compliance_specs",title:"Accessibility & WCAG Compliance \u2014 **specs.md**",summary:"> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non\u2011negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low\u2011cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.",kind:"reference",visibility:"public",route:"/docs/accessibility_wcag_compliance_specs",tags:["accessibility_wcag_compliance_specs"],body:`# Accessibility & WCAG Compliance \u2014 **specs.md**
+
+> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non\u2011negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low\u2011cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.
+
+---
+
+## 0) Scope & Principles
+
+- **Standards:** WCAG\xA02.2\xA0AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN\xA0301\xA0549 compliance by conformance to WCAG.
+- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).
+- **Rule of ARIA:** \u201CNo ARIA is better than bad ARIA.\u201D Prefer native elements.
+- **Definition of Done (DoD):** No Critical/Major a11y issues in CI; keyboard complete; SR (screen reader) smoke test passed; contrasts pass; acceptance criteria below satisfied.
+- **Repo Alignment:** Web apps use **Radix Primitives + shadcn** wrappers centralized in \`packages/lssm/libs/ui-kit-web\`. Prefer those components over per\u2011app duplicates (\`packages/*/apps/*/src/components/ui\`). When missing, add to \`ui-kit-web\` first, then adopt app\u2011side.
+
+---
+
+## 1) Design Requirements (Design System & Tokens)
+
+**1.1 Color & Contrast**
+
+- Body text, icons essential to meaning: **\u2265\xA04.5:1**; large text (\u2265\xA018.66px regular / 14px bold): **\u2265\xA03:1**.
+- Interactive states (default/hover/active/disabled/focus) must maintain contrast **\u2265\xA03:1** against adjacent colors; text within components follows text ratios.
+- Provide light & dark themes with tokens that guarantee minimums. **Never rely solely on color** to convey meaning; pair with text, shape, or icon.
+
+**1.2 Focus Indicators (WCAG\xA02.4.11/12)**
+
+- Every interactive element has a **visible focus** with clear offset; indicator contrast **\u2265\xA03:1** vs adjacent colors and indicator **area \u2265\xA02\xA0CSS\xA0px** thick.
+- Focus **must not be obscured** by sticky headers/footers or scroll containers.
+
+**1.3 Motion & Preferences**
+
+- Respect \`prefers-reduced-motion\`: suppress large parallax, auto\u2011animations; provide instant alternatives.
+- Avoid motion that could trigger vestibular issues; under PRM, use fade/scale under **150ms**.
+
+**1.4 Target Size (2.5.8)**
+
+- Hit areas **\u2265\xA024\xD724\xA0CSS\xA0px** (web) and **\u2265\xA044\xD744\xA0dp** (mobile) unless exempt.
+
+**1.5 Typography & Layout**
+
+- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320\xA0CSS\xA0px** width.
+- Maintain clear heading hierarchy (h1\u2026h6), one **h1** per view.
+
+- Repository baseline (Web): default body text uses Tailwind \`text-lg\` (\u224818px). As of 2025\u201109\u201120, the repository bumped all Tailwind typography scale usages by +1 step (e.g., \`text-sm\`\u2192\`text-base\`, \`text-base\`\u2192\`text-lg\`, \u2026, \`text-8xl\`\u2192\`text-9xl\`). For long\u2011form content, default to \`prose-lg\`.
+- Do not use \`text-xs\` for body copy. Reserve \`text-sm\` only for non\u2011essential meta (timestamps, fine print) while ensuring contrast and touch targets remain compliant.
+- When increasing font size, ensure line height supports readability. Prefer Tailwind defaults or \`leading-relaxed\`/\`leading-7\` for body text where dense blocks appear.
+
+**1.6 Iconography & Imagery**
+
+- Decorative images: \`alt=""\` or \`aria-hidden="true"\`.
+- Informative images: concise, specific **alt**; complex charts require a **data table or long description**.
+
+---
+
+## 2) Content Requirements (UX Writing)
+
+- Links say **what happens** (avoid \u201Cclick here\u201D).
+- Buttons start with verbs; avoid ambiguous labels.
+- Form labels are **visible**; placeholders are **not labels**.
+- Error messages: human + programmatic association; avoid color\u2011only.
+- Authentication: allow **copy/paste**, password managers, and avoid cognitive tests alone (**3.3.7/3.3.8/3.3.9**).
+- Avoid CAPTCHAs that block users; if unavoidable, provide **multiple alternatives** (logic-free).
+
+---
+
+## 3) Engineering Requirements (Web \u2014 Next.js/React)
+
+> Use and extend \`packages/lssm/libs/ui-kit-web\` as the default UI surface. It wraps **Radix** primitives with sensible a11y defaults (focus rings, roles, keyboard, ARIA binding). When a gap exists, add it to \`ui-kit-web\` first.
+
+**3.1 Semantics & Landmarks**
+
+- Use native elements: \`<button>\`, \`<a href>\`, \`<label for>\`, \`<fieldset>\`, \`<legend>\`, \`<table>\`, etc.
+- Landmarks per page: \`header\`, \`nav\`, \`main\`, \`aside\`, \`footer\`. Provide a **Skip to main content** link.
+- Provide a **Route Announcer** (\`aria-live="polite"\`) and move focus to page **h1** after navigation.
+
+**3.2 Keyboard**
+
+- All functionality available with keyboard alone. Tab order follows DOM/visual order; **no keyboard traps**.
+- Common bindings:
+  - Space/Enter \u2192 activate button; Enter on link;
+  - Esc closes dialogs/menus;
+  - Arrow keys for lists/menus/tablists with **roving tabindex**.
+
+**3.3 Focus Management**
+
+- On route change (Next.js), move focus to the page \`<h1>\` or container and announce via a live region.
+- Dialogs/menus: **trap focus** inside; return focus to invoking control on close.
+- Don\u2019t steal focus except after explicit user action.
+
+**3.4 Forms**
+
+- Each input has a \`<label>\` or \`aria-label\`. Group related inputs with \`<fieldset><legend>\`.
+- Associate errors via \`aria-describedby\` or inline IDs; announce with \`role="alert"\` (assertive only for critical).
+- Provide **autocomplete** tokens for known fields; show **inline validation** and do not block on **onBlur** alone.
+
+**3.5 ARIA Usage**
+
+- Only when needed; match patterns (dialog, menu, combobox, tablist, listbox) per ARIA Authoring Practices.
+- Ensure **name/role/value** are programmatically determinable.
+
+**3.6 Media**
+
+- Videos: **captions**; provide **transcripts** for audio; audio descriptions for essential visual info.
+- No auto\u2011playing audio. Auto\u2011playing video must be muted and pausable; provide controls.
+
+**3.7 Tables & Data**
+
+- Use \`<th scope>\` for headers; captions via \`<caption>\`; announce sorting via \`aria-sort\`.
+- Provide CSV/JSON export where charts are primary.
+
+**3.8 Performance & Robustness**
+
+- Avoid content shifts that move focus; reserve space or use skeletons.
+- Maintain accessible names through hydration/SSR; avoid \`dangerouslySetInnerHTML\` where possible.
+
+**3.9 Next.js specifics**
+
+- Use \`next/link\` for navigation; ensure links are **links**, not buttons.
+- \`next/image\` must include **alt** (empty if decorative).
+- Announce route changes with a **global live region** and shift focus to the new view.
+
+**3.10 Accessibility library integration**
+
+- Import \`@lssm/lib.accessibility\` at app root. It auto-imports its \`styles.css\` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:
+
+\`\`\`tsx
+// app/layout.tsx
+import '@lssm/lib.accessibility'; // includes tokens and provider exports
+// or if needed: import '@lssm/lib.accessibility/src/styles.css';
+\`\`\`
+
+- Wrap the app with \`AccessibilityProvider\` and include an element with \`id="main"\` for the skip link target.
+
+---
+
+## 3b) lssm/ui-kit-web \u2014 Component Patterns & Defaults
+
+> Source: \`packages/lssm/libs/ui-kit-web/ui/*\`
+
+- **Button/Input/Textarea**: Built\u2011in \`focus-visible\` rings; ensure visible labels via \`FormLabel\` or \`aria-label\`.
+- **Form** (\`form.tsx\`): \`FormControl\` wires \`aria-invalid\` and \`aria-describedby\` to \`FormMessage\` and \`FormDescription\`. Prefer \`FormMessage\` for inline errors. Add \`role="alert"\` only for critical.
+- **Dialog/Sheet/Dropdown**: Use Radix wrappers for focus\u2011trap and return\u2011focus. Provide \`DialogTitle\` + \`DialogDescription\` for name/description.
+- **Select/Combobox**: Prefer \`SelectTrigger\` with visible label; for icon\u2011only triggers, supply \`aria-label\`. Document examples in each app.
+- **Tabs**: Use \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`; names are programmatically determinable.
+- **Toast/Toaster**: Prefer non\u2011blocking announcements; map critical to assertive region; include action buttons with clear labels.
+- **Table**: Use \`TableCaption\`; ensure \`TableHead\` cells use proper \`scope\`. Provide \`aria-sort\` on sortable headers.
+- **Utilities to add (repo action)**:
+  - \`SkipLink\` component and pattern in layouts.
+  - \`RouteAnnouncer\` (\`aria-live="polite"\`) and **FocusOnRouteChange** helper.
+  - \`VisuallyHidden\` wrapper (Radix visually-hidden or minimal utility).
+  - \`useReducedMotion\` helper; honor in animated components.
+  - Touch\u2011size variants (\u226544\xD744) for interactive atoms.
+
+---
+
+## 4) Engineering Requirements (Mobile \u2014 Expo/React\xA0Native)
+
+- Set \`accessibilityLabel\`, \`accessibilityHint\`, and \`accessibilityRole\` on touchables.
+- Ensure **hit slop** / min size **\u2265\xA044\xD744\xA0dp**.
+- Support Dynamic Type / font scaling; no clipped text at **200%**.
+- Respect **Invert Colors** and **Reduce Motion**; avoid flashing.
+- Group related items with \`accessibilityElements\` ordering; hide decoration with \`accessible={false}\` or \`importantForAccessibility="no-hide-descendants"\` when appropriate.
+- Test with **VoiceOver (iOS)** and **TalkBack (Android)**.
+
+---
+
+## 5) Component Patterns (Acceptance Rules)
+
+**Buttons & Links**
+
+- Use \`<button>\` for actions, \`<a href>\` for navigation. Provide disabled states that are perceivable beyond color.
+
+**Navigation**
+
+- Provide **Skip link**. One primary nav landmark. Indicate current page (\`aria-current="page"\`).
+
+**Menus/Combobox/Autocomplete**
+
+- Follow ARIA patterns: focus moves into list; \`aria-expanded\`, \`aria-controls\`, \`aria-activedescendant\` when applicable; Esc closes; typing filters.
+
+**Modals/Dialogs**
+
+- \`role="dialog"\` or \`alertdialog\` with **label**; focus trapped; background inert; Esc closes; return focus to trigger.
+
+**Tabs**
+
+- \`role="tablist"\`; tabs are in the tab order; arrow keys switch focus; content is \`role="tabpanel"\` with \`aria-labelledby\`.
+
+**Toasts/Notifications**
+
+- Non-critical: \`aria-live="polite"\`; critical: \`role="alert"\` sparingly.
+
+**Infinite Scroll / \u201CLoad More\u201D**
+
+- Provide **Load more** control; announce new content to SR; preserve keyboard position.
+
+**Drag & Drop (2.5.7)**
+
+- Provide **non\u2011drag** alternative (e.g., move up/down buttons).
+
+**Charts & Maps**
+
+- Provide **table alternative** or textual summary; keyboard access to datapoints where interactive.
+
+---
+
+## 6) Testing & CI (Blocking Gates)
+
+**Static & Unit**
+
+- \`eslint-plugin-jsx-a11y\` \u2014 error on violations.
+- \`jest-axe\` \u2014 unit tests for components.
+
+**Automated Integration**
+
+- \`axe-core\` via Playwright or Cypress on critical flows.
+- \`pa11y-ci\` on key routes; threshold: **0 Critical / 0 Serious** to merge.
+- Lighthouse CI a11y score **\u2265\xA095** on target pages.
+
+**Manual QA (per release)**
+
+- **Keyboard patrol:** navigate primary flows without mouse.
+- **Screen reader smoke:** NVDA (Windows) or VoiceOver (macOS/iOS) across login, navigation, forms, dialogs.
+- **Zoom & Reflow:** 200\u2013400% & 320\xA0px width.
+- **Color/Contrast check:** tokens in both themes.
+
+**Reporting**
+
+- A11y issues labeled: \`a11y-blocker\`, \`a11y-bug\`, \`a11y-enhancement\` with WCAG ref.
+
+---
+
+## 7) Repository\u2011Specific Adoption Plan
+
+- Centralize UI usage on \`packages/lssm/libs/ui-kit-web\` and de\u2011duplicate per\u2011app \`components/ui\` where feasible.
+- Introduce \`SkipLink\`, \`RouteAnnouncer\`, \`FocusOnRouteChange\`, and \`VisuallyHidden\` in \`ui-kit-web\`. Adopt in app layouts (\`app/layout.tsx\`) first.
+- Add \`useReducedMotion\` and wire into animated components (e.g., \`drawer\`, \`tooltip\`, \`carousel\`).
+- Add touch\u2011size variants to \`Button\`, \`IconButton\`, \`TabsTrigger\`, toggles.
+- Document Select label patterns and error association in Forms.
+
+---
+
+## 8) Code Snippets
+
+**Skip Link**
+
+\`\`\`html
+<a
+  class="sr-only focus:not-sr-only focus-visible:outline focus-visible:ring-4 focus-visible:ring-offset-2"
+  href="#main"
+  >Skip to main content</a
+>
+<main id="main">\u2026</main>
+\`\`\`
+
+**Dialog (Radix + shadcn/ui) \u2014 essentials**
+
+\`\`\`tsx
+// Ensure label, description, focus trap, and return focus on close remain intact
+<Dialog>
+  <DialogTrigger asChild>
+    <button aria-haspopup="dialog">Open settings</button>
+  </DialogTrigger>
+  <DialogContent aria-describedby="settings-desc">
+    <DialogTitle>Settings</DialogTitle>
+    <p id="settings-desc">Update your preferences.</p>
+    <DialogClose asChild>
+      <button>Close</button>
+    </DialogClose>
+  </DialogContent>
+</Dialog>
+\`\`\`
+
+**Form error association**
+
+\`\`\`tsx
+<label htmlFor="email">Email</label>
+<input id="email" name="email" type="email" aria-describedby="email-err" />
+<p id="email-err" role="alert">Enter a valid email.</p>
+\`\`\`
+
+**Route change announcement (Next.js)**
+
+\`\`\`tsx
+// Add once at app root
+<div
+  aria-live="polite"
+  aria-atomic="true"
+  id="route-announcer"
+  className="sr-only"
+/>
+\`\`\`
+
+---
+
+## 9) Exceptions & Waivers
+
+- If a criterion cannot be met, file an issue with: context, attempted alternatives, WCAG reference, impact assessment, and a remediation date. **Temporary waivers only.**
+
+---
+
+## 10) Ownership
+
+- **Design:** maintains token contrast, component specs.
+- **Engineering:** enforces CI gates, implements patterns.
+- **QA:** runs manual checks per release.
+- **PM:** blocks release if AA not met on user\u2011visible flows.
+
+---
+
+## 11) References (internalize; no external dependency at runtime)
+
+- WCAG\xA02.2 (AA), EN\xA0301\xA0549. ARIA Authoring Practices. Platform HIG (Apple, Material).
+- \`packages/lssm/libs/ui-kit-web\` as the canonical UI source for web.
+
+> **Bottom line:** Shipping means **accessible by default**. We don\u2019t trade a11y for speed; we bake it into speed.
+
+---
+
+## 12) Adoption Status (2025-09-23)
+
+- web-artisan: AccessibilityProvider integrated; sr-only/forced-colors applied; 44x44 targets; forms announce errors; jest-axe and cypress-axe in place.
+- web-strit: AccessibilityProvider integrated; forced-colors, sr-only; forms announce errors; 44x44 targets; contrast tokens and text-scale wired; jest-axe and cypress-axe in place.
+- web-coliving: AccessibilityProvider integrated; forced-colors and focus visibility added; text-scale wired; landing pages converted to \`Section\`/stacks with text-lg defaults; CTA capture standardized; ESLint guard for text-xs in main content; jest-axe and cypress-axe in place. Next: audit icon-only controls and ensure 44x44 targets; add role="alert" where critical.
+
+> CI gates: run eslint a11y, jest-axe on components, and cypress-axe on critical flows per app.
+
+---
+
+## 13) CI Hardening & Visual QA
+
+- Linting: Run eslint with jsx-a11y rules across all web apps; block on violations.
+- Unit: Run jest-axe for ui-kit-web and app-level components.
+- Integration: cypress-axe on key flows (auth, forms, dialogs, tables).
+- Synthetic scans: pa11y-ci on critical pages (0 Critical/Serious policy).
+- Performance/A11y audit: Lighthouse CI with a11y score >= 95 on target routes.
+- Artifacts: Upload pa11y and Lighthouse reports per PR; annotate failures.
+
+### Recent additions (2025-09-26)
+
+- AutocompleteInput (groceries): Upgraded to ARIA combobox pattern with \`aria-controls\`, \`aria-activedescendant\`, \`Escape\`/\`Tab\` handling, and labelled listbox.
+- Cypress a11y tests added for furniture and incidents modules on \`/modules\` and operators flows; checks run axe with critical/serious impacts.
+
+## 14) Accessibility Telemetry (PostHog)
+
+- Events (anonymized): a11y_pref_changed (text_scale, contrast_mode, reduce_motion), a11y_panel_opened.
+- Properties: app, route, previous_value, new_value, timestamp.
+- Dashboards: Adoption over time, per app/route; correlation with reduced bounce on forms.
+- Privacy: No PII; aggregate only.
+`}];export const metaDocs=[{id:"docs.meta.docblocks-process",title:"DocBlocks process",summary:"How to author goal/how/usage DocBlocks close to code.",kind:"reference",visibility:"mixed",route:"/docs/meta/docblocks-process",tags:["docs","process"],body:`## DocBlocks authoring rules
+
+- Colocate docs beside implementation; avoid barrel /docs folders.
+- Split intent:
+  - **goal**: why this exists (before implementation).
+  - **how**: operational/runbook steps.
+  - **usage**: quick checklist for consumers.
+- Use \`visibility\`: public | internal | mixed.
+- Prefer routes like \`/docs/<domain>/<topic>/<kind>\`; ids mirror that.
+- Keep body Markdown LLM-friendly; avoid HTML.
+- Add owners/tags/domain/stability when known.
+- For presentations/markdown outputs, rely on TransformEngine via DocRegistry.
+- No sourcePath; DocBlocks are canonical.`}];

package/dist/docs/events/docsGenerated.event.d.ts

@@ -0,0 +1,55 @@
+import { SchemaModel } from '@lssm/lib.schema';
+export declare const DocsGeneratedPayload: SchemaModel<{
+    buildId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    version: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    generatedAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+    outputDir: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    artifactCount: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+    warnings: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+    };
+}>;
+export declare const DocsGeneratedEvent: import("../..").EventSpec<SchemaModel<{
+    buildId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    version: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    generatedAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+    outputDir: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    artifactCount: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+    warnings: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+    };
+}>>;

package/dist/docs/events/docsGenerated.event.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{defineEvent as r}from"../../events.js";import{DOCS_DOMAIN as n,DOCS_OWNERS as o,DOCS_STABILITY as a,DOCS_TAGS as i}from"../constants.js";import{docId as s}from"../registry.js";export const DocsGeneratedPayload=new t({name:"DocsGeneratedPayload",fields:{buildId:{type:e.String_unsecure(),isOptional:!1},version:{type:e.String_unsecure(),isOptional:!0},generatedAt:{type:e.DateTime(),isOptional:!1},outputDir:{type:e.String_unsecure(),isOptional:!0},artifactCount:{type:e.Int_unsecure(),isOptional:!0},warnings:{type:e.String_unsecure(),isOptional:!0,isArray:!0}}});export const DocsGeneratedEvent=r({meta:{key:"docs.generated",version:"1.0.0",description:"Emitted when documentation artifacts are generated.",domain:n,owners:o,tags:[...i,"generation"],stability:a,docId:[s("docs.tech.docs-generator")]},payload:DocsGeneratedPayload});

package/dist/docs/events/docsPublished.event.d.ts

@@ -0,0 +1,63 @@
+import { SchemaModel } from '@lssm/lib.schema';
+export declare const DocsPublishedPayload: SchemaModel<{
+    publishId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    version: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    environment: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    url: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    publishedAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+    status: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    warnings: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+    };
+}>;
+export declare const DocsPublishedEvent: import("../..").EventSpec<SchemaModel<{
+    publishId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    version: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    environment: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    url: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    publishedAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+    status: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    warnings: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+    };
+}>>;

package/dist/docs/events/docsPublished.event.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{defineEvent as i}from"../../events.js";import{DOCS_DOMAIN as s,DOCS_OWNERS as n,DOCS_STABILITY as o,DOCS_TAGS as r}from"../constants.js";import{docId as u}from"../registry.js";export const DocsPublishedPayload=new t({name:"DocsPublishedPayload",fields:{publishId:{type:e.String_unsecure(),isOptional:!1},version:{type:e.String_unsecure(),isOptional:!0},environment:{type:e.String_unsecure(),isOptional:!0},url:{type:e.String_unsecure(),isOptional:!0},publishedAt:{type:e.DateTime(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!0},warnings:{type:e.String_unsecure(),isOptional:!0,isArray:!0}}});export const DocsPublishedEvent=i({meta:{key:"docs.published",version:"1.0.0",description:"Emitted when documentation is published.",domain:s,owners:n,tags:[...r,"publish"],stability:o,docId:[u("docs.tech.docs-publish")]},payload:DocsPublishedPayload});

package/dist/docs/events/index.d.js

@@ -0,0 +1 @@
+export*from"./docsGenerated.event.js";export*from"./docsPublished.event.js";

package/dist/docs/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from './docsGenerated.event.js';
+export * from './docsPublished.event.js';

package/dist/docs/events/index.js

@@ -0,0 +1 @@
+export*from"./docsGenerated.event.js";export*from"./docsPublished.event.js";

package/dist/docs/forms/docsSearch.form.d.ts

@@ -0,0 +1,15 @@
+import { SchemaModel } from '@lssm/lib.schema';
+export declare const DocsSearchForm: import("../..").FormSpec<SchemaModel<{
+    query: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    visibility: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    kind: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+}>>;

package/dist/docs/forms/docsSearch.form.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as l}from"@lssm/lib.schema";import{defineFormSpec as a}from"../../forms/forms.js";import{DOCS_DOMAIN as i,DOCS_OWNERS as n,DOCS_STABILITY as o,DOCS_TAGS as r}from"../constants.js";import{docId as t}from"../registry.js";const c=new l({name:"DocsSearchFormModel",fields:{query:{type:e.String_unsecure(),isOptional:!0},visibility:{type:e.String_unsecure(),isOptional:!0},kind:{type:e.String_unsecure(),isOptional:!0}}});export const DocsSearchForm=a({meta:{key:"docs_search.form",title:"Docs Search",version:"1.0.0",description:"Search form for documentation discovery.",domain:i,owners:n,tags:[...r,"search"],stability:o,docId:[t("docs.tech.docs-search")]},model:c,fields:[{kind:"text",name:"query",labelI18n:"Search",placeholderI18n:"Search docs"},{kind:"select",name:"visibility",labelI18n:"Visibility",options:{kind:"static",options:[{labelI18n:"Public",value:"public"},{labelI18n:"Internal",value:"internal"},{labelI18n:"Mixed",value:"mixed"}]}},{kind:"select",name:"kind",labelI18n:"Kind",options:{kind:"static",options:[{labelI18n:"Goal",value:"goal"},{labelI18n:"How",value:"how"},{labelI18n:"Usage",value:"usage"},{labelI18n:"Reference",value:"reference"},{labelI18n:"FAQ",value:"faq"},{labelI18n:"Changelog",value:"changelog"}]}}],actions:[{key:"search",labelI18n:"Search"}],policy:{flags:[],pii:[]}});

package/dist/docs/forms/index.d.js

@@ -0,0 +1 @@
+export*from"./docsSearch.form.js";

package/dist/docs/forms/index.d.ts

@@ -0,0 +1 @@
+export * from './docsSearch.form.js';

package/dist/docs/forms/index.js

@@ -0,0 +1 @@
+export*from"./docsSearch.form.js";

package/dist/docs/index.d.js

@@ -0,0 +1 @@
+export*from"./capabilities/index.js";export*from"./commands/index.js";export*from"./constants.js";export*from"./contracts.js";export*from"./docblocks.manifest.generated.js";export*from"./docs.feature.js";export*from"./events/index.js";export*from"./forms/index.js";export*from"./manifest.js";export*from"./presentations.js";export*from"./presentations/index.js";export*from"./queries/index.js";export*from"./registry.js";export*from"./types.js";export*from"./views/index.js";

package/dist/docs/index.d.ts

@@ -0,0 +1,15 @@
+export * from './capabilities/index.js';
+export * from './commands/index.js';
+export * from './constants.js';
+export * from './contracts.js';
+export * from './docblocks.manifest.generated.js';
+export * from './docs.feature.js';
+export * from './events/index.js';
+export * from './forms/index.js';
+export * from './manifest.js';
+export * from './presentations.js';
+export * from './presentations/index.js';
+export * from './queries/index.js';
+export * from './registry.js';
+export * from './types.js';
+export * from './views/index.js';

package/dist/docs/index.js

@@ -0,0 +1 @@
+export*from"./capabilities/index.js";export*from"./commands/index.js";export*from"./constants.js";export*from"./contracts.js";export*from"./docblocks.manifest.generated.js";export*from"./docs.feature.js";export*from"./events/index.js";export*from"./forms/index.js";export*from"./manifest.js";export*from"./presentations.js";export*from"./presentations/index.js";export*from"./queries/index.js";export*from"./registry.js";export*from"./types.js";export*from"./views/index.js";

package/dist/docs/manifest-builder.d.ts

@@ -0,0 +1,13 @@
+import * as ts from '@lssm/lib.typescript-runtime';
+import type { DocBlockManifestEntry, PackageDocManifest } from './manifest.js';
+type ModuleAnalysis = {
+    entries: DocBlockManifestEntry[];
+    docRefs: string[];
+};
+export declare function extractModuleDocData(sourceText: string, filePath: string, sourceModule: string, parser?: ts.TypeScriptSourceParser): Promise<ModuleAnalysis>;
+export declare function buildPackageDocManifest(options: {
+    packageName: string;
+    srcRoot: string;
+    generatedAt?: string;
+}): Promise<PackageDocManifest>;
+export {};

package/dist/docs/manifest-builder.js

@@ -0,0 +1 @@
+import x from"node:fs";import y from"node:path";import*as n from"@lssm/lib.typescript-runtime";function b(e){if(!e||typeof e!=="object"||Array.isArray(e))return!1;const i=e;return typeof i.id==="string"&&typeof i.title==="string"&&typeof i.body==="string"}function u(e,i,o){if(n.isParenthesizedExpression(e))return u(e.expression,i,o);if(n.isSatisfiesExpression(e)||n.isAsExpression(e))return u(e.expression,i,o);if(n.isStringLiteral(e)||n.isNoSubstitutionTemplateLiteral(e))return e.text;if(n.isTemplateExpression(e)){let t=e.head.text;for(const r of e.templateSpans){const s=u(r.expression,i,o);if(typeof s!=="string"&&typeof s!=="number"&&typeof s!=="boolean")return;t+=`${s}${r.literal.text}`}return t}if(n.isNumericLiteral(e))return Number(e.text);if(n.isBinaryExpression(e)){const t=u(e.left,i,o),r=u(e.right,i,o);if(t===void 0||r===void 0)return;if(e.operatorToken.kind===n.SyntaxKind.PlusToken){if(typeof t==="number"&&typeof r==="number")return t+r;if((typeof t==="string"||typeof t==="number")&&(typeof r==="string"||typeof r==="number"))return`${t}${r}`}if(e.operatorToken.kind===n.SyntaxKind.SlashToken&&typeof t==="number"&&typeof r==="number")return t/r;return}if(e.kind===n.SyntaxKind.TrueKeyword)return!0;if(e.kind===n.SyntaxKind.FalseKeyword)return!1;if(e.kind===n.SyntaxKind.NullKeyword)return null;if(n.isArrayLiteralExpression(e)){const t=[];for(const r of e.elements){if(n.isSpreadElement(r)){const c=u(r.expression,i,o);if(!Array.isArray(c))return;t.push(...c);continue}const s=u(r,i,o);if(s===void 0)return;t.push(s)}return t}if(n.isObjectLiteralExpression(e)){const t={};for(const r of e.properties){if(!n.isPropertyAssignment(r))return;const s=r.name.getText().replace(/^["']|["']$/g,""),c=u(r.initializer,i,o);if(c===void 0)return;t[s]=c}return t}if(n.isIdentifier(e))return i.get(e.text);if(n.isPropertyAccessExpression(e)){const t=u(e.expression,i,o);if(!t||typeof t!=="object"||Array.isArray(t))return;return t[e.name.text]}if(n.isCallExpression(e)&&n.isIdentifier(e.expression)){if((e.expression.text==="docId"||e.expression.text==="docRef")&&e.arguments.length===1)return u(e.arguments[0],i,o)}if(n.isCallExpression(e)&&n.isPropertyAccessExpression(e.expression)&&e.expression.name.text==="join"&&e.arguments.length<=1){const t=u(e.expression.expression,i,o),r=e.arguments.length===0?",":u(e.arguments[0],i,o);if(!Array.isArray(t)||typeof r!=="string")return;return t.map((s)=>String(s)).join(r)}return}function D(e,i){const o=new Map;for(const t of e.statements){if(!n.isVariableStatement(t))continue;for(const r of t.declarationList.declarations){if(!n.isIdentifier(r.name)||!r.initializer)continue;let s;try{s=u(r.initializer,o,i)}catch{s=void 0}if(s!==void 0)o.set(r.name.text,s)}}return o}function M(e,i,o){let t=e;while(n.isParenthesizedExpression(t)||n.isSatisfiesExpression(t)||n.isAsExpression(t))t=t.expression;if(!n.isObjectLiteralExpression(t))return[];const r=t.properties.find((f)=>n.isPropertyAssignment(f)&&f.name.getText()==="meta");if(!r||!n.isPropertyAssignment(r))return[];let s=r.initializer;while(n.isParenthesizedExpression(s)||n.isSatisfiesExpression(s)||n.isAsExpression(s))s=s.expression;if(!n.isObjectLiteralExpression(s))return[];const c=s.properties.find((f)=>n.isPropertyAssignment(f)&&f.name.getText()==="docId");if(!c||!n.isPropertyAssignment(c))return[];const g=u(c.initializer,i,o);if(!Array.isArray(g)||!g.every((f)=>typeof f==="string"))throw Error(`Non-static DocBlock reference in ${o} at ${c.initializer.getStart()}`);return g}export async function extractModuleDocData(e,i,o,t){const r=t?await t.parse({filePath:i,sourceText:e}):await n.parseTypeScriptSource({filePath:i,sourceText:e}),s=D(r,i),c=[],g=new Set;for(const f of r.statements){if(!n.isVariableStatement(f))continue;if(!f.modifiers?.some((a)=>a.kind===n.SyntaxKind.ExportKeyword))continue;for(const a of f.declarationList.declarations){if(!n.isIdentifier(a.name)||!a.initializer)continue;const d=u(a.initializer,s,i);for(const l of M(a.initializer,s,i))g.add(l);if(d===void 0){if(a.name.text.includes("DocBlock")||a.initializer.getText(r).includes("satisfies DocBlock"))throw Error(`Non-static DocBlock source in ${i} at ${a.initializer.getStart(r)}`);continue}if(b(d))c.push({id:d.id,exportName:a.name.text,sourceModule:o,block:d});if(Array.isArray(d)&&d.every((l)=>b(l)))for(const l of d)c.push({id:l.id,exportName:a.name.text,sourceModule:o,block:l})}}return{entries:c,docRefs:[...g]}}function h(e){return!e.endsWith(".ts")||e.endsWith(".test.ts")||e.endsWith(".generated.ts")||e.includes(`${y.sep}dist${y.sep}`)}function A(e){return x.readdirSync(e,{withFileTypes:!0}).flatMap((i)=>{const o=y.join(e,i.name);if(i.isDirectory())return A(o);return h(o)?[]:[o]}).sort((i,o)=>i.localeCompare(o))}function V(e,i){return y.relative(e,i).replace(/\\/g,"/").replace(/\.ts$/,"")}export async function buildPackageDocManifest(e){const{packageName:i,srcRoot:o,generatedAt:t=new Date().toISOString()}=e,r=A(o);for(const a of r){if(a.endsWith(".docblock.ts"))throw Error(`Standalone DocBlock sources are not allowed: ${a}`);if(a.includes(`${y.sep}docs${y.sep}tech${y.sep}`))throw Error(`docs/tech source files are not allowed: ${a}`)}const s=[],c=new Map,g=new Map,f=new Map,k=new n.TypeScriptSourceParser;try{for(const a of r){const d=x.readFileSync(a,"utf8"),l=V(o,a),E=await extractModuleDocData(d,a,l,k);for(const p of E.entries){const m=`${p.sourceModule}:${p.exportName}`,w=c.get(p.id);if(w)throw Error(`Duplicate DocBlock id ${p.id} in ${m} and ${w}`);c.set(p.id,m);if(p.block.route){const S=g.get(p.block.route);if(S)throw Error(`Duplicate DocBlock route ${p.block.route} in ${m} and ${S}`);g.set(p.block.route,m)}s.push(p)}if(E.docRefs.length>0)f.set(l,E.docRefs)}}finally{await k.close()}for(const[a,d]of f)for(const l of d)if(!c.has(l))throw Error(`Missing DocBlock reference ${l} from ${a}`);s.sort((a,d)=>a.id.localeCompare(d.id));return{packageName:i,generatedAt:t,blocks:s}}

package/dist/docs/manifest.d.ts

@@ -0,0 +1,18 @@
+import type { DocBlock } from './types.js';
+export interface DocBlockManifestEntry {
+    id: string;
+    exportName: string;
+    sourceModule: string;
+    block: DocBlock;
+}
+export interface PackageDocManifest {
+    packageName: string;
+    generatedAt: string;
+    blocks: DocBlockManifestEntry[];
+}
+export interface WorkspaceDocManifest {
+    generatedAt: string;
+    packages: PackageDocManifest[];
+}
+export declare function packageDocBlocks(manifest: PackageDocManifest): DocBlock[];
+export declare function workspaceDocBlocks(manifest: WorkspaceDocManifest): DocBlock[];

package/dist/docs/manifest.js

@@ -0,0 +1 @@
+export function packageDocBlocks(e){return e.blocks.map(({block:c})=>c)}export function workspaceDocBlocks(e){return e.packages.flatMap((c)=>packageDocBlocks(c))}

package/dist/docs/presentations/docsLayout.presentation.d.ts

@@ -0,0 +1 @@
+export declare const DocsLayoutPresentation: import("../..").PresentationSpec;