86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 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
|
|
```
|