Repository navigation
fix: integration findings — TextLoader line height, region height, hidden text, refresh-gap type - #101
Merged
Conversation
While a TextLoader's value was still empty, only its mask had text. The content layer comes first in the inline grid and had no baseline, so the grid's baseline was synthesized from that layer's bottom edge and the loader sat on the line by its bottom: a 42px line at 28px type grew to 53px while pending. The layers now align on a shared baseline, which the mask provides while the content is empty. The test puts a pending TextLoader with a mask and no value in a 28px line (line-height 1.5 and 1) and compares the line with plain text: 53px and 32px before, 42px and 28px after. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The placeholder and content layers overlap in the region's grid, and the placeholder layer kept its space after `ready`. A placeholder taller than its content left blank space for good, and so did error states (`state="ready"` with `timing.duration: 0`). Once the region is ready or refreshing, the placeholder layer now gets `contain: size`. It stays laid out at its own size, hidden, but adds nothing to the region's height. `display: none` and an overflow clip both took its loaders off screen: their IntersectionObserver then marked them offscreen before React hydrated (a hydration warning), and the flag lagged on the next loading cycle, so the dissolve skipped them. While an external stylesheet loads, a document rule hides a ready region's placeholder, as the server markup already does. The handoff reads the placeholder's layout as it starts, so the presentation now goes from `pending` straight to `handoff` instead of passing through `ready`. Without that, six reveal tests fail because the morph reads a placeholder that isn't laid out. The tests hand over a region whose placeholder (200px) is taller than its content (22px): it stayed 200px after ready before, and is the content's height after, with and without a handoff, and for regions that start ready or refreshing. During the handoff the region keeps the placeholder's height. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The morph measures the content's text with getClientRects(), which ignores clipping. A visually hidden table header (a 1px box with `overflow: hidden`, `clip: rect(0,0,0,0)` or `clip-path: inset(50%)`) still measured as a full line of text, so the table handoff drew a stray row of marks for it. Text runs and content boxes are now clipped by their ancestors up to the region: `overflow` clips to the padding box (absolutely positioned content escapes it until its containing block), `clip: rect()` and `clip-path: inset()` clip to their rectangle, and other clip-path shapes count as the element's box. What shows less than 2px either way isn't a target. Partly clipped text, such as a truncated cell, gets marks only where it shows. The tests hand over a table whose header is hidden four ways (Tailwind's sr-only, a visually-hidden class with `clip`, `clip-path` alone, a zero-height box): 26 marks landed off the visible cells before, none after. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The theming and LoadingRegion pages document `--dotquilt-refresh-gap`,
but the React style type didn't list it, so
`style={{ '--dotquilt-refresh-gap': '10px' }}` failed to compile (TS2353).
The consumer type check (bun run check, and pack-smoke on TypeScript 7
and 5.7) now sets it on a LoadingRegion.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SkeletonText's lines are two rows of marks (18px with dots, 17px with squares, 19px with dashes) spaced 0.5em apart, which doesn't follow the text's line height. A default based on the line height would change the gap of every existing SkeletonText (8px to 6px at 16px/1.5), so it stays as it is and the Skeleton page shows the recipe instead: a gap and margins from 1lh. It uses margins, not padding: the idle glow's copy of the lines spans the padding box, so padding moves it up to 3px off the lines. The setup prompt points to the recipe. Tests check it with dots, squares and dashes: each line centred on a line of text, the glow on the lines, and a height of lines × 1lh. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Nov 20, 2026
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
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
Five findings from integrating Dotquilt 0.1.1 into a mock Next.js 16 app (React Query, chart, table, TextLoader KPIs, chat, profile card). Four are runtime fixes; the fifth is documented, because changing it would change how every SkeletonText looks.
1. A pending TextLoader no longer makes its line taller. With the value still empty, the first layer had no baseline, so the inline-grid sat on the line by its bottom edge (42 → 53 px at 28 px type). The layers now share one baseline: the mask's.
:host{display:inline-grid;vertical-align:baseline;min-height:1em} +:host [part]{align-self:baseline}2. A region is as tall as its content once it has handed over, and while it refreshes. Once the region is
readyorrefreshing, its placeholder layer gets size containment, so it adds nothing to the region's height. It keeps its place through the handoff, which reads it. So the presentation now goes frompendingstraight tohandoff. Before, it passed throughreadywhile the handoff read the layout.Why not
display: noneor a clip? Both took the placeholder's loaders off screen. Their IntersectionObserver then setdata-dotquilt-offscreenbefore React hydrated (a hydration warning intests/react/tab-order). On the next pending → ready, that flag hadn't cleared yet, so the dissolve skipped them (tests/m4/dissolve).display: nonealso zeroed the placeholder's box, which the layout suite pins. With containment, the placeholder stays laid out at its own size, hidden. While an external stylesheet loads, the layers aredisplay: contents, so a document rule hides a ready region's placeholder, as the server markup already does.3. The handoff skips text that's clipped away.
getClientRects()ignores clipping, so a visually hidden<thead>turned into a stray row of marks. Text runs and content boxes are now clipped by their ancestors up to the region:4.
DotquiltStyleaccepts--dotquilt-refresh-gap, which the theming and LoadingRegion pages already documented.5. SkeletonText line spacing stays as it is; the Skeleton page now shows how to match a line height. A default based on line height would change the gap on every existing SkeletonText (8 → 6 px at 16px/1.5), so that's the owner's call. The recipe is
gap: calc(1lh - 18px); margin-block: calc((1lh - 18px) / 2), with 17 px for squares and 19 px for dashes. It uses margins rather than padding: the idle glow's copy of the lines spans the padding box, so padding pushes it up to 3 px off the lines.Docs: the LoadingRegion page says how the region is sized in each state and that hidden text gets no marks. The setup prompt's SkeletonText line points to the recipe.
Evidence
Each new test fails on
mainand passes here (Chromium):The handoff ordering is covered too: with the CSS but without the
pending → handoffchange, 6 existing reveal tests fail, because the morph reads a placeholder that isn't laid out. Three tests also check the Skeleton page's recipe with dots, squares and dashes: each line centred on a line of text, the glow on the lines, and a height oflines × 1lh. They pass onmaintoo, as docs tests should.bun run verifypasses locally: lint, types, 102 unit tests, build, size budgets (LoadingRegion +7 B gzip; the lazily loaded morph chunk +0.9 KB), and 885 Chromium browser tests.Merge Danger
Door: two-way
Revert the PR. Nothing is published until a release PR is merged and approved on npm.
Blast Radius: layout
hiddenon a ready placeholder,display: nonein the React static CSS); upgraded regions now match it.data-presentationforreadybetweenpendingandhandoffwon't see it any more. Nothing in the runtime did: every check is!== 'pending'.overflow(truncated cells) gets marks only where it shows.vertical-align: topon an inline TextLoader; aria-labelled empty header cells instead of a visually hidden thead). They are still needed until a release with these fixes is on npm.🤖 Generated with Claude Code