Complete TSDoc coverage for intentional public exports

[woksin]

Problem

@cratis/components is a framework library, so exported TypeScript is product surface. Components 4 documents the changed foundation APIs, stable parts/tokens, migration aliases, Canvas core, and command-field part types, but a static export audit still finds older exported declarations with missing TSDoc—especially PivotViewer internals, Filter helpers, notification dispatch types, lower-level Canvas chat/emoji/mention helpers, schema types, and TimeMachine types.

Missing source documentation makes editor IntelliSense incomplete and blurs whether a symbol is a supported contract or an implementation detail accidentally re-exported by a broad barrel.

Direction

Do not add prose indiscriminately to implementation internals. First decide whether each symbol should remain public:

1. Build the actual export graph from every Source/package.json subpath and barrel.
2. Remove/narrow accidental exports in a semver-appropriate release.
3. Add concise TSDoc to every intentional exported declaration and every public member/property.
4. Include defaults, units, controlled/uncontrolled behavior, callback timing, precedence, accessibility expectations, token/part stability, and deprecated/no-op compatibility semantics where relevant.
5. Generate or validate API reference output from declarations so documentation cannot silently regress.

Acceptance criteria

• Every intentional exported interface, type, enum, function, class, component, and constant has TSDoc.
• Every property/method of an exported interface/class has a useful description.
• Public component props document defaults and state ownership.
• Exported part types identify the rendered semantic element for each key.
• Deprecated/compatibility members carry @deprecated and migration guidance.
• The gate follows package subpaths/barrels rather than scanning all source exports (internal files may export locally without becoming package API).
• A CI check fails when an intentional public declaration/member loses documentation.
• The published Components reference links generated API material from each component page where useful.

Initial audit groups

• PivotViewer/** engine/hooks/utils and component props
• Filter/** state and histogram helper types
• Notifications/toast.ts dispatch/options/record types
• lower-level Canvas/shapes/ChatBubble/** avatar/emoji/mention/helper contracts
• types/JsonSchema.ts, types/TypeFormat.ts
• TimeMachine data types and remaining helper components

This is follow-up documentation debt, not a reason to expose React Aria or other implementation-library types. Public contracts remain Cratis-owned.

[woksin]

PR #177 classifies the existing root namespaces as intentional Components 4 compatibility because representative existing consumers use them broadly. Do not remove those exports in a normal 4.x release. Continue this issue as the package-export-driven TSDoc/API-reference audit; any future pruning needs explicit consumer evidence and an appropriate major boundary.

[woksin]

Implemented in PR #177 on final candidate 39b4334: the package-export graph is audited, accidental v4 removals are migration-documented, every intentional public declaration/member now has TSDoc, and verify-api-docs.mjs follows actual export-map barrels with deterministic self-tests and zero debt. Final evidence: 275/275 test files, 846/846 tests; 25/25 exports. Keep open until #177 merges.

[woksin]

Final Components 4 root contract is now setup-only on candidate 073e1d7. All component namespaces were removed from the root and remain available through explicit subpaths. A shipped TypeScript-AST codemod plus namespace-aware ESLint autofix covers every historical namespace, aliases, and type imports; exact export/API-doc/package-graph gates prevent drift. Keep open until PR #177 merges.

[cratis-stagehand]

Thanks for opening this - it has been received and will be looked at.

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.