actual-css 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## [Unreleased]
 
+
+## [0.9.0] - 2026-09-13
+
+### Breaking changes
+
+- `--choice-control-offset` is renamed `--choice-control-nudge` and adds to the
+  derived first-line offset instead of replacing it — an old value is a whole
+  offset and will sit that far too low.
+- `--skeleton-width` is a maximum inline size, not a width: a placeholder fills
+  its container and stops there, so it no longer gives every shrink-to-fit
+  ancestor a min-content floor. A placeholder in a container sized by its own
+  content now collapses instead of forcing that container open.
+
+### Fixed
+
+- `.choice` aligns its control on the first line's cap height with the `cap`
+  unit, so a checkbox, radio or switch is level with the label text in any
+  font — the previous constant was tuned for Segoe UI and sat ~2px low on
+  Roboto.
+- `.switch` lays its knob out of flow, so the track's baseline is its own
+  border box.
+- `dialog.drawer` is `--viewport-block` tall again, so a mobile browser's
+  collapsing URL bar no longer pushes its footer below the fold.
+- `dialog.drawer` scrolls its body region, so the footer stays reachable
+  whatever the content length; the rule replaces the `nav`-only one.
+- `.table-wrap` is `position: relative`, so an `.sr-only` header inside a wide
+  table no longer escapes the scroller and gives the page a phantom horizontal
+  scrollbar on small viewports.
+
+### Documentation and tooling
+
+- `tests/browser/mobile-overflow.test.js` asserts that no component scrolls the
+  page sideways at 320px and 360px, and that wide content scrolls inside its
+  own container.
+- `bun run report:overflow` surveys demo and site pages at phone width and
+  bisects each failure down to the element that owns it.
+- `tests/browser/mega-menu.test.js` exercises three wide sibling nav panels —
+  takeover, toggle, focus handover, keyboard open, Escape, clamping at both
+  viewport edges, and no drawer mutation on a phone.
+- The flyout hooks are documented as a preferred width and a width cap, with
+  the cap's `20rem` default stated: a wide panel sets both, like `width` and
+  `max-width`.
+- The drawer and scrollable-modal pages state that a scrolling body region is
+  keyboard-focusable, takes a focus ring, and can claim a dialog's initial
+  focus — put the close control in the `header`, or use `autofocus`.
+- The kitchen-sink, blocks, blog, combobox and select-intents templates no
+  longer scroll sideways at phone widths.
+- The alert trailing-action recipe and the dashboard template add `.items-center`:
+  a trailing control makes the row taller than a line of text, which left the
+  start-aligned `.alert-icon` above the message.
+
 ## [0.8.0] - 2026-09-10
 
 Actual CSS 0.8 focuses on a cleaner component contract, more predictable sizing

package/dist/actual.full.css

@@ -2164,7 +2164,7 @@ small {
  * geometry and states. switch.css is imported after this file.
  *
  * Public hooks:
- * --choice-control-offset
+ * --choice-control-nudge
  * --choice-border
  * --choice-bg
  * --choice-mark
@@ -2196,45 +2196,89 @@ small {
   cursor: pointer;
 }
 
-/* Optical alignment: nudge the control down so it sits visually centered with
-   the first line of label text, not flush with the top of the line-box. Every
-   inline choice runs the same formula — center the control's own block size on
-   the first line box, then drop it 0.0625em so it reads level with the
-   cap-height rather than the em-box. A checkbox and a switch therefore stay
-   level with each other under any line-height or --choice-control-size, which
-   a per-control constant cannot do (a taller switch and a shorter checkbox
-   need different offsets to land on the same optical line).
-
-   The constants are what the formula yields at the default 1.5 line-height:
-   0.25em (4px) for a checkbox, 0.1875em (3px) for the taller switch track.
-   They serve browsers without lh units. Multi-line labels still keep the
-   control at the top thanks to align-items: flex-start.
-
-   --choice-control-offset stays fallback-only rather than declared here, so an
-   override placed anywhere up the tree — :root included — reaches the control
-   instead of losing to a component-level declaration. */
+/* Optical alignment: the control reads level with the first line's cap height,
+   not with the top of its line box. Every inline choice runs the same formula
+   over its own block size, so a checkbox and a taller switch stay level with
+   each other under any line-height or --choice-control-size — something a
+   per-control constant cannot do.
+
+   Three tiers, each the best the engine can express:
+
+   - `cap` unit: exact, and the only font-independent answer. Where the cap
+     center sits inside a line box depends on the font's ascent/descent/cap
+     ratios, so no constant can serve both Segoe UI and Roboto — the same rule
+     was a pixel high on Windows and two pixels low on Android. Baseline
+     alignment puts the control's border-box bottom on the text baseline, and
+     one inset drops it by half the difference between its own height and the
+     cap height. Both classed controls synthesize that baseline from their
+     border box because their mark and knob are out of flow.
+   - `lh` only: center the control on the line box, which is within a pixel of
+     the cap center for the usual UI faces.
+   - neither: the constants that formula yields at the default 1.5
+     line-height, 0.1875em for a checkbox and 0.125em for the switch track.
+
+   --choice-control-nudge adds to whichever tier applies, rather than replacing
+   it: the derived value is exact now, so a design has a correction to make,
+   not a formula to restate — and one number cannot stand in for three
+   different references anyway. It stays fallback-only rather than declared
+   here, so an override placed anywhere up the tree — :root included — reaches
+   the control instead of losing to a component-level declaration. */
 .choice > :is(input[type="checkbox"]:not([role="switch"]), input[type="radio"]) {
   flex: 0 0 auto;
-  margin-block-start: var(--choice-control-offset, 0.25em);
+  margin-block-start: calc(0.1875em + var(--choice-control-nudge, 0px));
 }
 
 .choice > .switch {
   flex: 0 0 auto;
-  margin-block-start: var(--choice-control-offset, 0.1875em);
+  margin-block-start: calc(0.125em + var(--choice-control-nudge, 0px));
 }
 
 @supports (margin-block-start: 1lh) {
   .choice > :is(input[type="checkbox"]:not([role="switch"]), input[type="radio"]) {
-    margin-block-start: var(
-      --choice-control-offset,
-      calc((1lh - var(--choice-control-size)) / 2 + 0.0625em)
+    margin-block-start: calc(
+      (1lh - var(--choice-control-size)) /
+      2 +
+      var(--choice-control-nudge, 0px)
+    );
+  }
+
+  .choice > .switch {
+    margin-block-start: calc(
+      (1lh - var(--switch-block-size)) /
+      2 +
+      var(--choice-control-nudge, 0px)
+    );
+  }
+}
+
+@supports (margin-block-start: 1cap) {
+  .choice {
+    align-items: baseline;
+  }
+
+  /* Baseline alignment owns the block position now; the tier above would only
+     grow the row. An unclassed native input keeps the UA's own baseline, which
+     is already tuned for text — the formula below describes the framework's
+     geometry and would not fit it. */
+  .choice > :is(input[type="checkbox"], input[type="radio"]) {
+    margin-block-start: 0;
+  }
+
+  /* inset-block-start rides the `position: relative` these controls already
+     carry for their mark and knob. */
+  .choice > :is(.check, .radio) {
+    inset-block-start: calc(
+      (var(--choice-control-size) - 1cap) /
+      2 +
+      var(--choice-control-nudge, 0px)
     );
   }
 
   .choice > .switch {
-    margin-block-start: var(
-      --choice-control-offset,
-      calc((1lh - var(--switch-block-size)) / 2 + 0.0625em)
+    inset-block-start: calc(
+      (var(--switch-block-size) - 1cap) /
+      2 +
+      var(--choice-control-nudge, 0px)
     );
   }
 }
@@ -2782,8 +2826,6 @@ small {
 
   position: relative;
   display: inline-grid;
-  align-items: center;
-  justify-content: start;
   inline-size: var(--switch-width);
   block-size: var(--switch-block-size);
   margin: 0;
@@ -2802,9 +2844,17 @@ small {
    against the track is what makes the knob legible. */
 .switch::before {
   content: "";
+  /* Out of flow like the checkbox mark, so the track carries no in-flow item
+     and the switch synthesizes its baseline from its own border box. A knob
+     laid out as a grid item makes the baseline the knob's bottom edge instead,
+     which is what .choice measures its cap-height offset from. The inset is
+     the same --switch-knob-margin on both axes: it resolves against the
+     padding box, so the border is already out of the way. */
+  position: absolute;
+  inset-block-start: var(--switch-knob-margin);
+  inset-inline-start: var(--switch-knob-margin);
   inline-size: var(--switch-knob-size);
   block-size: var(--switch-knob-size);
-  margin-inline: var(--switch-knob-margin);
   border-radius: var(--radius-full);
   background: var(--switch-knob);
   transition:
@@ -4491,7 +4541,7 @@ dialog.modal {
   /* --modal-size stays fallback-only: declaring it on dialog.modal gives it
      type+class specificity, which a single author class cannot outrank, so the
      public hook would silently keep this default. Same reason choice.css never
-     declares --choice-control-offset. */
+     declares --choice-control-nudge. */
   max-inline-size: min(calc(100% - var(--dialog-viewport-gap-2x)), var(--modal-size, 32rem));
 
   /* Stable viewport cap for the panel: dvh tracks the dynamic browser toolbar
@@ -4817,15 +4867,24 @@ dialog.drawer {
 
   /* Keep the surface anchored to the viewport in the top layer. This also
      provides the containing block for the absolutely positioned close button.
-     A percentage height resolves against the fixed containing viewport, while
-     dynamic viewport units can be stale in embedded previews. */
+
+     The panel reaches both viewport edges, so it has to follow the space that
+     is actually on screen: --viewport-block resolves to 100dvh and tracks a
+     mobile browser's collapsing URL bar. A percentage resolves against the
+     layout viewport instead, which those browsers size as if the bar were
+     hidden — that put the footer below the fold for as long as it showed. The
+     modal pins the small viewport for the opposite reason: it floats, so a
+     stable height beats a panel that breathes while the bar moves.
+
+     An embedded preview that fakes a viewport overrides --viewport-block on
+     its own shell; the component does not degrade to a percentage for it. */
   position: fixed;
   inset-block-start: 0;
 
   inline-size: min(calc(var(--viewport-inline) * 0.9), var(--drawer-size));
-  block-size: 100%;
+  block-size: var(--viewport-block);
   max-inline-size: none;
-  max-block-size: 100%;
+  max-block-size: var(--viewport-block);
   margin: 0;
   padding: var(--drawer-pad);
   border: 0;
@@ -4897,10 +4956,16 @@ dialog.drawer[open]::backdrop {
   }
 }
 
-/* Scrollable navigation region inside the drawer. */
-dialog.drawer nav {
+/* The body region absorbs the panel's height and scrolls. A drawer is a
+   full-height shell by definition, so it always scrolls its body — unlike the
+   modal, which sizes to its content and opts in with .scrollable. Header and
+   footer keep their own tracks; .drawer-close is named because a generic
+   exclusion list is easier to trust than its `position: absolute`. */
+dialog.drawer > :not(:is(header, footer, form, .drawer-close)),
+dialog.drawer > form > :not(:is(header, footer, .drawer-close)) {
   min-block-size: 0;
-  overflow-y: auto;
+  overflow: auto;
+  overscroll-behavior: contain;
 }
 
 @supports (transition-behavior: allow-discrete) {
@@ -5672,16 +5737,24 @@ dialog.drawer > form > header {
  * --skeleton-track
  * --skeleton-highlight
  */
+/* A placeholder fills its container up to --skeleton-width; the preset widths
+   are a cap, never an intrinsic size. Stated the other way round — a rem
+   `inline-size` capped by a percentage `max-inline-size` — the cap is ignored
+   during intrinsic sizing, so every shrink-to-fit ancestor inherits the
+   preset as a min-content floor: a card holding a title placeholder could not
+   go below 18rem and pushed a phone's layout sideways. A percentage
+   `inline-size` contributes nothing intrinsically and a rem cap only lowers
+   the contribution, so the same geometry costs no floor. */
 .skeleton {
   --skeleton-size: 1rem;
-  --skeleton-width: 100%;
+  --skeleton-width: none;
   --skeleton-radius: var(--radius);
   --skeleton-track: var(--surface-subtle);
   --skeleton-highlight: var(--surface-raised);
 
   display: block;
-  inline-size: var(--skeleton-width);
-  max-inline-size: 100%;
+  inline-size: 100%;
+  max-inline-size: var(--skeleton-width);
   block-size: var(--skeleton-size);
   border-radius: var(--skeleton-radius);
   background:
@@ -5705,11 +5778,14 @@ dialog.drawer > form > header {
   --skeleton-width: 18rem;
 }
 
+/* The one preset with a real intrinsic width: a disc is square, so it sizes
+   rather than caps. The floor it does carry is the avatar size, which is small
+   enough never to widen a layout. */
 .skeleton[data-shape="avatar"] {
   --skeleton-size: var(--avatar-size, 2.25rem);
-  --skeleton-width: var(--skeleton-size);
   --skeleton-radius: var(--radius-full);
 
+  inline-size: var(--skeleton-size);
   flex: 0 0 auto;
 }
 
@@ -7623,6 +7699,14 @@ a.list-item[aria-current]::before {
  * --table-cell-pad
  */
 .table-wrap {
+  /* Containing block for anything absolutely positioned inside the table —
+     `.sr-only` on a column header above all. Without it that box resolves
+     against the initial containing block, so it keeps the static position of a
+     cell that may be a thousand pixels along the scrolled row, escapes this
+     scroller, and extends the *document's* scrollable width. The page then
+     scrolls sideways on a phone with nothing painted out there. */
+  position: relative;
+
   inline-size: 100%;
   max-inline-size: 100%;
   min-inline-size: 0;