# 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
```