@contractspec/lib.contracts 1.56.1 → 1.58.0

package/dist/node/docs/accessibility_wcag_compliance_specs.docblock.js

@@ -0,0 +1,513 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/docs/accessibility_wcag_compliance_specs.docblock.ts
+var accessibility_wcag_compliance_specs_DocBlocks = [
+  {
+    id: "docs.accessibility_wcag_compliance_specs",
+    title: "Accessibility & WCAG Compliance — **specs.md**",
+    summary: "> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG 2.2 AA** (aim for AAA where low‑cost), align with **EN 301 549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React Native)**.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/accessibility_wcag_compliance_specs",
+    tags: ["accessibility_wcag_compliance_specs"],
+    body: `# Accessibility & WCAG Compliance — **specs.md**
+
+> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG 2.2 AA** (aim for AAA where low‑cost), align with **EN 301 549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React Native)**.
+
+---
+
+## 0) Scope & Principles
+
+- **Standards:** WCAG 2.2 AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN 301 549 compliance by conformance to WCAG.
+- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).
+- **Rule of ARIA:** “No ARIA is better than bad ARIA.” 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‑app duplicates (\`packages/*/apps/*/src/components/ui\`). When missing, add to \`ui-kit-web\` first, then adopt app‑side.
+
+---
+
+## 1) Design Requirements (Design System & Tokens)
+
+**1.1 Color & Contrast**
+
+- Body text, icons essential to meaning: **≥ 4.5:1**; large text (≥ 18.66px regular / 14px bold): **≥ 3:1**.
+- Interactive states (default/hover/active/disabled/focus) must maintain contrast **≥ 3: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 2.4.11/12)**
+
+- Every interactive element has a **visible focus** with clear offset; indicator contrast **≥ 3:1** vs adjacent colors and indicator **area ≥ 2 CSS px** 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‑animations; 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 **≥ 24×24 CSS px** (web) and **≥ 44×44 dp** (mobile) unless exempt.
+
+**1.5 Typography & Layout**
+
+- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320 CSS px** width.
+- Maintain clear heading hierarchy (h1…h6), one **h1** per view.
+
+- Repository baseline (Web): default body text uses Tailwind \`text-lg\` (≈18px). As of 2025‑09‑20, the repository bumped all Tailwind typography scale usages by +1 step (e.g., \`text-sm\`→\`text-base\`, \`text-base\`→\`text-lg\`, …, \`text-8xl\`→\`text-9xl\`). For long‑form content, default to \`prose-lg\`.
+- Do not use \`text-xs\` for body copy. Reserve \`text-sm\` only for non‑essential 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 “click here”).
+- Buttons start with verbs; avoid ambiguous labels.
+- Form labels are **visible**; placeholders are **not labels**.
+- Error messages: human + programmatic association; avoid color‑only.
+- 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 — 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 → 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’t 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‑playing audio. Auto‑playing 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 \`@contractspec/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 '@contractspec/lib.accessibility'; // includes tokens and provider exports
+// or if needed: import '@contractspec/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 — Component Patterns & Defaults
+
+> Source: \`packages/lssm/libs/ui-kit-web/ui/*\`
+
+- **Button/Input/Textarea**: Built‑in \`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‑trap and return‑focus. Provide \`DialogTitle\` + \`DialogDescription\` for name/description.
+- **Select/Combobox**: Prefer \`SelectTrigger\` with visible label; for icon‑only triggers, supply \`aria-label\`. Document examples in each app.
+- **Tabs**: Use \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`; names are programmatically determinable.
+- **Toast/Toaster**: Prefer non‑blocking 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‑size variants (≥44×44) for interactive atoms.
+
+---
+
+## 4) Engineering Requirements (Mobile — Expo/React Native)
+
+- Set \`accessibilityLabel\`, \`accessibilityHint\`, and \`accessibilityRole\` on touchables.
+- Ensure **hit slop** / min size **≥ 44×44 dp**.
+- 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 / “Load More”**
+
+- Provide **Load more** control; announce new content to SR; preserve keyboard position.
+
+**Drag & Drop (2.5.7)**
+
+- Provide **non‑drag** 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\` — error on violations.
+- \`jest-axe\` — 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 **≥ 95** 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–400% & 320 px width.
+- **Color/Contrast check:** tokens in both themes.
+
+**Reporting**
+
+- A11y issues labeled: \`a11y-blocker\`, \`a11y-bug\`, \`a11y-enhancement\` with WCAG ref.
+
+---
+
+## 7) Repository‑Specific Adoption Plan
+
+- Centralize UI usage on \`packages/lssm/libs/ui-kit-web\` and de‑duplicate per‑app \`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‑size 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">…</main>
+\`\`\`
+
+**Dialog (Radix + shadcn/ui) — 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‑visible flows.
+
+---
+
+## 11) References (internalize; no external dependency at runtime)
+
+- WCAG 2.2 (AA), EN 301 549. 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’t 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.
+`
+  }
+];
+registerDocBlocks(accessibility_wcag_compliance_specs_DocBlocks);
+export {
+  accessibility_wcag_compliance_specs_DocBlocks
+};