Repository navigation
docs(website): pretable docs PR 2 — Grid section (5 pages) + PR 1 cleanup - #61
Merged
Merged
Conversation
Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Three PR 1 pages reference a `<PretableGrid>` component that does
not exist. The actual public component is `<Pretable>` (3 props:
rows, columns, getRowId). `PretableGrid` is a TYPE export from
@pretable/core (the internal grid model), not a component.
Three fixes:
- /docs/page.mdx: rename "PretableGrid props" to "Pretable component
props" in the deferred-section list. Also moves Grid from "Coming
soon" to a documented section, since this PR ships /docs/grid.
- /docs/theming/density/page.mdx: remove the fictional
\`<PretableGrid rowHeight={56} headerHeight={64} />\` example. The
\`<Pretable>\` component does not accept rowHeight/headerHeight
props. The engine bridge runs via the useResolvedHeights hook
reading CSS values; consumers who need JS-side numeric overrides
pass them to the hook directly.
- /docs/theming/light-dark/page.mdx: change one in-prose
\`<PretableGrid>\` reference to \`<Pretable>\`.
Part 1 of pretable docs PR 2.
Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Code review on Task 1 of pretable docs PR 2 flagged a leftover "(PR 2 of the docs)" hedge in the Density page's "Where to go next" link to /docs/grid/density-helpers. That target ships in the same PR — the annotation reads stale once merged. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Adds the Grid section to the docs sidebar with 5 entries pointing at pages that subsequent commits in this PR create: - Overview (/docs/grid) - <Pretable> component (/docs/grid/pretable-component) - Custom rendering (/docs/grid/custom-rendering) - Density helpers (/docs/grid/density-helpers) - API reference (/docs/grid/api-reference) The build passes here because Next.js doesn't validate href targets at build time. Part 2 of pretable docs PR 2. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Documents the two consumer paths for @pretable/react: 1. <Pretable> drop-in component (3 props: rows, columns, getRowId). Wraps the engine with sensible defaults; basic display only. 2. usePretable / usePretableModel hooks for custom rendering. Power-user escape hatch; consumers write their own JSX, apply [data-pretable-*] data attributes for styling, wire interaction via the grid model. PretableSurface lives in @pretable-internal/react-surface (private) and is not part of the public API — bench and website's playground use it via the internal path; external consumers use the hooks. Documents the [data-pretable-*] attribute contract that both paths emit (and that @pretable/ui/grid.css targets), and the two CSS variables the engine reads in JS (--pretable-row-height, --pretable-header-height) via useResolvedHeights. Honest about what's not yet documented: autosize, streaming / transactions, per-row measured heights. Part 3 of pretable docs PR 2. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
The useResolvedHeights React hook (subscribes to <html>'s [data-density] / [data-theme] attribute changes via MutationObserver and re-resolves --pretable-row-height / --pretable-header-height) was previously internal to react-surface and only used by <Pretable> + <PretableSurface>. Promote it to the public API. Custom-rendering authors using usePretableModel need it to compute viewport math the same way the built-in surface does — without it, consumers either copy the hook source or lose reactivity to density / theme changes. Also exports the DensityHeights type. Pre-1.0; signature stable. Pretable docs PR 2 documents this hook as part of the public custom-rendering surface. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Code review on Task 3 of pretable docs PR 2 flagged three accuracy issues: 1. Drop "monospace cells" from <Pretable>'s hardcoded defaults. The component renders cells as label-above-value spans; monospace styling only applies if a theme provides --pretable-font-mono. Defaults are now described as label-above-value layout + 320px viewport. 2. [data-pretable-wrap] row in the attribute table — the attribute is a modifier on the same div that has [data-pretable-cell], not a distinct element. Updated element column to "each body cell (modifier)" and clarified coexistence in the purpose column. Custom-rendering authors reading the table to replicate the contract now see correct DOM structure. 3. [data-focused] row — the attribute appears on BOTH the row and the focused cell, so CSS can target either. Updated element column to "focused row + cell" and noted the mirror in the purpose column. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Documents the 3-prop drop-in component: columns, rows, getRowId. Includes a complete code example with PretableColumn typing and the rendered output's theming via @pretable/ui. Honest about limitations: no sort UI, no filter UI, no selection state in component tree, no custom cell rendering, no pinned columns, no measured-height passthrough. All of those require custom rendering with usePretable / usePretableModel hooks. Lists the hardcoded defaults (320px viewport, label/value layout, sort-direction indicator) so consumers know what they're getting. Part 4 of pretable docs PR 2. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Documents usePretableModel as the public API for custom grid rendering. Covers when to use it vs <Pretable> drop-in, the hook signature, the four return values (grid, snapshot, renderSnapshot, telemetry), and a minimal-but-complete working example (~80 lines of JSX). The example shows: scrollable viewport with [data-pretable-*] attributes, sticky header with sort-on-click, virtualized body with absolute-positioned rows, click-to-select wiring via grid.selectRow + grid.setFocus. Honest about gaps: keyboard navigation, pinned column sticky positioning, per-row measured heights, filter inputs, and telemetry instrumentation are NOT covered in the example — points readers at packages/react-surface/src/pretable-surface.tsx in the repo as the canonical reference (private API path, but readable source). Part 5 of pretable docs PR 2. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Documents the two functions for reading density values into JS: - useResolvedHeights (React hook, in @pretable/react): reactive via useSyncExternalStore + MutationObserver, optional numeric overrides as arguments, fallbacks 32/52, SSR-safe. - getDensityHeights (vanilla snapshot, in @pretable/ui): same read logic without subscription. For non-React utilities or one-shot reads. Includes a when-to-use table comparing the two and a note that <Pretable> and the internal <PretableSurface> use useResolvedHeights internally to compute viewport math. Part 6 of pretable docs PR 2. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Hand-authored type reference for @pretable/react's public API: - PretableColumn<TRow> field table (id, header, wrap, widthPx, pinned, sortable, filterable, getValue) - PretableRow type alias - PretableGrid model methods table (getSnapshot, subscribe, setSort, setFilter, clearFilters, replaceFilters, selectRow, setFocus, moveFocus, setViewport, applyTransaction, autosizeColumns) - PretableGridSnapshot interface - UsePretableOptions / UsePretableModelOptions interfaces - PretableModel return type (grid, snapshot, renderSnapshot, telemetry) - PretableRenderSnapshot / PretableRenderRow / PlannedColumn interfaces - PretableTelemetry interface - Hook signatures: usePretable, usePretableModel, useResolvedHeights, measureRenderedRowHeight Pre-1.0 disclaimer at the top — names may rename in patch releases. Part 7 of pretable docs PR 2. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Three issues from the whole-PR final code review: 1. /docs/grid Grid Overview linked to /docs/streaming, which does not yet exist (it ships in docs PR 3). The link 404s. Drop the href; keep the prose as a forward-reference statement. 2. PretableTelemetry was missing from @pretable/react's public type exports despite being part of the documented PretableModel shape. Add it to the type-export block (alphabetical) so consumers can name-import it like the other model types. 3. /docs/grid/custom-rendering said getPinnedLeftOffsets is "re-exported as part of the internal API" — incorrect. The helper lives in packages/react-surface/src/rendering.ts and is not exported from the package's index. Updated the prose to point at the source file directly, matching the existing pattern for "see the canonical implementation in pretable-surface.tsx". Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
blove
enabled auto-merge (squash)
May 2, 2026 17:14
Contributor
Vercel preview readyPreview: https://pretable-c6v987bpd-cacheplane.vercel.app Updated automatically by the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships the Grid section of the pretable docs (5 pages) — the second of four PRs in the docs arc. Also fixes three PR 1 references to a non-existent
<PretableGrid>component, extends the docs nav, and promotesuseResolvedHeightsfrom internal to public so custom-rendering authors can use it.What lands
5 new Grid pages under
apps/website/app/docs/grid/:page.mdx— Overview: the two consumer paths +[data-pretable-*]attribute contractpretable-component/page.mdx—<Pretable>3-prop drop-in recipecustom-rendering/page.mdx—usePretableModelrecipe with ~80-line working exampledensity-helpers/page.mdx—useResolvedHeights+getDensityHeightsreferenceapi-reference/page.mdx— full type reference (PretableColumn, PretableGrid model, snapshots, hooks)Public API expansion (small, deliberate):
useResolvedHeightspromoted from internal to public export of@pretable/react. Custom-rendering authors usingusePretableModelneed it to compute viewport math the same way the built-in surface does.PretableTelemetryadded to public type exports for symmetry with the rest ofPretableModel.PR 1 cleanup (the previous docs PR shipped 3 references to a
<PretableGrid>component that doesn't exist):apps/website/app/docs/page.mdx— fixed "API Reference" entry; moved Grid out of "Coming soon"apps/website/app/docs/theming/density/page.mdx— removed fictional<PretableGrid rowHeight={56} headerHeight={64} />exampleapps/website/app/docs/theming/light-dark/page.mdx— fixed in-prose<PretableGrid>referenceNav extended from 2 sections to 3: Getting Started, Theming, Grid (5 entries).
Out of scope (deferred to later PRs)
<Pretable>component API expansion —<Pretable>stays minimal; the hooks remain the escape hatchapps/website/app/components/CodeExample.tsxstill uses fictional<PretableGrid>on the landing page (pre-existing, tracked separately)Test Plan
pnpm --filter @pretable/app-website build— 19 static routes prerender, including all 5 new Grid pagespnpm test— 51/51 passpnpm typecheck— exit 0pnpm exec prettier --check apps/website/app/docs— all files compliant<PretableGrid>JSX-style references remain inapps/website/app/docs/PretableTelemetry.visibleRowRangeis{start, end}numerics)