actual-css 0.4.0 → 0.4.2

package/docs/pages/patterns/structured-lists.md

@@ -1,47 +1,45 @@
 # Structured Lists
 
-Use native lists plus layout primitives for rich content rows. Reset list chrome only when markers are not part of the content.
+Choose list markup from the content semantics, then add only the layout or
+component contract the collection needs.
 
-```html demo
-<figure class="stack">
-  <figcaption><strong>Most played songs this week</strong></figcaption>
+| Need | Use |
+| --- | --- |
+| Bullets or order carry meaning | Native `<ul>` or `<ol>` |
+| One leading element and one flexible content region | [`.media`](../layout/media.md) |
+| Repeated application rows with leading, content, and trailing regions | [`.list`](../components/list.md) |
+| A list of navigation links | [`.nav-list`](./navigation-list.md) |
+| A richer collection with its own item structure | Native list plus layout primitives and components |
 
-  <ul class="list-reset stack gap-none">
-    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
-      <div class="avatar">
-        <img src="https://i.pravatar.cc/48?img=5" alt="Dio Lupa" />
-      </div>
-      <div class="cluster">
-        <div class="stack grow" style="--gap: var(--space-10)">
-          <strong>Dio Lupa</strong>
-          <span class="muted">Remaining Reason</span>
-        </div>
-        <span class="muted">3:45</span>
-        <button class="btn ghost" type="button" aria-label="Play">
-          <i class="ti ti-player-play" aria-hidden="true"></i>
-        </button>
-      </div>
-    </li>
+`.media` and `.list` are not interchangeable. `.media` is geometry for one
+two-part composition and requires exactly two direct children. `.list` owns the
+repeated-row treatment: three regions, row padding, minimum touch height,
+dividers, navigable-row hover, and supporting text.
 
-    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
-      <div class="avatar">
-        <img src="https://i.pravatar.cc/48?img=10" alt="Astral Planes" />
-      </div>
-      <div class="cluster">
-        <div class="stack grow" style="--gap: var(--space-10)">
-          <strong>Astral Planes</strong>
-          <span class="muted">Neon Drift</span>
-        </div>
-        <span class="muted">4:12</span>
-        <button class="btn ghost" type="button" aria-label="Play">
-          <i class="ti ti-player-play" aria-hidden="true"></i>
-        </button>
-      </div>
-    </li>
-  </ul>
-</figure>
-```
+Keep native markers when they communicate sequence, rank, or grouping. Remove
+them with `.list-reset` only when they are not part of the content. A reset
+changes list chrome; it does not create a row component.
 
-Use `.actions` for action controls and `.nav-list` for navigation links. For structured content items, compose `.list-reset`, `.stack`, `.cluster`, `.media`, and components directly.
+For a collection whose items are complete compositions rather than application
+rows, keep the native list and compose each item independently:
 
-`.media` is a two-slot object: it lays out exactly two children — the leading element and one content column. Trailing metadata and actions belong inside the content column (nest a `.cluster` and put `.grow` on the flexible part), never as extra row children: additional children silently wrap onto a second grid row.
+```html demo
+<ul class="list-reset grid" style="--grid-min: 16rem">
+  <li>
+    <article class="card stack">
+      <span class="badge">Guide</span>
+      <h2>Choose a layout</h2>
+      <p>Match intrinsic behavior to the structure of the content.</p>
+      <a href="#layout-guide">Read the guide</a>
+    </article>
+  </li>
+  <li>
+    <article class="card stack">
+      <span class="badge">Reference</span>
+      <h2>Compose spacing</h2>
+      <p>Use shared rhythm without coupling content to a component.</p>
+      <a href="#spacing-reference">View the reference</a>
+    </article>
+  </li>
+</ul>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.4.0",
@@ -115,6 +115,7 @@
     "build:docs": "bun run build:themes && bun scripts/build-docs.js",
     "watch:docs": "bun run build:themes && bun scripts/build-docs.js --watch",
     "check:docs": "bun scripts/check-docs.js",
+    "check:doc-classes": "bun scripts/check-doc-classes.js",
     "check:compat": "bun scripts/check-compat.js",
     "check:css-api": "bun scripts/check-css-api.js",
     "check:color-space": "bun scripts/check-color-space.js",
@@ -135,7 +136,7 @@
     "check:sync": "bun scripts/check-sync.js",
     "test": "bun test",
     "test:changed": "bun test --changed=master",
-    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run build:docs && bun run check:docs && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:size",
+    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:size",
     "prepublishOnly": "bun run build:all"
   },
   "devDependencies": {

package/scripts/reserved-classes.json

@@ -10,6 +10,9 @@
   "align-self-center",
   "align-self-end",
   "align-self-start",
+  "app-layout",
+  "app-main",
+  "app-nav",
   "app-shell",
   "aura",
   "aura-glow",
@@ -26,6 +29,7 @@
   "border-context",
   "border-inline-end",
   "border-inline-start",
+  "bottom",
   "breadcrumb",
   "btn",
   "callout",
@@ -71,6 +75,7 @@
   "column-start-8",
   "column-start-9",
   "compact",
+  "complete",
   "container-query",
   "cursor-pointer",
   "danger",
@@ -124,6 +129,8 @@
   "had-scrollbar",
   "has-modal-open",
   "icon-only",
+  "indicator",
+  "indicator-item",
   "inline-size-full",
   "input",
   "input-icon",
@@ -146,6 +153,12 @@
   "link",
   "link-muted",
   "link-plain",
+  "list",
+  "list-item",
+  "list-item-content",
+  "list-item-text",
+  "list-item-title",
+  "list-item-trailing",
   "list-reset",
   "margin-block-end-auto",
   "margin-block-start-auto",
@@ -204,7 +217,9 @@
   "radius-sm-context",
   "raised",
   "range",
+  "rating",
   "required-mark",
+  "reverse",
   "row-gap-context",
   "scroll-snap",
   "scroll-target",
@@ -224,7 +239,9 @@
   "sr-only",
   "stable-gutter",
   "stack",
+  "start",
   "status-bar",
+  "steps",
   "sticky",
   "stretch",
   "subtle",

package/src/css/components/actions.css

@@ -11,6 +11,7 @@
   --gap: var(--space-20);
 
   display: flex;
+  flex-direction: row;
   flex-wrap: wrap;
   align-items: center;
   gap: var(--gap);

package/src/css/components/app-nav.css

@@ -0,0 +1,76 @@
+/*
+ * Primary application navigation. The component owns the navigation surface
+ * and item states; app-layout owns whether that surface is a bottom bar or
+ * labelled side navigation.
+ *
+ * Public hooks:
+ * --app-nav-size
+ * --app-nav-gap
+ */
+:where(.app-nav) {
+  --ui-bg: initial;
+  --ui-fg: initial;
+  --ui-border: initial;
+}
+
+.app-nav {
+  --app-nav-size: 4rem;
+  --app-nav-gap: var(--space-10);
+
+  position: sticky;
+  inset-block-end: 0;
+  z-index: var(--z-sticky);
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: minmax(0, 1fr);
+  gap: var(--app-nav-gap);
+  min-block-size: calc(var(--app-nav-size) + env(safe-area-inset-bottom));
+  padding-block: var(--space-10) max(var(--space-10), env(safe-area-inset-bottom));
+  padding-inline: var(--space-10);
+  border-block-start: var(--border-width) solid var(--ui-border, var(--border));
+  background: var(--ui-bg, var(--surface));
+  color: var(--ui-fg, var(--text-muted));
+}
+
+.app-nav > a {
+  display: grid;
+  grid-template-rows: auto auto;
+  place-content: center;
+  justify-items: center;
+  gap: var(--space-10);
+  min-inline-size: 0;
+  min-block-size: var(--control-size-lg);
+  padding-inline: var(--space-10);
+  border-radius: var(--radius);
+  color: inherit;
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--line-height-tight);
+  text-align: center;
+  text-decoration: none;
+  overflow-wrap: anywhere;
+}
+
+.app-nav > a > :where(svg, img, [aria-hidden="true"]) {
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  font-size: 1.5rem;
+  line-height: 1;
+}
+
+.app-nav > a:hover {
+  background: var(--surface-subtle);
+  color: var(--text);
+}
+
+.app-nav > a:where([aria-current]:not([aria-current="false"])) {
+  background: var(--state-selected);
+  color: var(--state-selected-fg);
+  font-weight: var(--font-weight-bold);
+}
+
+@media print {
+  .app-nav {
+    display: none;
+  }
+}

package/src/css/components/avatar.css

@@ -69,6 +69,9 @@
   }
 }
 
+/* The initials element (a span or an accessible <abbr title="…">) fills the box.
+   text-decoration: none neutralizes the UA dotted underline on <abbr title="…">
+   inside the circular avatar. */
 .avatar > :first-child:not(:where(img, picture, .badge)) {
   display: inline-grid;
   place-items: center;
@@ -76,6 +79,7 @@
   block-size: 100%;
   overflow: hidden;
   border-radius: inherit;
+  text-decoration: none;
 }
 
 .avatar > img,

package/src/css/components/badge.css

@@ -180,21 +180,9 @@ a.badge[aria-disabled="true"] {
     background: ButtonText;
   }
 
-  :where(a.badge, button.badge):hover:not(:where(:disabled, [aria-disabled="true"])) {
-    outline: var(--border-width) solid ButtonText;
-    outline-offset: 2px;
-  }
-
-  .badge > button:not(:disabled):hover {
-    outline: var(--border-width) solid currentColor;
-    outline-offset: 1px;
-  }
-
-  button.badge:disabled,
   .badge[aria-disabled="true"] {
-    border-color: GrayText;
-    background: Canvas;
     color: GrayText;
+    border-color: GrayText;
   }
 }
 @media print {

package/src/css/components/breadcrumb.css

@@ -6,6 +6,7 @@
  */
 .breadcrumb {
   display: flex;
+  flex-direction: row;
   flex-wrap: wrap;
   align-items: center;
   gap: var(--space-10);

package/src/css/components/button.css

@@ -92,7 +92,8 @@
 
 .btn.icon-only {
   inline-size: var(--btn-min-size);
-  padding-inline: 0;
+  block-size: var(--btn-min-size);
+  padding: 0;
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
@@ -164,14 +165,15 @@
   --ui-fg: var(--intent, currentColor);
   --ui-border: transparent;
   --btn-radius: var(--radius-sm);
-  --btn-border-block-end-color: transparent;
-  --btn-border-block-end-width: var(--border-width);
 
   min-block-size: auto;
   padding-inline: 0;
   inline-size: fit-content;
   max-inline-size: 100%;
-  border-color: transparent;
+  /* No border at all: a link reads through its underline, and the inherited
+     .btn border made transparent would turn into a visible box in forced
+     colors. :focus-visible keeps its own outline. */
+  border: 0;
   text-decoration: underline;
   text-underline-offset: 0.18em;
 }
@@ -232,44 +234,12 @@ a.btn[aria-disabled="true"] {
 }
 
 @media (forced-colors: active) {
-  .btn {
-    border-color: ButtonText;
-    background: ButtonFace;
-    color: ButtonText;
-    box-shadow: none;
-  }
-
-  .btn.link {
-    border-color: transparent;
-    background: Canvas;
-    color: LinkText;
-  }
-
-  .btn:is([aria-pressed="true"], [aria-current="page"]):not(.link) {
-    border-color: Highlight;
-    background: Highlight;
-    color: HighlightText;
-    forced-color-adjust: none;
-  }
-
-  .btn:is([aria-pressed="true"], [aria-current="page"]):not(.link):focus-visible {
-    outline: var(--focus-outline);
-    box-shadow: none;
-  }
-
-  .btn:hover:not(:where(:disabled, [aria-disabled="true"], .link)) {
-    outline: var(--border-width) solid ButtonText;
-    outline-offset: 2px;
-  }
-
-  .btn:disabled,
   a.btn[aria-disabled="true"] {
-    border-color: GrayText;
-    background: Canvas;
     color: GrayText;
-    forced-color-adjust: auto;
+    border-color: GrayText;
   }
 }
+
 @media print {
   :is(button, input[type="button"], input[type="submit"], input[type="reset"]).btn {
     display: none !important;

package/src/css/components/card.css

@@ -4,11 +4,14 @@
  * Surface, border, radius, padding, density, and elevation stay local here.
  * Direct header/footer children are structural slots; a direct footer is
  * anchored to the card's bottom edge when extra block space is available (so
- * price/action rows align across equal-height cards in a grid). Page layout
- * remains the job of markup and layout primitives outside the card.
+ * price/action rows align across equal-height cards in a grid). A bare card
+ * owns its direct-child rhythm; a layout primitive on the same element takes
+ * over that layout. Page layout remains the job of markup and layout
+ * primitives outside the card.
  *
  * Public hooks:
  * --card-pad
+ * --card-gap
  * --card-radius
  * --card-max-inline-size
  *
@@ -32,6 +35,7 @@
 
 .card {
   --card-pad: var(--space-40);
+  --card-gap: var(--space-30);
   --card-radius: var(--radius-lg);
   --card-max-inline-size: none;
   --card-bg: var(--ui-bg, var(--surface-raised));
@@ -58,10 +62,14 @@
 :where(.card) {
   display: flex;
   flex-direction: column;
+  gap: var(--card-gap);
 }
 
-.card > * {
+/* Native block margins would add to flex gap because flex-item margins never
+   collapse. Zero specificity keeps intentional child utilities available. */
+:where(.card) > * {
   min-inline-size: 0;
+  margin-block: 0;
 }
 
 .card > :where(header, footer) {
@@ -88,14 +96,6 @@
   margin-block-start: auto;
 }
 
-.card > :first-child {
-  margin-block-start: 0;
-}
-
-.card > :last-child {
-  margin-block-end: 0;
-}
-
 .card.raised {
   box-shadow: var(--shadow);
 }

package/src/css/components/chat.css

@@ -97,9 +97,3 @@
     column-gap: 0;
   }
 }
-
-@media (forced-colors: active) {
-  .chat-bubble {
-    border-color: CanvasText;
-  }
-}

package/src/css/components/drawer.css

@@ -138,12 +138,6 @@ dialog.drawer nav {
   }
 }
 
-@media (forced-colors: active) {
-  dialog.drawer::backdrop {
-    background: Canvas;
-  }
-}
-
 @media (prefers-reduced-motion: no-preference) {
   dialog.drawer.is-static {
     animation: actual-dialog-static var(--duration-slow) var(--ease);

package/src/css/components/fab.css

@@ -68,6 +68,7 @@
   max-inline-size: 16rem;
   padding: var(--space-10) var(--space-20);
   border-radius: var(--radius);
+  border: var(--border-width) solid transparent;
   background: var(--surface);
   color: var(--text);
   box-shadow: var(--shadow);
@@ -90,13 +91,6 @@
   transform: rotate(45deg);
 }
 
-@media (forced-colors: active) {
-  .fab-label {
-    border: var(--border-width) solid CanvasText;
-    box-shadow: none;
-  }
-}
-
 @media print {
   .fab {
     display: none;

package/src/css/components/index.css

@@ -27,11 +27,15 @@
 
 /* Display */
 @import "./avatar.css";
+@import "./indicator.css";
 @import "./key.css";
 @import "./chat.css";
 @import "./fab.css";
+@import "./rating.css";
+@import "./steps.css";
 
 /* Navigation */
+@import "./app-nav.css";
 @import "./navbar.css";
 @import "./breadcrumb.css";
 @import "./pagination.css";
@@ -39,6 +43,7 @@
 @import "./scrollspy.css";
 
 /* Data */
+@import "./list.css";
 @import "./table.css";
 @import "./meter.css";
 

package/src/css/components/indicator.css

@@ -0,0 +1,47 @@
+/*
+ * Indicator — generic corner positioning for overlaid component content.
+ *
+ * The container only establishes the containing block. The item owns no
+ * paint, size, or ring so badges and other components keep their own visual
+ * contract.
+ *
+ * Internal:
+ * --indicator-translate-x
+ * --indicator-translate-y
+ */
+.indicator {
+  position: relative;
+}
+
+.indicator-item {
+  --indicator-translate-x: 50%;
+  --indicator-translate-y: -50%;
+
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-end: 0;
+  z-index: 1;
+  transform: translate(var(--indicator-translate-x), var(--indicator-translate-y));
+}
+
+.indicator-item.start {
+  --indicator-translate-x: -50%;
+
+  inset-inline-start: 0;
+  inset-inline-end: auto;
+}
+
+.indicator-item.bottom {
+  --indicator-translate-y: 50%;
+
+  inset-block-start: auto;
+  inset-block-end: 0;
+}
+
+.indicator-item:dir(rtl) {
+  --indicator-translate-x: -50%;
+}
+
+.indicator-item.start:dir(rtl) {
+  --indicator-translate-x: 50%;
+}

package/src/css/components/list.css

@@ -0,0 +1,83 @@
+/*
+ * Application list — repeated rows with optional leading and trailing regions.
+ * Content determines the number of lines; the component only owns the row
+ * geometry, dividers, and supporting-text treatment.
+ *
+ * Public hooks:
+ * --list-item-min-size
+ * --list-item-pad-block
+ * --list-item-pad-inline
+ * --list-item-gap
+ * --list-divider
+ */
+.list {
+  --list-item-min-size: var(--control-size-lg);
+  --list-item-pad-block: var(--space-30);
+  --list-item-pad-inline: 0;
+  --list-item-gap: var(--gap);
+  --list-divider: var(--border-width) solid var(--border);
+
+  display: grid;
+  gap: 0;
+  margin: 0;
+  padding: 0;
+  border-block-start: var(--list-divider);
+  list-style: none;
+}
+
+.list > li {
+  margin: 0;
+}
+
+.list > :where(.list-item),
+.list > li > .list-item {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: var(--list-item-gap);
+  min-block-size: var(--list-item-min-size);
+  padding-block: var(--list-item-pad-block);
+  padding-inline: var(--list-item-pad-inline);
+}
+
+.list > .list-item + .list-item,
+.list > li + li {
+  border-block-start: var(--list-divider);
+}
+
+a.list-item {
+  color: inherit;
+  text-decoration: none;
+}
+
+a.list-item:hover {
+  background: var(--surface-subtle);
+}
+
+.list-item-content {
+  min-inline-size: 0;
+}
+
+.list-item-title,
+.list-item-text {
+  display: block;
+  margin: 0;
+}
+
+.list-item-text {
+  color: var(--text-muted);
+  font-size: var(--font-size-sm);
+  overflow-wrap: anywhere;
+}
+
+.list-item-trailing {
+  justify-self: end;
+  min-inline-size: 0;
+}
+
+@media print {
+  .list > :where(.list-item),
+  .list > li > .list-item {
+    break-inside: avoid;
+  }
+}

package/src/css/components/menu.css

@@ -126,10 +126,3 @@
   border: 0;
   border-block-start: var(--border-width) solid var(--border);
 }
-
-@media (forced-colors: active) {
-  .menu-item:focus-visible {
-    outline: var(--border-width) solid ButtonText;
-    outline-offset: -1px;
-  }
-}

package/src/css/components/modal.css

@@ -239,23 +239,6 @@ html.has-modal-open.had-scrollbar {
   }
 }
 
-@media (forced-colors: active) {
-  dialog.modal {
-    border-color: ButtonText;
-    background: Canvas;
-    color: CanvasText;
-    box-shadow: none;
-  }
-
-  dialog.modal::backdrop {
-    background: Canvas;
-  }
-
-  .dialog-icon {
-    border: var(--border-width) solid CanvasText;
-  }
-}
-
 /* Close controls. A close button is an action attached to a surface, so it
    never participates in the content flow. The modal and the drawer share the
    same simple placement — absolute at the panel's top inline-end, inside the