actual-css 0.2.0 → 0.3.0

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

@@ -1,36 +1,54 @@
 /*
- * Input Icon — leading decorative icon inside a relative wrapper.
+ * Input Icon — decorative icon inside a relative wrapper, leading or trailing.
  *
- * Icon-library agnostic: selects the wrapper's first child rather than a
- * specific tag, so it works with an <i> webfont icon, an inline <svg>, or a
- * <span>. Sizes with --variant-icon-size (variants.css) so .sm/.lg pick up
- * the same icon scale used elsewhere (alert.css); the input's start padding
- * grows to match so text never runs under the icon.
+ * Icon-library agnostic: detects position by DOM order. First child that is
+ * not .input = leading icon; icon after .input = trailing. The icon keeps a
+ * fixed size; density contexts shrink the control geometry around it, not
+ * the pictogram.
+ *
+ * Public hooks:
+ * --input-icon-size
  */
 .input-icon {
-  --input-icon-size: var(--variant-icon-size, 1.25rem);
+  --input-icon-size: 1.25rem;
 
   display: block;
   position: relative;
 }
 
-.input-icon > :first-child {
+/* Icon — shared by leading and trailing */
+.input-icon > :where(:not(.input)) {
   position: absolute;
   inset-block-start: 50%;
-  inset-inline-start: var(--space-3);
   transform: translateY(-50%);
   font-size: var(--input-icon-size);
   color: var(--text-muted);
   pointer-events: none;
 }
 
+/* Leading: icon is the first child */
+.input-icon > :first-child:where(:not(.input)) {
+  inset-inline-start: var(--space-30);
+}
+
+/* Trailing: input is the first child, icon follows */
+.input-icon > .input:first-child ~ :where(:not(.input)) {
+  inset-inline-end: var(--space-30);
+}
+
 /* font-size only sizes text-metric icons (webfont <i>, <span>). An inline
    <svg> with just a viewBox ignores it, so give it explicit dimensions. */
-.input-icon > svg:first-child {
+.input-icon > svg:where(:not(.input)) {
   inline-size: var(--input-icon-size);
   block-size: var(--input-icon-size);
 }
 
-.input-icon > .input {
-  padding-inline-start: calc(var(--space-3) * 2 + var(--input-icon-size));
+/* Leading: input gets start padding to clear the icon */
+.input-icon > :first-child:where(:not(.input)) ~ .input {
+  padding-inline-start: calc(var(--space-30) * 2 + var(--input-icon-size));
+}
+
+/* Trailing: input is first child and has a sibling → end padding */
+.input-icon > .input:first-child:where(:not(:last-child)) {
+  padding-inline-end: calc(var(--space-30) * 2 + var(--input-icon-size));
 }

package/src/css/forms/native.css

@@ -1,7 +1,7 @@
 /*
- * Native-only control polish: file input that mostly defeats custom styling,
- * so the framework stays out of the way and just keeps it readable and
- * theme-aware.
+ * Native-only control polish: the file input and color picker mostly defeat
+ * custom styling, so the framework stays out of the way and just keeps them
+ * readable and theme-aware.
  *
  * 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.
@@ -11,9 +11,9 @@
 }
 
 .file::file-selector-button {
-  margin-inline-end: var(--space-3);
-  padding-block: var(--space-1);
-  padding-inline: var(--space-2);
+  margin-inline-end: var(--space-30);
+  padding-block: var(--space-10);
+  padding-inline: var(--space-20);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius-sm);
   background: var(--surface-subtle);
@@ -32,13 +32,52 @@
   cursor: not-allowed;
 }
 
-@media (hover: hover) {
-  .file:not(:disabled)::file-selector-button:hover {
-    background: var(--border);
-  }
+.file:not(:disabled)::file-selector-button:hover {
+  background: var(--border);
 }
 
 .file:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
+  box-shadow: var(--focus-ring-shadow);
+}
+
+/* Native color picker — keep the browser's dialog and selected-color UI. */
+.color {
+  inline-size: var(--control-size);
+  block-size: var(--control-size);
+  padding: var(--space-10);
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+  cursor: pointer;
+}
+
+.color::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+.color::-webkit-color-swatch {
+  border: 0;
+}
+
+.color::-moz-color-swatch {
+  border: 0;
+}
+
+.color:disabled {
+  cursor: not-allowed;
+  opacity: var(--disabled-opacity);
+}
+
+.color:focus-visible {
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
+
+@media (forced-colors: active) {
+  .color {
+    border-color: ButtonText;
+    background: ButtonFace;
+    forced-color-adjust: none;
+  }
+}

package/src/css/forms/range.css

@@ -5,19 +5,18 @@
  * 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.
+ *
+ * Public hooks:
+ * --range-thumb-size
+ * --range-track-height
+ * --range-thumb-bg
+ * --range-track-bg
  */
 
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.range) {
-  /* @sync intent-boundary */
   --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .range {
@@ -68,7 +67,7 @@
 }
 
 .range:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
 }
 
 /*
@@ -89,7 +88,16 @@
 }
 
 .range:disabled {
-  --range-thumb-bg: var(--text-subtle);
+  --range-thumb-bg: var(--state-disabled);
   cursor: not-allowed;
   opacity: var(--disabled-opacity);
 }
+
+/* Forced colors: map the custom thumb/track to system colors. The focus
+   indicator stays visible through the transparent outline on :focus-visible. */
+@media (forced-colors: active) {
+  .range {
+    --range-thumb-bg: ButtonText;
+    --range-track-bg: Canvas;
+  }
+}

package/src/css/forms/select.css

@@ -8,19 +8,19 @@
  * custom-select.css can be opted out independently. Add .native to a specific
  * select to opt out of the enhancement.
  */
-.select:is(:not([multiple], [size]), :not([multiple])[size="1"]) {
+.select:not([multiple], [size]:not([size="1"])) {
   appearance: none;
-  padding-inline-end: calc(var(--space-3) + var(--space-6));
-  background-image: var(--icon-chevron-image);
-  background-position: center right var(--space-3);
+  padding-inline-end: calc(var(--space-30) + var(--space-60));
+  background-image: var(--icon-chevron);
+  background-position: center right var(--space-30);
   background-size: 1rem auto;
   background-repeat: no-repeat;
 }
 
 /* The chevron sits on the inline-end side; flip it in RTL so it follows
    the padding-inline-end space reserved for it. */
-.select:is(:not([multiple], [size]), :not([multiple])[size="1"]):dir(rtl) {
-  background-position: center left var(--space-3);
+.select:not([multiple], [size]:not([size="1"])):dir(rtl) {
+  background-position: center left var(--space-30);
 }
 
 /* Both forced-colors and prefers-contrast hand the arrow back to the
@@ -28,9 +28,9 @@
    simpler than maintaining contrast variants, and native rendering already
    matches whatever contrast mode the user picked. */
 @media (forced-colors: active), (prefers-contrast: more) {
-  .select:is(:not([multiple], [size]), :not([multiple])[size="1"]) {
+  .select:not([multiple], [size]:not([size="1"])) {
     appearance: auto;
     background-image: none;
-    padding-inline-end: var(--space-3);
+    padding-inline-end: var(--space-30);
   }
 }

package/src/css/forms/switch.css

@@ -3,18 +3,22 @@
  *
  * The switch remains an input control, not a decorative toggle. Checked, hover,
  * focus-visible, and disabled states stay clear.
+ *
+ * Public hooks:
+ * --switch-bg
+ * --switch-border
+ * --switch-knob
+ * --switch-width
+ * --switch-block-size
+ * --switch-knob-margin
+ * --switch-knob-size
+ * --switch-travel
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.switch) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .switch {
@@ -62,10 +66,8 @@
     box-shadow var(--duration);
 }
 
-@media (hover: hover) {
-  .switch:hover:not(:disabled) {
-    --switch-border: var(--intent, var(--primary));
-  }
+.switch:hover:not(:disabled) {
+  --switch-border: var(--intent, var(--primary));
 }
 
 .switch:checked {
@@ -86,14 +88,14 @@
 
 .switch:focus-visible {
   --switch-border: var(--focus);
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
 .switch:disabled {
   --switch-bg: var(--surface-subtle);
   --switch-border: var(--border);
-  --switch-knob: var(--text-subtle);
+  --switch-knob: var(--state-disabled);
   opacity: 1;
   cursor: not-allowed;
 }

package/src/css/forms/validation.css

@@ -3,6 +3,17 @@
  *
  * Imported by default through forms/index.css. Custom builds may omit this
  * file when an app wants to own validation styling completely.
+ *
+ * State coverage (which states each component ships) is audited in
+ * tests/validation.test.js and summarized in docs/pages/forms/validation.md —
+ * not kept as a source comment that can drift from the implementation.
+ *
+ * Public hooks:
+ * --form-invalid-border
+ *
+ * Internal:
+ * --choice-bg
+ * --switch-bg
  */
 
 .field.danger {
@@ -25,17 +36,33 @@
   --form-invalid-border: var(--danger);
 }
 
-/* Override checked/indeterminate background so both border and fill signal
-   danger instead of showing a red border around a primary-colored control. */
-.check[aria-invalid="true"]:is(:checked, :indeterminate),
-.radio[aria-invalid="true"]:checked {
+/* Override checked/indeterminate fill so both border and fill signal danger
+   instead of a red border around a primary-colored control. All three
+   invalid routes must converge: aria-invalid, was-validated :invalid, and
+   :user-invalid. */
+.check:is(:checked, :indeterminate)[aria-invalid="true"],
+.needs-validation.was-validated .check:is(:checked, :indeterminate):invalid,
+.radio:checked[aria-invalid="true"],
+.needs-validation.was-validated .radio:checked:invalid {
   --choice-bg: var(--danger);
 }
 
-.switch[aria-invalid="true"]:checked {
+.switch:checked[aria-invalid="true"],
+.needs-validation.was-validated .switch:checked:invalid {
   --switch-bg: var(--danger);
 }
 
+@supports selector(:user-invalid) {
+  .needs-validation .check:is(:checked, :indeterminate):user-invalid,
+  .needs-validation .radio:checked:user-invalid {
+    --choice-bg: var(--danger);
+  }
+
+  .needs-validation .switch:checked:user-invalid {
+    --switch-bg: var(--danger);
+  }
+}
+
 /* Choice cards hide their native input, so invalid state must surface on the
    card itself. Sets the same --form-invalid-border hook the card's border
    consumes. */

package/src/css/grid.css

@@ -1,26 +1,24 @@
+/*
+ * Responsive equal-width grids, with fixed-column presets below.
+ *
+ * Public hooks:
+ * --grid-min
+ * --grid-columns
+ */
 .grid {
   display: grid;
   gap: var(--gap);
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr));
+  grid-template-columns: var(
+      --grid-columns,
+      repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr))
+    );
 }
 
-/* Query-container wrapper that opts .grid-2/3/4/6 into responsive
- * collapse. Wrap a .grid-2/3/4/6 inside .container-query to make the
- * column count collapse on narrow wrappers. Without this wrapper,
- * .grid-2/3/4/6 stay at their full column count. */
-/* Fixed-column grids at their full count by default.
- *   .grid-2: 2 cols
- *   .grid-3: 3 cols
- *   .grid-4: 4 cols
- *   .grid-6: 6 cols
- * When placed inside .container-query, the column count collapses
- * on narrow wrappers. The intermediate 2-col step applies to
- * .grid-3/.grid-4; .grid-6 starts at 2 columns because it is meant
- * for compact items that do not need a full single-column stack.
- *   .grid-2: 1 col -> 2 cols
- *   .grid-3: 1 col -> 2 cols -> 3 cols
- *   .grid-4: 1 col -> 2 cols -> 4 cols
- *   .grid-6: 2 cols -> 3 cols -> 6 cols */
+/* Fixed-column grids at their full count by default: .grid-2/3/4/6 stay at
+   2/3/4/6 columns unless wrapped in .container-query, which collapses the
+   column count on narrow wrappers (a 2-col intermediate step for
+   .grid-3/.grid-4; .grid-6 starts at 2 columns because it is meant for
+   compact items that do not need a full single-column stack). */
 .grid-2,
 .grid-3,
 .grid-4,
@@ -42,6 +40,9 @@
   grid-template-columns: repeat(6, minmax(0, 1fr));
 }
 
+/* Container queries are the preferred responsive path; browsers without them
+   ignore these rules and get the equivalent @media rules from the
+   @supports not (container-type) block below — same columns, same breakpoints. */
 @container (width < 28rem) {
   .container-query .grid-2,
   .container-query .grid-3,

package/src/css/intents.css

@@ -2,8 +2,8 @@
  * Intent classes do not style elements directly.
  * They only expose --intent and --intent-fg.
  * Components and variants decide how to consume them. Each component that
- * consumes --intent or --ui-* must open a local intent boundary in a :where()
- * block that resets --intent / --intent-fg / --ui-* to initial. Parent intents
+ * consumes --intent or --ui-* opens a local intent boundary in a :where()
+ * block that resets exactly the tokens it consumes to initial. Parent intents
  * do not leak into nested components. Local intent classes (.primary, .danger,
  * etc.) still apply because they have higher specificity than :where().
  */

package/src/css/layout.css

@@ -1,3 +1,25 @@
+/*
+ * Core layout primitives: stack, cluster, center, frame, app-shell, media,
+ * sidebar-layout. Each primitive owns a single, readable behavior; they are
+ * meant to compose in markup.
+ *
+ * Public hooks:
+ * --cluster-align
+ * --cluster-justify
+ * --cluster-wrap
+ * --center-size
+ * --center-pad
+ * --frame-ratio
+ * --sidebar-layout-size
+ *
+ * Child contracts:
+ * .stack owns vertical rhythm: direct-child margins are reset, spacing comes
+ *   from --gap.
+ * .cluster owns inline rhythm: direct-child margins are reset, spacing comes
+ *   from --gap.
+ * .frame sizes direct media children (img/video/iframe/canvas/svg) to fill the
+ *   frame.
+ */
 .container-query {
   container-type: inline-size;
 }
@@ -14,12 +36,16 @@
 
 .cluster {
   display: flex;
-  flex-wrap: wrap;
+  flex-wrap: var(--cluster-wrap, wrap);
   align-items: var(--cluster-align, center);
   justify-content: var(--cluster-justify, flex-start);
   gap: var(--gap);
 }
 
+.cluster > * {
+  margin: 0;
+}
+
 .center {
   box-sizing: content-box;
   max-inline-size: var(--center-size, 72rem);
@@ -63,6 +89,8 @@
   grid-template-columns: minmax(0, 1fr);
 }
 
+/* Container queries are the preferred path; without them the @supports not
+   block below restores the same columns at the same viewport breakpoint. */
 @container (width >= 64rem) {
   .container-query .sidebar-layout {
     grid-template-columns: minmax(0, 1fr) var(--sidebar-layout-size, 18rem);

package/src/css/optional/aura.css

@@ -0,0 +1,93 @@
+/*
+ * Decorative intent-colored frame for one direct child.
+ *
+ * Public hooks:
+ * --aura-color
+ * --aura-width
+ * --aura-blur
+ * --aura-radius
+ * --aura-duration
+ */
+@property --aura-angle {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+/* Intent boundary — an outer intent does not tint nested aura frames. */
+:where(.aura) {
+  --intent: initial;
+  --intent-fg: initial;
+}
+
+.aura {
+  --aura-color: var(--intent, var(--primary));
+  --aura-width: 2px;
+  --aura-blur: 0.75rem;
+  --aura-radius: var(--radius-lg);
+  --aura-duration: 6s;
+
+  position: relative;
+  isolation: isolate;
+  display: inline-grid;
+  padding: var(--aura-width);
+  border-radius: calc(var(--aura-radius) + var(--aura-width));
+  background: var(--aura-color);
+  background: conic-gradient(from var(--aura-angle), transparent 0 65%, var(--aura-color));
+}
+
+.aura::before {
+  position: absolute;
+  z-index: -1;
+  inset: 0;
+  border-radius: inherit;
+  background: inherit;
+  filter: blur(var(--aura-blur));
+  opacity: 0.45;
+  pointer-events: none;
+  content: "";
+}
+
+.aura > * {
+  position: relative;
+}
+
+.aura-glow {
+  background: var(--aura-color);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .aura:not(.aura-glow) {
+    animation: aura-rotate var(--aura-duration) linear infinite;
+  }
+}
+
+@keyframes aura-rotate {
+  to {
+    --aura-angle: 360deg;
+  }
+}
+
+@supports selector(:has(*)) {
+  .aura:has(> .btn) {
+    --aura-radius: var(--radius);
+  }
+
+  .aura:has(> :is(.card, .alert)) {
+    --aura-radius: var(--radius-lg);
+  }
+
+  .aura:has(> .badge) {
+    --aura-radius: var(--radius-full);
+  }
+}
+
+@media (forced-colors: active) {
+  .aura {
+    background: CanvasText;
+  }
+
+  .aura::before {
+    display: none;
+  }
+}

package/src/css/optional/chat.css

@@ -0,0 +1,105 @@
+/*
+ * Message rows composed from an optional avatar, metadata, and bubble.
+ *
+ * Public hooks:
+ * --chat-gap
+ * --chat-max-size
+ *
+ * Internal:
+ * --chat-bubble-bg
+ * --chat-bubble-fg
+ * --chat-bubble-border
+ */
+.chat {
+  --chat-gap: var(--space-30);
+  --chat-max-size: min(85%, 40rem);
+
+  display: grid;
+  grid-auto-rows: min-content;
+  column-gap: var(--chat-gap);
+}
+
+.chat-start {
+  grid-template-columns: auto minmax(0, 1fr);
+  justify-items: start;
+}
+
+.chat-end {
+  grid-template-columns: minmax(0, 1fr) auto;
+  justify-items: end;
+}
+
+.chat-avatar {
+  grid-row: 1 / span 3;
+  align-self: end;
+}
+
+.chat-start > .chat-avatar {
+  grid-column: 1;
+}
+
+.chat-end > .chat-avatar {
+  grid-column: 2;
+}
+
+.chat-header,
+.chat-footer {
+  display: flex;
+  gap: var(--space-10);
+  color: var(--text-muted);
+  font-size: var(--font-size-xs);
+}
+
+.chat-start > :is(.chat-header, .chat-bubble, .chat-footer) {
+  grid-column: 2;
+}
+
+.chat-end > :is(.chat-header, .chat-bubble, .chat-footer) {
+  grid-column: 1;
+}
+
+/* Intent boundary — an outer intent does not tint nested messages. */
+:where(.chat-bubble) {
+  --intent: initial;
+  --intent-fg: initial;
+  --ui-bg: initial;
+  --ui-fg: initial;
+  --ui-border: initial;
+}
+
+.chat-bubble {
+  --chat-bubble-bg: var(--ui-bg, var(--intent, var(--surface-subtle)));
+  --chat-bubble-fg: var(--ui-fg, var(--intent-fg, var(--text)));
+  --chat-bubble-border: var(--ui-border, transparent);
+
+  inline-size: fit-content;
+  max-inline-size: var(--chat-max-size);
+  padding: var(--space-20) var(--space-30);
+  border: var(--border-width) solid var(--chat-bubble-border);
+  border-radius: var(--radius-lg);
+  background: var(--chat-bubble-bg);
+  color: var(--chat-bubble-fg);
+  overflow-wrap: anywhere;
+}
+
+.chat-start > .chat-bubble {
+  border-end-start-radius: var(--radius-sm);
+}
+
+.chat-end > .chat-bubble {
+  border-end-end-radius: var(--radius-sm);
+}
+
+/* Remove the reserved avatar gutter when a message has no avatar. This is a
+   cosmetic enhancement; the two-column baseline remains fully readable. */
+@supports selector(:has(*)) {
+  .chat:not(:has(> .chat-avatar)) {
+    column-gap: 0;
+  }
+}
+
+@media (forced-colors: active) {
+  .chat-bubble {
+    border-color: CanvasText;
+  }
+}