actual-css 0.6.0 → 0.7.0

package/docs/pages/enhancements/tooltip.md

@@ -17,6 +17,18 @@ with the `hidden` attribute.
 - The arrow inherits the tooltip background — custom gradients carry through automatically.
 - Avoid relying on the native `title` attribute as the primary implementation.
 
+A `.tooltip[popover]` may use a native or third-party-owned popover lifecycle.
+Actual removes the native inset, margin, and overflow that conflict with
+positioning and with the projecting arrow, while leaving bare `[popover]`
+elements untouched. The lifecycle owner must still write the fixed viewport
+coordinates and arrow position; Actual only supplies the presentation.
+
+That reset is gated on `@supports selector(:popover-open)`. Native Popover is
+optional and is not part of Actual's Minimal contract: browsers within the
+Minimal range may not support it, and there the attribute carries no behavior,
+so nothing shows or hides the tip. Use `data-tooltip` and the built-in runtime
+when the lifecycle must work across the full Minimal range.
+
 ```html demo
 <button class="btn ghost"
         type="button"

package/docs/pages/foundations/philosophy.md

@@ -75,6 +75,19 @@ As inherited contexts, one class tightens or loosens the whole subtree:
 </div>
 ```
 
+Application chrome can use the same scope; no separate `.compact` mode is
+needed:
+
+```html demo
+<header class="navbar sm">
+  <a class="navbar-brand" href="/">Workspace</a>
+  <nav class="cluster" aria-label="Workspace actions">
+    <button class="btn ghost">Search</button>
+    <button class="btn primary">Create</button>
+  </nav>
+</header>
+```
+
 The same class on a component is local density, not a second meaning:
 
 ```html demo
@@ -86,7 +99,8 @@ This is not "`.sm` sometimes means density and sometimes size": `.sm` always
 establishes the same density tokens — only the scope changes. The density
 tokens are `--gap`, `--density-space`, `--control-size`, and
 `--density-compact-size`. Components consume the dimensions that make sense
-for them and opt out of the rest.
+for them and opt out of the rest. The absolute `--space-*` scale is not rebound
+by density scopes.
 
 Components with bespoke sizing (`.avatar`, `.spinner`) define local `.sm`/`.lg`
 instead of consuming the shared tokens.

package/docs/pages/foundations/theming.md

@@ -70,6 +70,14 @@ Native controls that no component class restyles — a bare checkbox, radio, ran
 
 → Forms · Overview · Foundations · Tokens (theme contract)
 
+### Store a theme name without applying it
+
+`data-theme` is an active theme boundary on every element that carries it, not
+a generic storage attribute. Use a different name such as `data-theme-value`,
+or a form control's `value`, when the element should only hold a theme name.
+Apply `data-theme` deliberately when that element and its subtree should paint
+with the selected palette — a theme swatch is a useful example.
+
 ### Loading / busy overlay on a container
 
 Use `aria-busy="true"` with a direct last-child `.spinner`; tint the overlay with `--busy-overlay-bg`.

package/docs/pages/guides/progressive-enhancement.md

@@ -124,19 +124,18 @@ The JS is designed to run on its own, without Actual's stylesheet.
 ## The runtime as a primitive kit
 
 For building custom widgets (select, tags, date picker) on Actual's primitives,
-see the widget-primitives design note. Every primitive subpath is published in
-`package.json#exports`:
-
-| Subpath                  | Purpose                                                          |
-| ------------------------ | ---------------------------------------------------------------- |
-| `actual-css/js/enhance`  | DOM lifecycle engine: `enhance()`, `registerEnhancement`, tokens |
-| `actual-css/js/escape`   | Per-document LIFO Escape dismissal stack                         |
-| `actual-css/js/events`   | The `actual:*` event name constants                              |
-| `actual-css/js/floating` | Positioning engine (`reposition`, `repositionAt`, `autoUpdate`)  |
-| `actual-css/js/focus`    | Focusable-item lookup and helpers                                |
-| `actual-css/js/keys`     | Roving-focus item navigation helpers                             |
-| `actual-css/js/menu`     | Menu keyboard/click wiring, item vocabulary                      |
-| `actual-css/js/surface`  | Surface lifecycle (`openSurface`, `closeSurface`, …)             |
+see the widget-primitives design note. Every Actual runtime primitive subpath is
+published in `package.json#exports`:
+
+| Subpath                 | Purpose                                                          |
+| ----------------------- | ---------------------------------------------------------------- |
+| `actual-css/js/enhance` | DOM lifecycle engine: `enhance()`, `registerEnhancement`, tokens |
+| `actual-css/js/escape`  | Per-document LIFO Escape dismissal stack                         |
+| `actual-css/js/events`  | The `actual:*` event name constants                              |
+| `actual-css/js/focus`   | Focusable-item lookup and helpers                                |
+| `actual-css/js/keys`    | Roving-focus item navigation helpers                             |
+| `actual-css/js/menu`    | Menu keyboard/click wiring, item vocabulary                      |
+| `actual-css/js/surface` | Surface lifecycle (`openSurface`, `closeSurface`, …)             |
 
 The exports map is explicit — it *is* the statement of what is public.
 
@@ -149,33 +148,36 @@ computes and writes inline `left`/`top`, `data-placement`,
 caller owns the floating element's presentation entirely.
 
 ```js
-import { autoUpdate, reposition, repositionAt } from "actual-css/js/floating";
+import { autoUpdate, reposition, repositionAt } from "@lekoala/floating";
 
-const stop = autoUpdate(float, () => {
+const stop = autoUpdate(trigger, float, () => {
   reposition(trigger, float, { placement: "bottom-start", distance: 4 });
 });
 ```
 
 Options passed to `reposition()`:
 
-| Option         | Default          | Contract                                    |
-| -------------- | ---------------- | ------------------------------------------- |
-| `placement`    | `"bottom-start"` | Preferred side and alignment                |
-| `distance`     | `0`              | Gap from the reference element              |
-| `flip`         | `true`           | Flip when the preferred side is out of view |
-| `shift`        | `true`           | Shift along the main axis to stay in bounds |
-| `shiftPadding` | `4`              | Minimum space kept from the boundary        |
-| `scope`        | viewport         | Boundary element for overflow decisions     |
+| Option         | Default          | Contract                                     |
+| -------------- | ---------------- | -------------------------------------------- |
+| `placement`    | `"bottom-start"` | Preferred side and alignment                 |
+| `distance`     | `0`              | Gap from the reference element               |
+| `flip`         | `true`           | Flip when the preferred side is out of view  |
+| `shift`        | `true`           | Shift along the cross axis to stay in bounds |
+| `shiftPadding` | `4`              | Minimum space kept from the boundary         |
+| `scope`        | viewport         | Boundary element for overflow decisions      |
 
 `placement` takes a `-start` or `-end` alignment suffix.
 
-`autoUpdate(element, callback)` batches scroll, resize, and element-resize
-callbacks per document and returns a stop handle; it does not keep a closed or
+`@lekoala/floating` is the standalone positioning dependency used by the
+runtime. `autoUpdate(reference, float, callback)` batches scroll, resize, and
+element-resize callbacks per document and returns a stop handle; it observes
+both the reference and floating element while the surface is open. Pass `null`
+as the reference for point-positioned surfaces. It does not keep a closed or
 hidden element positioned. `repositionAt(x, y, float, opts)` positions relative
 to a fixed point — used by context menus.
 
-A third-party widget importing only `floating` with no Actual stylesheet must be
-able to position a listbox under an input — that is the test.
+A third-party widget importing only `@lekoala/floating` with no Actual stylesheet
+must be able to position a listbox under an input — that is the test.
 
 ## Surface contract
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "actual-css",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.1",
   "license": "MIT",
   "author": "Thomas <thomas@lekoala.be>",
   "repository": {
@@ -58,7 +58,6 @@
     "./js/parse-config": "./src/js/parse-config.js",
     "./js/events": "./src/js/events.js",
     "./js/filter": "./src/js/filter.js",
-    "./js/floating": "./src/js/floating.js",
     "./js/flyout": "./src/js/flyout.js",
     "./js/focus": "./src/js/focus.js",
     "./js/focus-group": "./src/js/focus-group.js",
@@ -143,5 +142,8 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5",
     "happy-dom": "^20.11"
+  },
+  "dependencies": {
+    "@lekoala/floating": "^0.1.0"
   }
 }

package/src/css/components/flyout.css

@@ -79,12 +79,50 @@
   transition: opacity var(--duration-fast) ease;
 }
 
-.flyout.is-open:not(.is-sheet) {
+/* Native popovers enter the top layer with UA geometry that conflicts with
+   anchored positioning. The reset is gated on real Popover support because an
+   attribute selector matches whether or not the engine implements Popover:
+   without it the UA neither hides nor promotes the element, so an ungated
+   reset would strand a permanently visible panel at inset: auto. Popover is
+   not part of Actual's Minimal contract — engines inside the Minimal range
+   may lack it — so the gate is about the capability, not the floor. Kept
+   scoped to Actual surfaces so bare [popover] elements retain their platform
+   presentation. */
+@supports selector(:popover-open) {
+  .flyout[popover] {
+    position: fixed;
+    inset: auto;
+    margin: 0;
+  }
+
+  /* A presentation class may own its *visible* display type, but must not
+     override the platform's hidden state. The UA closes a popover with
+     display: none, and an author declaration beats the UA origin whatever the
+     specificity — so .flyout's own display: grid would leave a closed popover
+     painted at its static position. Restoring both properties here also gives
+     the native path the exit target the runtime path already has in
+     .flyout[hidden]: without an opacity to animate, the overlay/display
+     allow-discrete transition below would hold a fully opaque panel in the top
+     layer and then snap it away. */
+  .flyout[popover]:not(:popover-open) {
+    display: none;
+    opacity: 0;
+  }
+}
+
+/* compat-ok: :popover-open rides in a forgiving :is(), where an engine without
+   Popover discards just that member and .is-open alone keeps driving the open
+   state. This is a property of the forgiving list, not of the pseudo-class: in
+   a plain selector list an unsupported member would invalidate the whole rule.
+   Keep it inside :is()/:where() or gate it. */
+.flyout:is(.is-open, :popover-open):not(.is-sheet) {
   inset: auto;
 }
 
+/* compat-ok: forgiving :is() again, and @starting-style is itself unsupported
+   across part of the Minimal range, so the rule simply does not exist there. */
 @starting-style {
-  .flyout.is-open {
+  .flyout:is(.is-open, :popover-open) {
     opacity: 0;
   }
 }
@@ -123,16 +161,23 @@
   translate: 0 var(--space-30);
 }
 
+/* compat-ok: forgiving :is() inside @starting-style, as above. */
 @starting-style {
-  .flyout.is-sheet.is-open {
+  .flyout.is-sheet:is(.is-open, :popover-open) {
     translate: 0 var(--space-30);
   }
 }
 
+/* display keeps the exit transition alive for the [hidden] path; overlay does
+   the same for the native popover path, where hidePopover() would otherwise
+   drop the panel out of the top layer on the first frame and let a parent
+   overflow or a dialog clip the fade. An engine that cannot transition either
+   property ignores it and the exit is instant. */
 @supports (transition-behavior: allow-discrete) {
   .flyout {
     transition:
       opacity var(--duration-fast) ease,
+      overlay var(--duration-fast) allow-discrete,
       display var(--duration-fast) allow-discrete;
   }
 
@@ -140,6 +185,7 @@
     transition:
       opacity var(--duration-fast) ease,
       translate var(--duration-fast) ease,
+      overlay var(--duration-fast) allow-discrete,
       display var(--duration-fast) allow-discrete;
   }
 }

package/src/css/components/join.css

@@ -63,6 +63,13 @@
   border-end-start-radius: var(--join-es);
 }
 
+/* A square icon button has an explicit block size, which otherwise prevents
+   align-items: stretch from matching a taller labelled sibling. The button's
+   existing min-block-size keeps the standalone square-size invariant intact. */
+.join > .btn.icon-only {
+  block-size: auto;
+}
+
 .join > :first-child {
   --join-ss: var(--join-radius);
   --join-es: var(--join-radius);

package/src/css/components/menu.css

@@ -75,30 +75,36 @@
 /* Checkable menu items are one command with one accessible state. Their
    indicator is generated so authors do not add a second interactive input. */
 .menu-item:is([role="menuitemcheckbox"], [role="menuitemradio"])::before {
-  display: grid;
+  content: "";
+  display: block;
   flex: 0 0 var(--menu-item-icon-size);
   inline-size: var(--menu-item-icon-size);
-  place-items: center;
-}
-
-.menu-item[role="menuitemcheckbox"]::before {
-  content: "";
+  block-size: var(--menu-item-icon-size);
 }
 
 .menu-item[role="menuitemcheckbox"][aria-checked="true"]::before {
-  content: "✓";
+  background: currentColor;
+  -webkit-mask: var(--icon-check) center / contain no-repeat;
+  mask: var(--icon-check) center / contain no-repeat;
 }
 
 .menu-item[role="menuitemcheckbox"][aria-checked="mixed"]::before {
-  content: "−";
+  background:
+    linear-gradient(currentColor 0 0) center / 60% max(var(--border-width), 0.125em) no-repeat;
 }
 
 .menu-item[role="menuitemradio"]::before {
-  content: "○";
+  background: radial-gradient(circle, transparent 0 46%, currentColor 48% 58%, transparent 60%);
 }
 
 .menu-item[role="menuitemradio"][aria-checked="true"]::before {
-  content: "●";
+  background: radial-gradient(
+    circle,
+    currentColor 0 25%,
+    transparent 27% 46%,
+    currentColor 48% 58%,
+    transparent 60%
+  );
 }
 
 .menu-item:focus-visible {

package/src/css/components/tooltip.css

@@ -39,21 +39,57 @@
   transition: opacity var(--duration-fast) ease;
 }
 
+/* Neutralize only the native geometry that conflicts with a positioned
+   tooltip. In particular, the UA overflow would turn the arrow into scroll
+   overflow instead of letting it project beyond the bubble. Gated on real
+   Popover support: the attribute selector matches whether or not the engine
+   implements Popover, and without it nothing hides the element, so an ungated
+   reset would leave a stray bubble parked at inset: auto. Popover sits outside
+   Actual's Minimal contract, so the gate tracks the capability rather than the
+   floor. */
+@supports selector(:popover-open) {
+  .tooltip[popover] {
+    inset: auto;
+    margin: 0;
+    overflow: visible;
+  }
+
+  /* .tooltip declares no display of its own, so the UA already hides a closed
+     popover here. The rule is written anyway: both components advertised as
+     Popover-compatible should cede the hidden state the same way, and the
+     opacity target is what actually makes the native exit fade — see the
+     overlay note below. */
+  .tooltip[popover]:not(:popover-open) {
+    display: none;
+    opacity: 0;
+  }
+}
+
 .tooltip[hidden] {
   display: none;
   opacity: 0;
 }
 
+/* Entry opacity for both lifecycles: a runtime-driven tip is visible when it
+   is neither a popover nor [hidden], a native one when it is :popover-open.
+   compat-ok: [popover] appears here only under negation, which every engine
+   evaluates correctly whether or not it implements Popover, :popover-open
+   rides in a forgiving :is(), and @starting-style is itself unsupported across
+   part of the Minimal range — so the rule does not exist there at all. */
 @starting-style {
-  .tooltip:not([hidden]) {
+  .tooltip:is(:not([popover]):not([hidden]), :popover-open) {
     opacity: 0;
   }
 }
 
+/* overlay is the native popover counterpart of display: it holds the tip in
+   the top layer until the fade finishes, instead of letting hidePopover()
+   demote it on the first frame. Ignored where unsupported. */
 @supports (transition-behavior: allow-discrete) {
   .tooltip {
     transition:
       opacity var(--duration-fast) ease,
+      overlay var(--duration-fast) allow-discrete,
       display var(--duration-fast) allow-discrete;
   }
 }

package/src/js/status.js

@@ -31,6 +31,12 @@
  *   - Any other code, without importing this module: dispatch `actual:status`
  *     directly — `detail: { message, intent, duration }`, or `{}` to clear.
  *
+ * A message originating inside an open dialog temporarily mounts the singleton
+ * bar in that dialog. Content outside a modal dialog is inert and cannot sit
+ * above its top layer, so this keeps both the visual feedback and live region
+ * in the active subtree. Programmatic callers pass the originating element as
+ * `options.source`; event and command entry points propagate it automatically.
+ *
  * The element contract is `[data-status][role="status"]`. Both are required:
  * "status" is a generic domain word, so `role="status"` keeps the
  * document-wide lookup from matching an unrelated app element that happens to
@@ -59,12 +65,39 @@ let statusTimer;
 // never emptied by the previous message's cleanup.
 let statusGeneration = 0;
 let viewportTracker = null;
+const statusHomes = new WeakMap();
 
 function statusTarget() {
   if (typeof document === "undefined") return null;
   return document.querySelector(STATUS_SELECTOR);
 }
 
+function restoreStatusTarget(target) {
+  const home = statusHomes.get(target);
+  if (!home) return;
+
+  const parent = home.parent?.isConnected ? home.parent : target.ownerDocument?.body;
+  if (parent) {
+    const reference = home.nextSibling?.parentNode === parent ? home.nextSibling : null;
+    parent.insertBefore(target, reference);
+  }
+  statusHomes.delete(target);
+}
+
+function mountStatusTarget(target, source) {
+  const dialog = source?.closest?.("dialog[open]");
+  if (!dialog || dialog.ownerDocument !== target.ownerDocument) {
+    restoreStatusTarget(target);
+    return;
+  }
+  if (dialog.contains(target)) return;
+
+  if (!statusHomes.has(target)) {
+    statusHomes.set(target, { parent: target.parentNode, nextSibling: target.nextSibling });
+  }
+  dialog.append(target);
+}
+
 // The bar is fixed to the layout viewport, so the mobile software keyboard
 // covers it. visualViewport reports the occluded band; the CSS adds it to the
 // bottom inset. Tracking runs only while a message is on screen.
@@ -130,6 +163,8 @@ export function status(message, options = {}) {
   clearTimeout(statusTimer);
   statusGeneration++;
 
+  mountStatusTarget(target, options.source);
+
   clearIntentClasses(target);
   const intent = intentClasses(options.intent);
   if (intent.length) {
@@ -168,6 +203,7 @@ status.clear = function clear() {
     target.textContent = "";
     clearIntentClasses(target);
     releaseViewport();
+    restoreStatusTarget(target);
   });
 };
 
@@ -198,7 +234,7 @@ function connectStatusTrigger(trigger, target) {
 if (typeof document !== "undefined") {
   document.addEventListener(EVENTS.invalid, (event) => {
     const message = event.detail?.message;
-    if (message) status(message, { intent: "danger" });
+    if (message) status(message, { intent: "danger", source: event.target });
   });
 
   // Public contract: any code can trigger the status bar this way, without
@@ -209,7 +245,7 @@ if (typeof document !== "undefined") {
     // paths end in the same exit, so a detail that lost its message never
     // strands a stale one on screen.
     if (message != null) {
-      status(message, { intent, duration });
+      status(message, { intent, duration, source: event.target });
     } else {
       status.clear();
     }

package/src/js/surface.js

@@ -1,7 +1,7 @@
+import { autoUpdate, reposition, repositionAt } from "@lekoala/floating";
 import enhance from "./enhance.js";
 import { registerEscapeDismissal } from "./escape.js";
 import { EVENTS } from "./events.js";
-import { autoUpdate, reposition, repositionAt } from "./floating.js";
 
 import { CLASSES } from "./selectors.js";
 import { waitForTransitions } from "./transition.js";
@@ -210,6 +210,10 @@ function startSurfaceResources(menu, state) {
     const armKey = (event) => {
       if (!event.defaultPrevented && SCROLL_KEYS.has(event.key)) arm(event);
     };
+    const dismissOnScroll = (event) => {
+      if (state.scrollIntentAt == null || menu.contains(event.target)) return;
+      closeSurface(menu);
+    };
     const captureOptions = { signal: controller.signal, capture: true };
     const passiveCaptureOptions = { ...captureOptions, passive: true };
     const doc = menu.ownerDocument;
@@ -217,20 +221,13 @@ function startSurfaceResources(menu, state) {
     doc.addEventListener("touchmove", arm, passiveCaptureOptions);
     doc.addEventListener("wheel", arm, passiveCaptureOptions);
     doc.addEventListener("keydown", armKey, { signal: controller.signal });
+    doc.addEventListener("scroll", dismissOnScroll, passiveCaptureOptions);
     state.stopScrollIntent = () => controller.abort();
   }
-  state.stopTracking = autoUpdate(menu, ({ type, targets, timeStamp }) => {
+  const anchor = state.point ? null : state.trigger || state.source;
+  state.stopTracking = autoUpdate(anchor, menu, ({ type }) => {
     if (menu.hidden) return;
-    if (
-      type === "scroll" &&
-      state.dismissOnScroll &&
-      state.scrollIntentAt != null &&
-      timeStamp >= state.scrollIntentAt &&
-      [...targets].some((target) => target !== menu && !menu.contains(target))
-    ) {
-      closeSurface(menu);
-      return;
-    }
+    if (type === "scroll" && state.dismissOnScroll) return;
     applyPresentation(menu, state);
     if (!positionSurface(menu)) closeSurface(menu);
   });
@@ -249,11 +246,30 @@ export function prepareSurface(menu) {
   reaperFor(menu)?.refresh(menu);
 }
 
+/*
+ * One lifecycle owner per surface. surface.js opens by clearing [hidden] and
+ * adding .is-open; it never calls showPopover(). So a [popover] panel handed to
+ * the runtime has two owners and stays shut: the platform keeps a popover it
+ * was never asked to show closed, whatever the runtime writes.
+ *
+ * This covers every popover value. "manual" is a candidate future transport for
+ * this module, which does not make it a legitimate mix today. Delete this guard
+ * in the commit that makes surface.js call showPopover().
+ */
+function warnPopoverConflict(panel) {
+  if (!panel.hasAttribute("popover")) return;
+  console.warn(
+    "Actual: the surface lifecycle cannot own a [popover] element — choose one lifecycle owner (remove the popover attribute, or drop the Actual enhancement).",
+    panel,
+  );
+}
+
 export function retainSurface(panel) {
   if (!panel) return () => {};
 
   let entry = surfaceRetainers.get(panel);
   if (!entry) {
+    warnPopoverConflict(panel);
     prepareSurface(panel);
     entry = { count: 0 };
     surfaceRetainers.set(panel, entry);

package/src/js/tooltip.js

@@ -27,9 +27,9 @@
  * Hide:       blur, pointer leave, Escape
  */
 
+import { autoUpdate, reposition } from "@lekoala/floating";
 import enhance from "./enhance.js";
 import { registerEscapeDismissal } from "./escape.js";
-import { autoUpdate, reposition } from "./floating.js";
 import { CLASSES } from "./selectors.js";
 
 const SHOW_DELAY_MS = 150;
@@ -163,7 +163,7 @@ function updateTrackedTip(tip, state) {
 function startTracking(tip, state) {
   if (state.stopTracking) return;
 
-  state.stopTracking = autoUpdate(tip, () => updateTrackedTip(tip, state));
+  state.stopTracking = autoUpdate(state.activeRef, tip, () => updateTrackedTip(tip, state));
 }
 
 function stopTracking(state) {