suaveplan/openspec/changes/enterprise-react-docs/tasks.md

Tasks: enterprise-react-docs

Change ID: enterprise-react-docs Package: @suaveplan/react-docs Target path: react/platform/react-docs Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/docs, @suaveplan/react-translate

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree. Write package.json at 0.1.0, tsconfig.json, vitest.config.ts, scripts.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/docs workspace:^, @suaveplan/react-translate workspace:^, react-markdown catalog:docs, rehype-highlight catalog:docs, remark-gfm catalog:docs, lucide-react catalog:ui, tailwind-merge catalog:ui, @opentelemetry/api catalog:observability, tslib catalog:build.

---

2. Error codes and types

• Define DocsUiError; codes: DOCS_RENDER_FAILED, DOCS_LINK_UNSAFE.
• Define all prop types: DocViewerProps, DocNavProps, DocSearchProps, OrphanReportProps, DocStatsProps, DocBreadcrumbProps, CategoryBadgeProps, DocOutlineProps.

---

3. Utils

link-sanitiser

• sanitiseLink(href: string): string | null — strips javascript: URIs and protocols other than http:, https:, relative paths. Returns null for disallowed hrefs.
• Write link-sanitiser.test.ts (≤500 lines): safe hrefs pass through, javascript URIs return null, external blocked when allowExternal=false. { timeout: 5000 }.
• Write link-sanitiser.md.

---

4. Components

CategoryBadge

• Styled chip for doc category label. Accepts category: string, variant?: 'default' | 'outline'.
• Write test, stories (default, outline, all-categories, playground), md.

DocBreadcrumb

• Navigation breadcrumb from DocFile path. useTranslation for "Home" / separator aria.
• Write test, stories (default, deep-path, single, playground), md.

DocStats

• Total/package/category/orphan counts display. OTel docs.stats.view counter.
• Write test, stories (default, with-orphans, empty, playground), md.

OrphanReport

• Lists orphan docs with suggested parent locations from findOrphans. useTranslation for labels. OTel docs.orphan.click counter.
• Write test, stories (default, empty, playground), md.

DocOutline

• TOC panel derived from markdown heading nodes with scroll-spy highlight.
• Write test, stories (default, long-doc, no-headings, playground), md.

DocSearch

• Live search input with keyboard-navigable dropdown. role="combobox", aria-activedescendant, aria-expanded. Accepts onSearch(query): Promise<DocFile[]>. OTel docs.search counter on submit.
• Write doc-search.test.tsx (≤500 lines): renders results, keyboard nav (down/up/enter/escape), empty state, debounce. { timeout: 10000 }.
• Write stories (default, loading, empty, keyboard, playground), md.

DocNav

• Collapsible sidebar grouped by category → package. Keyboard expand/collapse (Enter/Space), arrow-key navigation between items. OTel docs.nav.expand counter.
• Write doc-nav.test.tsx (≤500 lines): renders tree, expand/collapse, keyboard nav, active-item highlight. { timeout: 5000 }.
• Write stories (default, all-expanded, single-category, playground), md.

DocViewer

• GFM markdown rendered via react-markdown + rehype-highlight. Breadcrumb, category badge, skip-link, <main> landmark. Intercepts relative links via sanitiseLink → onLinkClick. OTel docs.view counter on mount.
• Write doc-viewer.test.tsx (≤500 lines): renders markdown, code blocks highlighted, link interception fires onLinkClick, unsafe href blocked, skip-link present. { timeout: 5000 }.
• Write stories (default, code-blocks, with-outline, empty, playground), md.

---

5. E2E

• e2e/docs.spec.ts — Playwright:
  • Search for a term; select from dropdown; verify DocViewer renders the doc.
  • Click expand/collapse in DocNav; verify tree state toggles.
  • Click an orphan in OrphanReport; verify navigation fires.
  • Verify mobile viewport renders nav as collapsible drawer.

---

6. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-docs — green.
• bunx turbo test:coverage --filter=@suaveplan/react-docs — 100%.
• bun scripts/publish.ts --package @suaveplan/react-docs.
• Archive change folder.