Initial Commit

openspec/changes/enterprise-react-docs/proposal.md

@@ -0,0 +1,85 @@
+# OpenSpec Change: enterprise-react-docs
+
+- **Change ID**: enterprise-react-docs
+- **Package**: `@suaveplan/react-docs`
+- **Category**: react
+- **Target path**: `react/platform/react-docs`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-docs.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-docs` on genesis from scratch at enterprise quality. A docs browser on top of `@suaveplan/docs`: `DocViewer` (GFM markdown + syntax highlighting + breadcrumb + link interception), `DocNav` (collapsible sidebar grouped by category), `DocSearch` (live keyboard-navigable dropdown), `OrphanReport`, `DocStats`, `DocBreadcrumb`, and `CategoryBadge`. Genesis ships all prop types explicitly from `index.ts`, kebab-case file naming, Storybook for every component, accessibility (WCAG 2.2 AA with combobox ARIA for DocSearch, keyboard expansion for DocNav), link sanitisation, OTel counters, and Playwright E2E.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/docs` (`workspace:^`) | Doc graph + search engine |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n for all UI strings |
+| `@opentelemetry/api` (`catalog:observability`) | `docs.view`, `docs.search`, `docs.link.click` counters |
+
+External: `react-markdown catalog:docs`, `rehype-highlight catalog:docs`, `remark-gfm catalog:docs`, `lucide-react catalog:ui`, `tailwind-merge catalog:ui`, `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+// Components
+DocViewer, DocNav, DocSearch, OrphanReport, DocStats, DocBreadcrumb, CategoryBadge
+
+// Prop types (all exported from index.ts)
+DocViewerProps, DocNavProps, DocSearchProps, OrphanReportProps,
+DocStatsProps, DocBreadcrumbProps, CategoryBadgeProps
+```
+
+---
+
+## New additions for genesis
+
+1. **All prop types exported** from `index.ts` (main branch omitted them, forcing consumers to import from internal paths).
+2. **Kebab-case filenames** — `doc-viewer.tsx`, `doc-nav.tsx`, etc. (consistent with monorepo convention).
+3. **Storybook coverage** — default + playground + a11y + error/empty states for every component.
+4. **Accessibility** — `DocSearch` with `role="combobox"` / `aria-activedescendant`; `DocNav` keyboard expand/collapse; `DocViewer` skip-link + landmark roles.
+5. **Link sanitisation** — `DocViewer` strips `javascript:` and external hrefs before `onLinkClick`.
+6. **OTel counters** — `docs.view`, `docs.search`, `docs.link.click` via `@opentelemetry/api`.
+7. **Outline/TOC panel** — derived from markdown headings with scroll-spy.
+8. **Playwright E2E** — search + select, nav expand/collapse, orphan click-through, mobile viewport.
+
+---
+
+## File layout
+
+```text
+react/platform/react-docs/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    types/
+    doc-viewer/ (tsx + types + md + test + stories + index)
+    doc-nav/ (tsx + types + md + test + stories + index)
+    doc-search/ (tsx + types + md + test + stories + index)
+    orphan-report/ (tsx + types + md + test + stories + index)
+    doc-stats/ (tsx + types + md + test + stories + index)
+    doc-breadcrumb/ (tsx + types + md + test + stories + index)
+    category-badge/ (tsx + types + md + test + stories + index)
+    doc-outline/ (tsx + types + md + test + stories + index)
+    utils/
+      link-sanitiser.ts + test + md
+  e2e/
+    docs.spec.ts
+```