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

// 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

All prop types exported from index.ts (main branch omitted them, forcing consumers to import from internal paths).
Kebab-case filenames — doc-viewer.tsx, doc-nav.tsx, etc. (consistent with monorepo convention).
Storybook coverage — default + playground + a11y + error/empty states for every component.
Accessibility — DocSearch with role="combobox" / aria-activedescendant; DocNav keyboard expand/collapse; DocViewer skip-link + landmark roles.
Link sanitisation — DocViewer strips javascript: and external hrefs before onLinkClick.
OTel counters — docs.view, docs.search, docs.link.click via @opentelemetry/api.
Outline/TOC panel — derived from markdown headings with scroll-spy.
Playwright E2E — search + select, nav expand/collapse, orphan click-through, mobile viewport.

File layout

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

3.4 KiB Raw Blame History