actual-css 0.1.0

package/src/css/utilities.css

@@ -0,0 +1,162 @@
+/*
+ * Small, single-purpose utilities for common escape hatches.
+ *
+ * These support components and layout primitives without becoming a
+ * utility-first API.
+ */
+.sr-only {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.overflow-auto {
+  overflow: auto;
+}
+
+.fit {
+  inline-size: fit-content;
+  max-inline-size: 100%;
+}
+
+.grow {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+}
+
+.nowrap {
+  white-space: nowrap;
+}
+
+.truncate {
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.items-start {
+  --items-align: start;
+  align-items: start;
+}
+
+.items-center {
+  --items-align: center;
+  align-items: center;
+}
+
+.items-end {
+  --items-align: end;
+  align-items: end;
+}
+
+.muted {
+  color: var(--text-muted);
+}
+
+/* Circle: forces a fully round shape without mutating global radius tokens.
+   Works on any component because utilities load after components. .join is
+   the one exception: it writes corner longhands on its children, so
+   .join.circle keeps its own --join-radius hook (join.css). */
+.circle {
+  border-radius: var(--radius-full);
+}
+
+/* Text alignment — uses logical properties so it follows writing direction. */
+.text-start {
+  --text-align: start;
+  text-align: start;
+}
+
+.text-center {
+  --text-align: center;
+  text-align: center;
+}
+
+.text-end {
+  --text-align: end;
+  text-align: end;
+}
+
+/* Text wrapping utilities. Unsupported values are ignored by the browser. */
+.text-balance {
+  text-wrap: balance;
+}
+
+.text-pretty {
+  text-wrap: pretty;
+}
+
+/* Generic list chrome reset. Use for any list (tags, footer columns, related
+   items). For navigation lists, prefer .nav-list for semantic intent.
+   components/{actions,navbar}.css apply their own resets where needed. */
+.list-reset {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Separator dot for inline metadata rows (byline, timestamp, read time,
+   breadcrumb-like facts). Pair with a flex/cluster container; flex: none
+   keeps a flex parent from shrinking it to nothing. */
+.dot {
+  flex: none;
+  inline-size: 0.25rem;
+  block-size: 0.25rem;
+  border-radius: var(--radius-full);
+  background: var(--text-subtle);
+}
+
+/* Link variants for chrome that should not look like prose links. Use in
+   navigation, tags, footer, tables of contents, and similar surfaces. */
+.link-plain {
+  color: inherit;
+  text-decoration: none;
+}
+
+.link-muted {
+  color: var(--text-muted);
+  text-decoration: none;
+}
+
+@media (hover: hover) {
+  .link-muted:hover {
+    color: var(--text);
+  }
+}
+
+/* Spacing step helpers — semantic scale (sm / default / lg).
+   Names map to logical properties for writing-direction safety. The default
+   step uses --space-4, which matches the framework's built-in padding on
+   cards, dialogs, and form-actions. */
+
+/* Gap */
+.gap-none {
+  gap: 0;
+}
+
+/* Padding — block (vertical) */
+.py {
+  padding-block: var(--variant-space);
+}
+
+/* Padding — inline (horizontal) */
+.px {
+  padding-inline: var(--variant-space);
+}
+
+/* Margin — block-start */
+.mbs {
+  margin-block-start: var(--variant-space);
+}
+
+/* Margin — block-end */
+.mbe {
+  margin-block-end: var(--variant-space);
+}

package/src/css/variants.css

@@ -0,0 +1,118 @@
+/*
+ * Cross-cutting variant token mapping.
+ *
+ * Variant scope: .solid/.soft/.outline set --ui-* for components that opt into
+ * shared variants. Component-specific defaults (.btn solid-by-default, .badge
+ * solid-by-default, .alert soft-by-default) live with their components:
+ *   components/button.css — .btn default solid + .btn.ghost + .btn.link
+ *   components/badge.css   — .badge default solid
+ *   components/alert.css   — .alert default + .alert.solid/.alert.outline
+ *
+ * .sm/.lg set shared size tokens. Controls consume --control-*; non-control
+ * components may consume --variant-* when the variant should affect their
+ * local density. Compact components may consume --variant-compact-*.
+ * Components with bespoke sizing (spinner, avatar) define local .sm/.lg;
+ * applying .sm/.lg to card, dialog, accordion, navbar, table is
+ * a no-op.
+ *
+ * Intent list source of truth: intents.css. Components consume --intent* tokens
+ * instead of re-listing intent classes.
+ */
+.solid {
+  --ui-bg: var(--intent, var(--neutral));
+  --ui-fg: var(--intent-fg, var(--neutral-fg));
+  --ui-border: transparent;
+}
+
+.soft {
+  --ui-bg: var(--surface-subtle);
+  --ui-border: var(--border);
+  --ui-fg: var(--intent, var(--text));
+}
+
+.outline {
+  --ui-bg: transparent;
+  --ui-fg: var(--intent, var(--text));
+  --ui-border: var(--intent, var(--border));
+}
+
+.sm {
+  --gap: var(--space-2);
+  --variant-space: var(--space-2);
+  --control-size: var(--control-size-sm);
+  --control-font-size: var(--font-size-sm);
+  --variant-font-size: var(--font-size-sm);
+  --variant-icon-size: 1rem;
+  --variant-pad-block: var(--space-3);
+  --variant-compact-size: 1.25rem;
+  --variant-compact-font-size: 0.75rem;
+}
+.lg {
+  --gap: var(--space-5);
+  --variant-space: var(--space-5);
+  --control-size: var(--control-size-lg);
+  --control-font-size: var(--font-size-lg);
+  --variant-font-size: var(--font-size-lg);
+  --variant-icon-size: 1.5rem;
+  --variant-pad-block: var(--space-5);
+  --variant-compact-size: 1.875rem;
+  --variant-compact-font-size: var(--font-size-sm);
+}
+
+/* Modern color enhancement. Baseline variant values above remain usable
+   everywhere. Interactive states live in the components that consume them. */
+@supports (color: color-mix(in oklch, red, white)) {
+  .soft {
+    /* @sync soft-recipe */
+    --ui-bg: color-mix(in oklch, var(--surface) var(--soft-bg-mix), var(--intent, var(--neutral)));
+    --ui-border: color-mix(
+      in oklch,
+      var(--surface) var(--soft-border-mix),
+      var(--intent, var(--neutral))
+    );
+    /* @sync soft-recipe */
+  }
+}
+
+/* Interactive hover recipe shared by .btn and .badge. Declared outside :hover
+   on purpose: --ui-hover-bg is only consumed inside their @media (hover: hover)
+   rules, so these values are inert until hovered. :is() carries real
+   specificity so the components' :where() intent boundaries
+   (--ui-hover-bg: initial) cannot override the recipe. The solid/soft overlay
+   darkening lives in the consuming components. */
+:is(.btn, a.badge, button.badge):is(.outline, .ghost) {
+  --ui-hover-bg: var(--surface-subtle);
+}
+
+@supports (color: color-mix(in oklch, red, white)) {
+  /* Solid has no literal class requirement: bare .btn/.badge default to solid,
+     so this must match anything that isn't one of the other variants rather
+     than an explicit .solid class. Stacks with the box-shadow overlay the
+     consuming components apply on top for extra depth. */
+  :is(.btn, a.badge, button.badge):not(:where(.soft, .outline, .ghost, .link)) {
+    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
+  }
+
+  /* Same recipe as the resting .soft bg with the surface share reduced by
+     --soft-hover-alpha: stays opaque, so it reads on any backdrop instead of
+     letting the container show through on hover. */
+  :is(.btn, a.badge, button.badge):is(.soft) {
+    --ui-hover-bg: color-mix(
+      in oklch,
+      var(--surface) calc(var(--soft-bg-mix) - var(--soft-hover-alpha)),
+      var(--intent, var(--neutral))
+    );
+  }
+
+  /* Mixed against the opaque --surface-subtle rather than transparent: a
+     transparent-based tint reads clean on light surfaces but goes muddy and
+     low-contrast on dark ones, since the same low alpha lands very
+     differently over a light vs. a near-black backdrop. */
+  :is(.btn, a.badge, button.badge):is(.outline) {
+    --ui-hover-bg: color-mix(in oklch, var(--surface-subtle) 92%, var(--intent, var(--neutral)));
+  }
+
+  :is(.btn, a.badge, button.badge):is(.ghost) {
+    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--text)) 8%, transparent);
+  }
+}

package/src/js/command.js

@@ -0,0 +1,165 @@
+/*
+ * Command — stateless command/commandfor routing.
+ *
+ * The registry tracks command handlers, never triggers or targets. One click
+ * listener per document reads the current DOM at event time, resolves the
+ * current commandfor target, and routes the action. Newly inserted triggers,
+ * late targets, changed commandfor values, and same-id replacements therefore
+ * work immediately without an observer, scan, refresh call, or per-element
+ * listener.
+ */
+
+/* One registry per document owns its delegated listener and command handlers.
+ * The WeakMap does not retain discarded documents; registry entries contain
+ * behavior definitions only, never DOM triggers or resolved targets. */
+const registries = new WeakMap();
+
+function commandNames(commands, caller) {
+  const names = Array.isArray(commands) ? commands : [commands];
+  if (!names.length || names.some((name) => typeof name !== "string" || !name)) {
+    throw new TypeError(`${caller} requires one or more command names.`);
+  }
+  return [...new Set(names)];
+}
+
+// Native command keywords are ASCII case-insensitive. Custom commands keep
+// their exact spelling, as required by the command invoker contract.
+function commandKey(command) {
+  return command.startsWith("--")
+    ? command
+    : command.replace(/[A-Z]/g, (character) => character.toLowerCase());
+}
+
+/**
+ * Resolve a trigger's current `commandfor` target in the same document or
+ * shadow root.
+ *
+ * @param {Element} trigger Element carrying the `commandfor` attribute.
+ * @returns {Element | null} The current target, or `null` when it cannot be resolved.
+ */
+export function targetFor(trigger) {
+  const id = trigger.getAttribute("commandfor");
+  if (!id) return null;
+
+  const root = trigger.getRootNode();
+  return root.getElementById?.(id) ?? null;
+}
+
+/**
+ * Build the button selector corresponding to one or more command names.
+ *
+ * @param {string | string[]} commands Command name or names to include.
+ * @returns {string} A selector matching command buttons with `commandfor`.
+ * @throws {TypeError} When no valid command name is provided.
+ */
+export function commandSelector(commands) {
+  const attributes = commandNames(commands, "commandSelector()").map(
+    (name) => `[command="${name.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"]`,
+  );
+  return `button[commandfor]:is(${attributes.join(", ")})`;
+}
+
+function triggerFromEvent(event, doc) {
+  const ElementClass = doc.defaultView?.Element;
+  if (!ElementClass) return null;
+
+  for (const node of event.composedPath?.() ?? [event.target]) {
+    if (node instanceof ElementClass && node.matches("button[commandfor][command]")) {
+      return node;
+    }
+    if (node === doc) break;
+  }
+
+  return null;
+}
+
+function createRegistry(doc) {
+  const commands = new Map();
+
+  function route(event) {
+    if (event.defaultPrevented) return;
+
+    const trigger = triggerFromEvent(event, doc);
+    if (!trigger || trigger.disabled) return;
+
+    const command = commandKey(trigger.getAttribute("command"));
+    const registration = commands.get(command);
+    if (!registration) return;
+
+    const target = registration.resolve(trigger);
+    if (!target) return;
+
+    registration.prepare?.(trigger, target, command);
+    registration.handle(event, trigger, target, command);
+  }
+
+  doc.addEventListener("click", route);
+  return { commands, route };
+}
+
+/**
+ * Register one behavior for one or more command names.
+ *
+ * `prepare`, when present, runs immediately before `handle` on every matching
+ * action. It must be idempotent; it is useful for semantics derived from the
+ * resolved target, without introducing a connection lifecycle.
+ *
+ * @param {string | string[]} commands Command name or names owned by this behavior.
+ * @param {object} options Behavior callbacks.
+ * @param {(trigger: HTMLButtonElement) => Element | null} [options.resolve=targetFor]
+ * Resolver evaluated for every action.
+ * @param {(trigger: HTMLButtonElement, target: Element, command: string) => void} [options.prepare]
+ * Optional idempotent callback run immediately before the handler.
+ * @param {(event: MouseEvent, trigger: HTMLButtonElement, target: Element, command: string) => void} options.handle
+ * Command handler.
+ * @returns {{ disconnect: () => void }} An idempotent registration teardown handle.
+ * @throws {TypeError} When command names or callbacks are invalid.
+ * @throws {Error} When a command already has an owner in the current document.
+ */
+export function registerCommands(commands, { resolve = targetFor, prepare, handle } = {}) {
+  const names = [
+    ...new Set(commandNames(commands, "registerCommands()").map((name) => commandKey(name))),
+  ];
+  if (
+    typeof resolve !== "function" ||
+    (prepare !== undefined && typeof prepare !== "function") ||
+    typeof handle !== "function"
+  ) {
+    throw new TypeError("registerCommands() requires function callbacks.");
+  }
+  if (typeof document === "undefined") return { disconnect() {} };
+
+  const doc = document;
+  let registry = registries.get(doc);
+  if (!registry) {
+    registry = createRegistry(doc);
+    registries.set(doc, registry);
+  }
+
+  const conflict = names.find((name) => registry.commands.has(name));
+  if (conflict) {
+    throw new Error(`Command "${conflict}" is already registered in this document.`);
+  }
+
+  const registration = { resolve, prepare, handle };
+  for (const name of names) registry.commands.set(name, registration);
+
+  let connected = true;
+  return {
+    disconnect() {
+      if (!connected) return;
+      connected = false;
+
+      for (const name of names) {
+        if (registry.commands.get(name) === registration) {
+          registry.commands.delete(name);
+        }
+      }
+
+      if (!registry.commands.size) {
+        doc.removeEventListener("click", registry.route);
+        registries.delete(doc);
+      }
+    },
+  };
+}