Skip to content

fix: integration findings — TextLoader line height, region height, hidden text, refresh-gap type - #101

Merged
b4rb13 merged 6 commits into
mainfrom
fix/integration-findings
Nov 20, 2026
Merged

b4rb13 merged 6 commits into
mainfrom
fix/integration-findings

Conversation

@b4rb13

@b4rb13 b4rb13 commented Nov 20, 2026

Copy link
Copy Markdown
Owner

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 ready or refreshing, 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 from pending straight to handoff. Before, it passed through ready while the handoff read the layout.

 data-presentation
-  pending → ready (handoff reads layout) → handoff → ready
+  pending → handoff (handoff reads layout) → ready
+
+:host([data-presentation=ready]) .p,
+:host([data-presentation=refreshing]) .p { contain: size }

Why not display: none or a clip? Both took the placeholder's loaders off screen. Their IntersectionObserver then set data-dotquilt-offscreen before React hydrated (a hydration warning in tests/react/tab-order). On the next pending → ready, that flag hadn't cleared yet, so the dissolve skipped them (tests/m4/dissolve). display: none also 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 are display: 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:

visiblePart(rect, element)
  for each ancestor up to the region
    overflow ≠ visible → clip to its padding box
      (skipped for absolutely positioned content until its containing block)
    clip: rect(…)       → clip to that rect
    clip-path: inset(…) → clip to the inset; any other shape → its box
  less than 2 px either way → not a target

4. DotquiltStyle accepts --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 main and passes here (Chromium):

tests/e2e/sizing.spec.ts
  TextLoader in a 28px/1.5 line, pending, empty value      line 53 px → 42 px (= plain text)
  TextLoader in a 28px/1 line                              32 px → 28 px
  region (8-line placeholder, 1-line content), ready       180 px → 22 px (= content); 180 px during the handoff
  same with timing { duration: 0 } (an error)              180 px → 22 px
  region that starts ready / refreshing                    placeholder height → content height
tests/e2e/reveal.spec.ts
  hidden <thead>: Tailwind sr-only, visually-hidden clip,
  clip-path alone, zero-height box                         26 marks off the cells → 0
tests/react/consumer.tsx (bun run check, pack-smoke on TS 7 and 5.7)
  style={{ '--dotquilt-refresh-gap': '10px' }}             TS2353 → compiles

The handoff ordering is covered too: with the CSS but without the pending → handoff change, 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 of lines × 1lh. They pass on main too, as docs tests should.

bun run verify passes 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

  • Upgraded regions whose placeholder is taller than their content now shrink when the handoff ends, instead of keeping blank space. Their server markup already did this (hidden on a ready placeholder, display: none in the React static CSS); upgraded regions now match it.
  • A taller placeholder still overflows the region, hidden, down to where the region used to end. It no longer pushes anything down. It can still add scroll extent when the region is the last thing in a scroll container, but never more than before.
  • Code that watched data-presentation for ready between pending and handoff won't see it any more. Nothing in the runtime did: every check is !== 'pending'.
  • A TextLoader's mask and content now align on one baseline. They share a font, so nothing should move. A ready TextLoader still keeps its mask's width; this PR leaves that alone.
  • Text partly clipped by overflow (truncated cells) gets marks only where it shows.
  • Merging deploys dotquilt.dev with the docs changes. The setup prompt keeps its 0.1.1 workarounds (vertical-align: top on 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

b4rb13 and others added 5 commits November 21, 2026 00:43
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>
@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
dotquilt Ready Ready Preview Nov 20, 2026 10:34pm UTC

Request Review

@b4rb13
b4rb13 merged commit bd66b77 into main Nov 20, 2026
9 checks passed
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