Skip to content

refactor(react): audit @pretable/react public surface; rename usePretableModel → usePretable - #111

Merged
blove merged 9 commits into
mainfrom
api-stabilization-react
May 8, 2026
Merged

refactor(react): audit @pretable/react public surface; rename usePretableModel → usePretable#111
blove merged 9 commits into
mainfrom
api-stabilization-react

Conversation

@blove

@blove blove commented May 8, 2026

Copy link
Copy Markdown
Contributor

Summary

PR 3 of 5 for Tier 1 Sub-project A — Public API Stabilization. Audits `@pretable/react` per PR 3's design spec.

  • Hook brevity rename. `usePretableModel` → `usePretable` (the simple-sounding name now points to the hook docs already use). The old low-level `usePretable` (just `useMemo(() => createGrid(opts))`) is deleted; consumers can inline that pattern if needed. `UsePretableModelOptions` → `UsePretableOptions`; the strict-subset old `UsePretableOptions` is deleted. 8 website docs updated.
  • `public_api.ts` convention. Hand-curated public surface; `index.ts` is one line.
  • Three demotions to `ɵ`-prefix (Angular-style internal-but-exported marker). `useResolvedHeights` → `ɵuseResolvedHeights`, `measureRenderedRowHeight` → `ɵmeasureRenderedRowHeight`, `ROW_SELECT_COLUMN_ID` → `ɵROW_SELECT_COLUMN_ID`. Tagged `@internal` at source.
  • Five `@beta` tags on `InspectionGrid`, `LabeledGridSurface`, and their props/format-input types.
  • Two deletions. `PretableCoreColumn` alias (use `PretableColumn` from `@pretable/core` if the headless base is needed). `PretableSurfaceSortDirection` leak (replaced with `PretableSortDirection` from core).
  • TSDoc + `@public` on every public symbol. Zero `(undocumented)` annotations in `react.api.md`.
  • Per-package `README.md` with the "when to reach for what" table.
  • Clipboard symbols stay `@public`. Per user feedback: clipboard is stable API. Docs alignment captured in `project_clipboard_docs_followup.md` memory.

Spec correction surfaced during execution

  • `ae-internal-missing-underscore` silenced in `api-extractor.base.json`. api-extractor expects `_underscore` prefix for `@internal` symbols; pretable uses Angular's `ɵ` convention. Same approach as PR 2's other config tweaks.

Test plan

  • `pnpm -w typecheck` clean
  • `pnpm -w test` clean (205 react tests pass)
  • `pnpm -w lint` clean
  • `pnpm format` clean
  • `pnpm api:check` clean (all 4 packages)
  • `react.api.md` shows `usePretable` returning `PretableModel`; no `usePretableModel`
  • `react.api.md` has `ɵ`-prefixed exports for the 3 demoted symbols
  • `InspectionGrid` / `LabeledGridSurface` annotated `@beta`
  • `PretableCoreColumn` and `PretableSurfaceSortDirection` gone

🤖 Generated with Claude Code

blove and others added 9 commits May 8, 2026 11:36
Renames usePretableModel → usePretable (deleting the old PretableGrid-
returning usePretable); demotes useResolvedHeights, measureRenderedRowHeight,
ROW_SELECT_COLUMN_ID to ɵ-prefix at re-export; tags InspectionGrid,
LabeledGridSurface and their props @beta; deletes PretableCoreColumn alias
and PretableSurfaceSortDirection leak; clipboard symbols stay @public per
user feedback (docs alignment captured as separate follow-up).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…plan

7 tasks: hook rename + ripple, fix PretableSurfaceSortDirection leak,
TSDoc + release tags, public_api.ts + index.ts collapse, regenerate
react.api.md + audit diff, per-package README, gates+PR.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…vel usePretable

The simple-sounding name now points to the hook docs already use.
Old usePretable (returning just PretableGrid) was a one-line useMemo
wrapper around createGrid; deleted. UsePretableModelOptions is now
UsePretableOptions; the strict-subset old UsePretableOptions deleted.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ableSortDirection from core

Eliminates the ae-forgotten-export warning on react.api.md. The local
alias was just a more verbose way of saying 'asc | desc | null'.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds TSDoc summaries with release tags on every public, beta, and
internal symbol so api-extractor's report shows annotated API
instead of @public (undocumented). Tags InspectionGrid,
LabeledGridSurface, and their props @beta. Tags useResolvedHeights,
measureRenderedRowHeight, ROW_SELECT_COLUMN_ID @internal — public_api.ts
will re-export them with ɵ-prefix in the next task.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
public_api.ts is the single source of truth for the package's public
surface. index.ts collapses to a one-line re-export. Three internal-use
exports demoted to ɵ-prefix at the public boundary:
ɵuseResolvedHeights, ɵmeasureRenderedRowHeight, ɵROW_SELECT_COLUMN_ID.
PretableCoreColumn alias deleted — use PretableColumn from @pretable/core
if the headless base type is what you need.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…missing-underscore

react.api.md: hook rename, 3 ɵ-prefix demotions, 5 @beta tags,
deletion of PretableCoreColumn alias and PretableSurfaceSortDirection
leak, @public TSDoc on every public symbol — 0 (undocumented)
annotations.

ae-internal-missing-underscore silenced because pretable uses the
ɵ-prefix convention (Angular ecosystem) for "exported but @internal"
rather than api-extractor's _underscore convention.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…t; format pass

The ɵ-prefix demotion removed measureRenderedRowHeight from the public
re-export. Internal tests can still import from ../row-height directly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@vercel

vercel Bot commented May 8, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
pretable Error Error May 8, 2026 7:12pm

@blove
blove enabled auto-merge (squash) May 8, 2026 19:11
@blove
blove merged commit 57e7f79 into main May 8, 2026
12 of 13 checks passed
@blove
blove deleted the api-stabilization-react branch May 8, 2026 19:14
@github-actions

github-actions Bot commented May 8, 2026

Copy link
Copy Markdown
Contributor

Vercel preview ready

Preview: https://pretable-gu4m0uyv6-cacheplane.vercel.app
Commit: e9d0bdf5e342b2ad2adcfab91bd4875825d935bf

Updated automatically by the deploy-preview job.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant