actual-css 0.9.0 → 0.9.2

package/src/css/components/join.css

@@ -1,6 +1,8 @@
 /*
  * Join — visually groups adjacent controls into a single unit.
  *
+ * Docs: docs/pages/forms/joined-controls.md
+ *
  * This is a cross-cutting control primitive, not a forms-only component:
  * it applies equally to inputs, selects, buttons, and button-like links.
  *

package/src/css/components/key.css

@@ -1,6 +1,8 @@
 /*
  * Key — keyboard keys and shortcut tokens for UI chrome.
  *
+ * Docs: docs/pages/components/key.md
+ *
  * Use .key outside prose. Plain kbd inside .prose gets the same visual
  * treatment from prose.css so authored content stays convenient.
  *

package/src/css/components/list.css

@@ -3,6 +3,8 @@
  * Content determines the number of lines; the component only owns the row
  * geometry, dividers, and supporting-text treatment.
  *
+ * Docs: docs/pages/components/list.md
+ *
  * Public hooks:
  * --list-item-min-size
  * --list-item-pad-block

package/src/css/components/meter.css

@@ -1,6 +1,8 @@
 /*
  * Meter — native and segmented gauges for known-range values.
  *
+ * Docs: docs/pages/components/meter.md
+ *
  * Maps the three standard meter zones (optimum / suboptimum / even-less-good)
  * to the shared success / warning / danger intent colors.
  *

package/src/css/components/modal.css

@@ -1,6 +1,8 @@
 /*
  * Modal shell styling for native dialog elements.
  *
+ * Docs: docs/pages/components/dialog.md
+ *
  * Spacing, radius, transitions, and focus treatment come from shared tokens.
  * Opening behavior and intent-specific decisions stay outside this component.
  *
@@ -12,16 +14,15 @@
  *
  * Internal:
  * --dialog-close-icon-size
+ * --dialog-focus-bleed
  * --dialog-viewport-block
  * --dialog-viewport-gap-default
  * --dialog-viewport-gap-2x
  */
-dialog.modal {
-  /* --dialog-viewport-gap stays fallback-only for the same reason as
-     --modal-size below: declaring the public hook here would give it
-     type+class specificity that a single author class cannot outrank. The
-     responsive default lives in an internal token instead, so a media query
-     can still move it without closing the hook.
+:where(dialog).modal {
+  /* --dialog-viewport-gap stays fallback-only so the responsive default can
+     live in an internal token: a media query moves it without closing the
+     public hook.
 
      calc() multiplication is not in the supported browser range, so the
      doubled gap is spelled out with an additive calc. */
@@ -35,10 +36,8 @@ dialog.modal {
      provides the containing block for the absolutely positioned close button. */
   position: fixed;
 
-  /* --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-nudge. */
+  /* The root is :where(dialog).modal (0-1-0), so a single author class can
+     outrank these defaults — no fallback-only indirection needed here. */
   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
@@ -68,8 +67,8 @@ dialog.modal {
     transform var(--duration) var(--ease-exit);
 }
 
-dialog.modal > form,
-dialog.modal > .stack {
+:where(dialog).modal > form,
+:where(dialog).modal > .stack {
   display: grid;
   gap: var(--space-40);
   max-block-size: calc(var(--dialog-viewport-block) - var(--dialog-viewport-gap-2x));
@@ -79,7 +78,7 @@ dialog.modal > .stack {
 }
 
 @supports (block-size: 100svh) {
-  dialog.modal {
+  :where(dialog).modal {
     --dialog-viewport-block: 100svh;
   }
 }
@@ -87,42 +86,50 @@ dialog.modal > .stack {
 /* Keep the dialog off the viewport edges on small screens. Moves the internal
    default, not the public hook, so an author override still wins here too. */
 @media (max-width: 30rem) {
-  dialog.modal {
+  :where(dialog).modal {
     --dialog-viewport-gap-default: var(--space-30);
   }
 }
 
-dialog.modal.scrollable > form,
-dialog.modal.scrollable > .stack {
+:where(dialog).modal.scrollable > form,
+:where(dialog).modal.scrollable > .stack {
   grid-template-rows: auto minmax(0, 1fr) auto;
   overflow: hidden;
 }
 
-dialog.modal.scrollable > form > :not(:is(header, footer)),
-dialog.modal.scrollable > .stack > :not(:is(header, footer)) {
+:where(dialog).modal.scrollable > form > :not(:is(header, footer)),
+:where(dialog).modal.scrollable > .stack > :not(:is(header, footer)) {
+  --dialog-focus-bleed: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+
   min-block-size: 0;
+  /* Keep focus paint inside the clip without moving the body off the fixed
+     header and footer edges. */
+  margin-inline: calc(var(--dialog-focus-bleed) * -1);
+  padding-inline: var(--dialog-focus-bleed);
   overflow: auto;
   overscroll-behavior: contain;
 }
 
-dialog.modal header > :first-child,
-dialog.modal footer > :first-child {
+/* Anatomy is bounded to the structural slots (direct children of the
+   form/.stack body): a header or footer deeper in the content keeps its own
+   rhythm and is not restyled as the modal's chrome. */
+:where(dialog).modal > :where(form, .stack) > :is(header, footer) > :first-child {
   margin-block-start: 0;
 }
 
-dialog.modal header > :last-child,
-dialog.modal footer > :last-child {
+:where(dialog).modal > :where(form, .stack) > :is(header, footer) > :last-child {
   margin-block-end: 0;
 }
 
 /* The close button is anchored to the dialog at top inline-end, out of the
-   content flow; headers reserve inline room so titles never run under it. */
-dialog.modal > form > header,
-dialog.modal > .stack > header {
+   content flow; headers reserve inline room so titles never run under it.
+   The form/.stack anatomy is structural, so it stays in :where() and never
+   lends .stack's specificity to a bare <form>. */
+:where(dialog).modal > :where(form, .stack) > header {
   padding-inline-end: calc(var(--control-size) + var(--space-30));
 }
 
-dialog.modal footer {
+:where(dialog).modal > :where(form, .stack) > footer {
   display: flex;
   flex-wrap: wrap;
   justify-content: flex-end;
@@ -132,17 +139,17 @@ dialog.modal footer {
 /* Confirmation layout — a focused message followed by a visually distinct
    action band. The media primitive owns icon/content alignment; this variant
    only removes the standard form inset so both regions can own their padding. */
-dialog.modal.dialog-confirmation > form {
+:where(dialog).modal.dialog-confirmation > form {
   gap: 0;
   padding: 0;
 }
 
-dialog.modal.dialog-confirmation > form > .media {
+:where(dialog).modal.dialog-confirmation > form > .media {
   gap: var(--space-40);
   padding: var(--space-50);
 }
 
-dialog.modal.dialog-confirmation > form > footer {
+:where(dialog).modal.dialog-confirmation > form > footer {
   padding: var(--space-40) var(--space-50);
   border-end-start-radius: calc(var(--radius-lg) - var(--border-width));
   border-end-end-radius: calc(var(--radius-lg) - var(--border-width));
@@ -183,13 +190,13 @@ dialog.modal.dialog-confirmation > form > footer {
 }
 
 @media (max-width: 30rem) {
-  dialog.modal.dialog-confirmation > form > .media,
-  dialog.modal.dialog-confirmation > form > footer {
+  :where(dialog).modal.dialog-confirmation > form > .media,
+  :where(dialog).modal.dialog-confirmation > form > footer {
     padding: var(--space-40);
   }
 }
 
-dialog.modal[open] {
+:where(dialog).modal[open] {
   opacity: 1;
   transform: none;
   transition:
@@ -198,13 +205,13 @@ dialog.modal[open] {
 }
 
 @starting-style {
-  dialog.modal[open] {
+  :where(dialog).modal[open] {
     opacity: 0;
     transform: translateY(0.35rem);
   }
 }
 
-dialog.modal::backdrop {
+:where(dialog).modal::backdrop {
   background: var(--backdrop-fill);
   opacity: 0;
   /* Scrim curve stays neutral `ease`; only the panel carries the character
@@ -213,7 +220,7 @@ dialog.modal::backdrop {
 }
 
 @supports (transition-behavior: allow-discrete) {
-  dialog.modal {
+  :where(dialog).modal {
     transition:
       opacity var(--duration) var(--ease-exit),
       transform var(--duration) var(--ease-exit),
@@ -221,7 +228,7 @@ dialog.modal::backdrop {
       display var(--duration) allow-discrete;
   }
 
-  dialog.modal[open] {
+  :where(dialog).modal[open] {
     transition:
       opacity var(--duration) var(--ease-enter),
       transform var(--duration) var(--ease-enter),
@@ -229,7 +236,7 @@ dialog.modal::backdrop {
       display var(--duration) allow-discrete;
   }
 
-  dialog.modal::backdrop {
+  :where(dialog).modal::backdrop {
     transition:
       opacity var(--duration) ease,
       overlay var(--duration) allow-discrete,
@@ -237,7 +244,7 @@ dialog.modal::backdrop {
   }
 }
 
-dialog.modal[open]::backdrop {
+:where(dialog).modal[open]::backdrop {
   opacity: 1;
 }
 
@@ -250,7 +257,7 @@ html.has-modal-open.had-scrollbar {
 }
 
 @starting-style {
-  dialog.modal[open]::backdrop {
+  :where(dialog).modal[open]::backdrop {
     opacity: 0;
   }
 }
@@ -258,7 +265,7 @@ html.has-modal-open.had-scrollbar {
 @media (prefers-reduced-motion: no-preference) {
   /* Wrong-close feedback and view-transition transport are motion quirks, not
      presence enter/exit, so they stay on the plain CSS default easing. */
-  dialog.modal.is-static {
+  :where(dialog).modal.is-static {
     animation: actual-dialog-static var(--duration-slow) ease;
   }
 

package/src/css/components/navbar.css

@@ -1,6 +1,8 @@
 /*
  * Navbar — top-level navigation bar.
  *
+ * Docs: docs/pages/components/navbar.md
+ *
  * .navbar is a horizontal bar; .navbar-brand is the brand link; .navbar-nav is
  * the inline link list using .nav-link items. .nav-list is the vertical nav
  * list shared with .drawer, fed by the shared --gap token.

package/src/css/components/pagination.css

@@ -1,6 +1,8 @@
 /*
  * Pagination — page navigation for paginated lists.
  *
+ * Docs: docs/pages/components/pagination.md
+ *
  * Render .btn elements inside a .pagination list. The active page is marked
  * with aria-current="page"; .btn owns the active state styling.
  *

package/src/css/components/progress.css

@@ -1,6 +1,8 @@
 /*
  * Progress — native progress bar with theme-aware track and value.
  *
+ * Docs: docs/pages/components/progress.md
+ *
  * Consumes the shared --intent/--primary for the value bar and --bar-height
  * for thickness. Indeterminate state animates a shimmer using --duration-shimmer.
  *

package/src/css/components/rating.css

@@ -1,6 +1,8 @@
 /*
  * Rating — integer star rating drawn on native radio inputs.
  *
+ * Docs: docs/pages/components/rating.md
+ *
  * The checked radio remains the functional baseline. :has() progressively
  * fills preceding stars without reversing DOM or keyboard order. Forced
  * colors restores the platform radio presentation.

package/src/css/components/scrollspy.css

@@ -2,6 +2,8 @@
  * Scrollspy — behavior hook for navigation that marks the active section
  * while the page scrolls.
  *
+ * Docs: docs/pages/enhancements/scrollspy.md
+ *
  * Does not add visual styles by itself. scrollspy.js watches
  * <nav class="scrollspy">
  * containing <a href="#section"> links and toggles aria-current="location" on

package/src/css/components/skeleton.css

@@ -1,6 +1,8 @@
 /*
  * Skeleton placeholders for loading states.
  *
+ * Docs: docs/pages/components/skeleton.md
+ *
  * Shows approximate loading structure without implying real content hierarchy.
  * Geometry, animation, and color stay theme-aware.
  *

package/src/css/components/spinner.css

@@ -1,6 +1,8 @@
 /*
  * Spinner — compact loading feedback.
  *
+ * Docs: docs/pages/components/spinner.md
+ *
  * Uses currentColor so it adapts to buttons, alerts, badges, and text. The
  * [aria-busy] overlay composition lives in components/busy.css.
  *

package/src/css/components/status-bar.css

@@ -1,6 +1,8 @@
 /*
  * Status bar — singleton floating status area.
  *
+ * Docs: docs/pages/enhancements/status-bar.md
+ *
  * One element in the HTML, empty by default. .is-open is the visual state, set
  * by status.js like any other surface: it lands after the message is written
  * and lifts before the bar is cleared, so the bar leaves in the exact state it

package/src/css/components/steps.css

@@ -1,6 +1,8 @@
 /*
  * Steps — semantic ordered-list progression for a multi-step process.
  *
+ * Docs: docs/pages/components/steps.md
+ *
  * One primitive, two explicit compositions. Both classes are required:
  *
  *   <ol class="steps steps-horizontal">  horizontal, 2 to 5 stages

package/src/css/components/tab.css

@@ -1,6 +1,8 @@
 /*
  * Tabs — in-place panel switcher with real tab semantics.
  *
+ * Docs: docs/pages/enhancements/tabs.md
+ *
  * JavaScript owns roving tabindex, aria-selected, panel visibility,
  * and arrow-key navigation. CSS owns the tab strip appearance and
  * active indicator.

package/src/css/components/table.css

@@ -1,6 +1,8 @@
 /*
  * Table — structured tabular data.
  *
+ * Docs: docs/pages/components/table.md
+ *
  * .table-wrap provides the scroll container and outer chrome; .table owns row
  * and cell rules. Tokens are sourced from the shared scale.
  *

package/src/css/components/tooltip.css

@@ -1,6 +1,8 @@
 /*
  * Tooltip — supplemental label overlaid near a trigger.
  *
+ * Docs: docs/pages/enhancements/tooltip.md
+ *
  * Position, placement, and arrow position are managed by JavaScript via left,
  * top, data-placement, and --arrow-x. The runtime also owns `position`: it
  * writes `absolute` for a tip whose trigger scrolls with the page, so the

package/src/css/core/base.css

@@ -7,12 +7,14 @@
  * Public hooks:
  * --link
  * --hr-space
+ * --font-width / --font-width-dense (see variants.css for the dense application)
  */
 
 body {
   background: var(--surface);
   color: var(--text);
   font-family: var(--font-sans);
+  font-stretch: var(--font-width);
   line-height: var(--line-height);
 }
 

package/src/css/core/print.css

@@ -1,5 +1,8 @@
 @media print {
   :root,
+  /* The doubled attribute intentionally outranks single-attribute preset
+     islands (data-theme="dark", paired themes) loaded after the core. */
+  [data-theme][data-theme],
   body {
     /* Save some ink in dark mode */
     color-scheme: light;

package/src/css/core/tokens.css

@@ -19,6 +19,8 @@
   /* Typography */
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --font-width: 100%;
+  --font-width-dense: 95%;
   --line-height: 1.5;
   --line-height-tight: 1.25;
   --line-height-relaxed: 1.75;

package/src/css/core/variants.css

@@ -16,9 +16,16 @@
  *   components/alert.css   — .alert default soft behind explicit --ui-*
  *
  * .compact/.spacious set inherited density tokens: spacing rhythm and geometry
- * only. Density never changes typography or icon size. Controls consume
- * --control-size; non-control components may consume --density-* when the
- * context should affect their local rhythm.
+ * only, plus a slight typographic width bonus. Density never changes font size
+ * or icon size. Controls consume --control-size; non-control components may
+ * consume --density-* when the context should affect their local rhythm.
+ * .compact applies --font-width-dense through font-stretch (a variable wdth
+ * axis when available, otherwise normal width-face matching); layout must
+ * never depend on the narrowing being available. .spacious restores
+ * --font-width, so a spacious island inside a compact context returns to the
+ * normal width exactly as it restores its own gap, spacing, and control size.
+ * Themes whose typeface has no useful width axis opt out with
+ * --font-width-dense: 100%.
  *
  * .sm/.lg are local size roles, not shared measurements. Shared control
  * participants below map both typography and geometry; components with
@@ -83,18 +90,20 @@
   --gap: var(--space-20);
   --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
+  font-stretch: var(--font-width-dense);
 }
 
 .spacious {
   --gap: var(--space-50);
   --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
+  font-stretch: var(--font-width);
 }
 
 /* Shared control scale. Wrappers are listed when their descendants form one
-   component (field, input-icon, join, pagination, tabs, flyout). A local size
-   declaration beats inherited density because it is declared on the sized
-   component itself. */
+   component (field, choice-card, floating-field, input-icon, join, pagination,
+   tabs, flyout). A local size declaration beats inherited density because it
+   is declared on the sized component itself. */
 :where(
   .btn,
   .input,
@@ -104,7 +113,9 @@
   .file,
   .field,
   .choice,
+  .choice-card,
   .input-icon,
+  .floating-field,
   .otp,
   .join,
   .pagination,
@@ -126,7 +137,9 @@
   .file,
   .field,
   .choice,
+  .choice-card,
   .input-icon,
+  .floating-field,
   .otp,
   .join,
   .pagination,

package/src/css/effects/aura.css

@@ -1,6 +1,8 @@
 /*
  * Decorative intent-colored frame for one direct child.
  *
+ * Docs: docs/pages/components/aura.md
+ *
  * The effect is built from three layers with distinct roles: a frame carrying
  * a short accent of light, a small halo that belongs to the frame and keeps
  * that light attached to the edge, and a wide static halo that belongs to the

package/src/css/forms/choice-card.css

@@ -1,6 +1,8 @@
 /*
  * Choice cards — card-style radio and checkbox labels.
  *
+ * Docs: docs/pages/forms/choice-cards.md
+ *
  * Each .choice-card is a <label> wrapping a native radio or checkbox. When
  * :has() is supported the input is visually hidden and the card mirrors its
  * state: checked border and tint, checkmark badge (round for radio, rounded
@@ -37,6 +39,8 @@
   border-radius: var(--choice-card-radius);
   background: var(--choice-card-bg);
   color: var(--text);
+  /* Consumed so .sm/.lg reach the card; the badge's em sizing follows. */
+  font-size: var(--control-font-size);
   cursor: pointer;
   transition:
     border-color var(--duration),

package/src/css/forms/control.css

@@ -1,6 +1,8 @@
 /*
  * Text controls — input, textarea, select.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Neutral geometry and interaction states shared across all text-like
  * controls. select shares this base recipe; its chevron/appearance layer
  * lives in select.css. checkbox, radio, range, switch, and file have their

package/src/css/forms/floating-field.css

@@ -2,6 +2,8 @@
  * Floating labels — optional composition over the text controls
  * (.input, .textarea, .select) and .field-label.
  *
+ * Docs: docs/pages/forms/floating-field.md
+ *
  * The cell owns a control plus its label; the label overlays the control and
  * floats to the top when the control is focused or non-empty. Help and error
  * messages stay in the surrounding .field, not inside the cell, so the
@@ -43,7 +45,9 @@
 
 .floating-field > .field-label {
   position: absolute;
-  inset-inline-start: calc(var(--space-30) + var(--border-width));
+  /* Same start edge as the control's text: --control-pad-x owns that shared
+     geometry, so .sm/.lg keep label and value aligned. */
+  inset-inline-start: calc(var(--control-pad-x) + var(--border-width));
   color: var(--text-muted);
   font-size: var(--control-font-size);
   font-weight: var(--font-weight-normal);

package/src/css/forms/form-actions.css

@@ -1,6 +1,8 @@
 /*
  * Form actions — bottom form bar with sticky variant.
  *
+ * Docs: docs/pages/forms/form-actions.md
+ *
  * A flex cluster of buttons/actions that closes a form. The sticky variant
  * docks to the viewport bottom with a translucent blur where supported; at
  * rest it stays visually neutral so it does not double as a separator.

package/src/css/forms/form.css

@@ -1,6 +1,8 @@
 /*
  * Form layout and supporting text.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Individual controls keep their own files; .choice label layout lives in
  * choice.css; .form-actions lives in form-actions.css.
  *
@@ -16,6 +18,12 @@
  */
 .field {
   display: grid;
+
+  /* why: a field stretched by a taller row sibling — the classic case is a
+     neighbour revealing its .field-error — would otherwise hand the extra
+     block size to its auto rows and inflate the control. Rows keep their
+     natural height; the slack stays at the end. */
+  align-content: start;
   gap: var(--space-10);
   color: var(--text);
   font-size: var(--control-font-size);

package/src/css/forms/input-icon.css

@@ -1,6 +1,8 @@
 /*
  * Input Icon — decorative icon inside a relative wrapper, leading or trailing.
  *
+ * Docs: docs/pages/patterns/icon-input.md
+ *
  * Icon-library agnostic: detects position by DOM order. First child that is
  * not .input = leading icon; icon after .input = trailing. The icon follows
  * local typography; density contexts shrink the control geometry around it

package/src/css/forms/native.css

@@ -3,6 +3,8 @@
  * custom styling, so the framework stays out of the way and just keeps them
  * readable and theme-aware.
  *
+ * Docs: docs/pages/forms/controls.md
+ *
  * Range has its own custom-styled file (range.css) so the focus ring can
  * target the thumb pseudo-element rather than the rectangular CSS box.
  */

package/src/css/forms/otp.css

@@ -1,6 +1,8 @@
 /*
  * One-time code input with visual cells and one native input.
  *
+ * Docs: docs/pages/forms/otp.md
+ *
  * Add one direct span per accepted character. The cells determine the
  * component width; the overlaid input remains the only interactive control.
  *
@@ -129,4 +131,12 @@
   .needs-validation.was-validated .otp > input:invalid ~ span {
     --otp-cell-border: Mark;
   }
+
+  /* biome-ignore lint/style/noDescendingSpecificity: the :user-invalid route
+     mirrors the non-forced-colors block above and must come last — the three
+     invalid markers write the same value, so source order is inert. An engine
+     without the pseudo drops this rule alone. */
+  .needs-validation .otp > input:user-invalid ~ span {
+    --otp-cell-border: Mark;
+  }
 }

package/src/css/forms/range.css

@@ -2,6 +2,8 @@
  * Range slider — custom-styled so the focus ring always targets the
  * user-manipulated surface (the thumb) rather than the CSS box.
  *
+ * Docs: docs/pages/forms/range.md
+ *
  * appearance: none gives us full control over track and thumb; without it,
  * pseudo-element rules for ::-webkit-slider-thumb and ::-moz-range-thumb
  * are not reliably applied across browsers.

package/src/css/forms/select.css

@@ -2,6 +2,8 @@
  * Select — chevron and appearance layer on top of the shared text-control
  * recipe.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Base geometry and interaction states come from control.css (select shares
  * the --control-* tokens). This file only removes the native arrow and draws
  * the CSS chevron, so the picker (appearance: base-select) enhancement in

package/src/css/forms/switch.css

@@ -1,6 +1,8 @@
 /*
  * Switch controls for checkbox inputs with switch semantics.
  *
+ * Docs: docs/pages/forms/switch.md
+ *
  * The switch remains an input control, not a decorative toggle. Checked, hover,
  * focus-visible, and disabled states stay clear.
  *