actual-css 0.2.0 → 0.3.0

package/docs/utilities.md

@@ -1,384 +0,0 @@
-# Utilities
-
-Utilities are a small escape hatch for common single-purpose needs. They should support composition, not become the primary way to build UI.
-
-- Prefer semantic HTML, components, and layout primitives first.
-- Add utilities only when the rule is broadly useful and unlikely to become a component.
-- Keep utility names stable, boring, and few.
-- Utilities should use logical properties where relevant.
-
-## Accessibility
-
-### Screen Reader Only
-
-Use `.sr-only` for text that should be available to assistive technology but visually hidden.
-
-```html
-<button class="btn ghost" type="button">
-  <i class="ti ti-menu-2" aria-hidden="true"></i>
-  <span class="sr-only">Open navigation</span>
-</button>
-```
-
-```css
-.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
-
-> Explicit overflow handling for content that may exceed its container.
-
-Use `.overflow-auto` when content may overflow its container, especially tables and code-like regions.
-
-```html
-<div class="overflow-auto">
-  <table class="table">
-    <caption>Team members</caption>
-    <thead>
-      <tr>
-        <th>Name</th>
-        <th>Role</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td>Alice Johnson</td>
-        <td>Admin</td>
-      </tr>
-    </tbody>
-  </table>
-</div>
-```
-
-```css
-.overflow-auto {
-  overflow: auto;
-}
-```
-
-## Sizing And Wrapping
-
-> Small layout corrections for controls, labels, and compact rails.
-
-Use `.fit` when a control or element should shrink to its content instead of filling the available inline space.
-
-```html
-<select class="select fit" aria-label="Theme">
-  <option>System</option>
-  <option>Light</option>
-  <option>Dark</option>
-</select>
-```
-
-Use `.nowrap` on a flex layout such as `.cluster` when the group must stay on one line.
-
-```html
-<div class="cluster nowrap sm">
-  <select class="select sm fit" aria-label="Segment">
-    <option>All segments</option>
-  </select>
-  <button class="btn sm outline" type="button">Filter</button>
-</div>
-```
-
-Use `.truncate` on the flexible item that should ellipsize inside a constrained row.
-
-```html
-<header class="cluster nowrap">
-  <strong class="truncate">A long account name that should not push actions away</strong>
-  <button class="btn sm ghost" type="button">Open</button>
-</header>
-```
-
-```css
-.fit {
-  inline-size: fit-content;
-  max-inline-size: 100%;
-}
-
-.nowrap {
-  flex-wrap: nowrap;
-  white-space: nowrap;
-}
-
-.truncate {
-  min-inline-size: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-```
-
-### Scroller
-
-Use `.scroller` to apply optional framework scrollbar treatment to a scroll container. It styles the scrollbar only; pair it with `.overflow-auto` or a component that already creates overflow.
-
-`scroller` is not imported by `actual.css`. Import it explicitly when a project wants Actual CSS scrollbar chrome instead of the native OS default:
-
-```css
-@import "actual-css/css/optional/scroller";
-```
-
-```html
-<div class="overflow-auto scroller" style="max-block-size: 12rem">
-  <div class="stack">
-    <p>Scrollable content keeps the native scrollbar but makes it quieter.</p>
-    <p>Long content can keep flowing without forcing every component to invent its own scrollbar rules.</p>
-    <p>The utility exposes local custom properties for one-off tuning.</p>
-  </div>
-</div>
-```
-
-```css
-.scroller {
-  --scroller-size: 0.625rem;
-  --scroller-padding: 0.125rem;
-  --scroller-track: transparent;
-  --scroller-thumb: var(--border);
-  --scroller-thumb-hover: var(--text-muted);
-
-  scrollbar-color: var(--scroller-thumb) var(--scroller-track);
-  scrollbar-width: thin;
-}
-```
-
-Customize locally when a scroll surface needs more contrast:
-
-```html
-<div class="overflow-auto scroller"
-     style="--scroller-thumb: var(--text-muted); --scroller-thumb-hover: var(--text)">
-  ...
-</div>
-```
-
-For rounded scroll containers, keep the thumb visually away from the edge by tuning `--scroller-padding` rather than adding extra wrappers or masking pseudo-elements.
-
-## Metadata Separator
-
-> A small inline dot for separating facts in a metadata row.
-
-Use `.dot` between short facts in a byline, timestamp row, or breadcrumb-like list of details — anywhere a plain `·` character would otherwise be typed as text (which screen readers announce awkwardly).
-
-```html
-<p class="cluster" style="--cluster-justify: flex-start;">
-  <span>Ada Meridian</span>
-  <span class="dot" aria-hidden="true"></span>
-  <time datetime="2026-06-12">June 12, 2026</time>
-  <span class="dot" aria-hidden="true"></span>
-  <span>8 min read</span>
-</p>
-```
-
-```css
-.dot {
-  flex: none;
-  inline-size: 0.25rem;
-  block-size: 0.25rem;
-  border-radius: var(--radius-full);
-  background: var(--text-subtle);
-}
-```
-
-Always mark it `aria-hidden="true"` — it is a visual separator, not content.
-
-## Flex Helpers
-
-> Small flex helpers for grow behavior and other one-line needs.
-
-### Grow
-
-Use `.grow` when one item in a flex layout should take available space without overflowing.
-
-```html
-<header class="cluster">
-  <a href="/" class="brand">Actual CSS</a>
-  <nav class="grow" aria-label="Main navigation">
-    <a href="/docs">Docs</a>
-    <a href="/components">Components</a>
-  </nav>
-  <button class="btn ghost" type="button">Menu</button>
-</header>
-```
-
-```css
-.grow {
-  flex: 1 1 auto;
-  min-inline-size: 0;
-}
-```
-
-### Item Alignment
-
-Use `.items-start` on flex or grid layouts when children should keep their natural height and align to the block-start edge. This is especially useful for form fields in a grid, where the default grid stretch would make short fields as tall as taller neighbors.
-
-```html
-<div class="grid items-start">
-  <label class="field">
-    <span class="field-label">Name</span>
-    <input type="text" />
-  </label>
-  <label class="field">
-    <span class="field-label">Notes</span>
-    <textarea></textarea>
-  </label>
-</div>
-```
-
-Use `.items-center` when a flex or grid layout should center its children on the cross axis. Use `.items-end` when children should align to the block-end edge.
-
-## Spacing Helpers
-
-> Semantic step helpers for gap, padding, and margin — the most common inline-style escape hatches.
-
-Spacing helpers use a restrained semantic scale:
-
-- `-sm` — small step, `--space-2` (0.5rem)
-- Default — standard step, `--space-4` (1rem)
-- `-lg` — large step, `--space-5` (1.5rem)
-
-All map to logical properties (`padding-block`, `margin-block-end`, etc.) for writing-direction safety.
-
-### Gap
-
-Override the default gap from layout primitives (`.stack`, `.cluster`, `.grid`):
-
-```html
-<ul class="cluster">
-  <li><a href="/about" class="btn ghost">About</a></li>
-  <li><a href="/contact" class="btn ghost">Contact</a></li>
-</ul>
-```
-
-- `.gap-none` → `gap: 0`
-
-### Padding
-
-Block (vertical) and inline (horizontal) padding. Values respond to the `.sm` / `.lg` modifiers.
-
-```html
-<section role="tabpanel" class="py">
-  Panel content with breathing room above and below.
-</section>
-```
-
-- `.py` → `padding-block: var(--variant-space)`
-- `.px` → `padding-inline: var(--variant-space)`
-
-### Margin
-
-Block-start and block-end margin for giving elements room:
-
-```html
-<h2 class="mbs">A section heading with space above</h2>
-```
-
-- `.mbs` → `margin-block-start: var(--variant-space)`
-- `.mbe` → `margin-block-end: var(--variant-space)`
-
-No `mbs-none` / `mbe-none` — use `margin: 0` via `.list-reset` for lists, or a layout primitive that already resets margins (`.stack > *`).
-
-## Text Helpers
-
-> Lightweight helpers for muted or secondary text without a full color scale.
-
-### Muted
-
-Use `.muted` for secondary text when no semantic element already carries the meaning.
-
-```html
-<p class="muted">Last updated June 12, 2026.</p>
-```
-
-```css
-.muted {
-  color: var(--text-muted);
-}
-```
-
-Do not create a full text color utility scale. Intent colors belong to components and state, not arbitrary text decoration.
-
-### Text Alignment
-
-Use `.text-start`, `.text-center`, or `.text-end` when a component or layout primitive does not already set alignment. These use logical properties so they follow the writing direction.
-
-### Text Wrap
-
-`.text-balance` and `.text-pretty` opt elements outside `.prose` into balanced or pretty text wrapping. They are safe progressive enhancements: browsers that do not support a `text-wrap` value ignore that declaration and keep normal wrapping.
-
-### Lead
-
-`.lead` is a slightly larger, more relaxed reading-introduction paragraph (`1.125em`, `--line-height-relaxed`). Use it for introductory text in editorial surfaces. For fluid headline sizing, use `src/css/optional/typography-fluid.css`.
-
-## Shape Helpers
-
-> Rare shape utilities for cases that must be perfectly round or square.
-
-Shape utilities should be rare because shape is mostly theme-level.
-
-### Circle
-
-Use `.circle` only when an element must be perfectly round.
-
-```html
-<img class="circle" src="https://i.pravatar.cc/48?img=5" alt="Jane Doe" width="48" height="48" />
-```
-
-```css
-.circle {
-  border-radius: var(--radius-full);
-}
-```
-
-Do not add `.rounded-sm`, `.rounded-lg`, `.square`, or `.pill` unless repeated real use proves they are needed.
-
-## Content
-
-### Measure
-
-`.measure` caps a block at a readable width using `--prose-measure`. It does not center — combine with `.center` for the common centered reading column, or with `margin-inline: auto` for a one-off centered block.
-
-Use it for any content that needs a comfortable measure: prose articles, TOC lists, form fields, callouts. Avoid using it for full-bleed surfaces.
-
-## List Helpers
-
-### List Reset
-
-`.list-reset` removes the native list chrome (margin, padding, markers) from any list. It is the generic version of `.nav-list` — use `.nav-list` when the list is a navigation list for semantic intent, and `.list-reset` for everything else (tag clouds, footer columns, related items, comment threads, embedded controls).
-
-## Editorial Labels
-
-### Overline
-
-`.overline` is a small editorial label: muted color, smaller size, uppercase, slight letter-spacing. It does not impose a shape by itself. Add `.pill` for a bordered rounded chip, and combine with an intent class (`.primary`, `.success`, etc.) to tint the chip's text, border, and background.
-
-The overline exists because categories, kicker labels, and section markers recur across editorial surfaces, and `.badge` is the wrong shape for them. `.badge` is a status indicator; `.overline` is metadata.
-
-## Link Variants
-
-### Plain
-
-`.link-plain` removes the link's underline and inherits the surrounding color. Use for chrome that is conceptually a link (a card title, a table row action, a tag, a breadcrumb segment) but should not look like prose.
-
-### Muted
-
-`.link-muted` is a `.link-plain` that starts in the muted text color and shifts to the full text color on hover. Use for navigation lists, table of contents, and other secondary navigation surfaces.
-
-## Non-Goals
-
-> Utilities deliberately excluded to keep the surface small and intentional.
-
-- No display scale such as `.block`, `.flex`, `.grid` — use layout primitives.
-- No color scales such as `.text-primary` or `.bg-success` — intent colors belong to components and state.
-- No breakpoint utility variants — use container queries or layout primitives.
-- No utility variants for hover, focus, dark mode, or arbitrary selectors — use component states.
-- No full spacing scale with every step and direction — the 17 spacing helpers above cover the most common escape hatches.

package/src/css/dialog-fallback.css

@@ -1,56 +0,0 @@
-/*
- * Legacy dialog fallback — presentation for the dialog-fallback.js shim
- * (browsers without native <dialog>: Safari <= 15.3, Firefox <= 97).
- *
- * Isolated in its own file so a custom bundle can opt out by dropping this
- * import; the JS side is disabled with data-dialog-fallback="false" on the
- * root element or on a dialog. Must load before component styles so ties
- * such as dialog.modal's padding resolve in the component's favor.
- *
- * The whole file is inert on modern browsers: rules key on the
- * .dialog-fallback marker written by the shim, so browsers that support
- * <dialog> but not :modal are never affected either.
- */
-@supports not (selector(dialog:modal)) {
-  /* Browsers without native <dialog> ship no UA dialog styles at all;
-     approximate them. :where() keeps specificity at dialog[open] level so
-     component styles such as dialog.modal still override the emulation. */
-  dialog[open]:where(.dialog-fallback) {
-    position: absolute;
-    inset-inline: 0;
-    width: -moz-fit-content;
-    width: fit-content;
-    max-inline-size: calc(100% - 2rem);
-    margin: auto;
-    padding: var(--space-4, 1em);
-    border: var(--border-width, 1px) solid var(--border, currentColor);
-    background: var(--surface-raised, #fff);
-    color: var(--text, inherit);
-  }
-
-  /* Open modally: fixed near the top (no fit-content in the block axis on
-     these browsers, so no vertical centering) and above menus, below
-     tooltips. Legacy-only layer, hence no z-index token. The spread shadow is
-     the visible backdrop: the dialog is its own stacking context, where a
-     negative z-index child paints above the element's background, so the
-     dimming cannot live on the ::before. */
-  dialog[open].is-fallback-modal {
-    position: fixed;
-    inset-block: 8vh auto;
-    max-block-size: 84vh;
-    overflow: auto;
-    z-index: 40;
-    box-shadow: 0 0 0 100vmax var(--backdrop-fill, rgb(0 0 0 / 35%));
-  }
-
-  /* Transparent stand-in for ::backdrop, hit-testing only. Clicks on it hit
-     the dialog element outside its own box, which dialog.js already treats as
-     a backdrop click, and it blocks pointer interaction with the page behind
-     the modal. */
-  dialog[open].is-fallback-modal::before {
-    content: "";
-    position: fixed;
-    inset: 0;
-    z-index: -1;
-  }
-}

package/src/js/dialog-fallback.js

@@ -1,163 +0,0 @@
-/*
- * Dialog fallback — minimal per-element shim for browsers without native
- * <dialog> support (Safari <= 15.3, Firefox <= 97, both below Baseline 2023).
- *
- * Standalone side-effect module: the default runtime imports it, a custom
- * build opts out by omitting it — dialog.js has no dependency on this file
- * and falls back to its acknowledgement alert without it. On supporting
- * browsers importing this module registers nothing.
- *
- * Not a polyfill: no top layer, no focus trap, no inert background. It only
- * provides show()/showModal()/close(), an `open` property, and the
- * form[method=dialog] close-on-submit contract (otherwise those forms really
- * navigate on legacy browsers), so dialog.js can run its normal wiring —
- * backdrop click, Escape cancel, close events, focus restore, and the scroll
- * lock all come from that wiring, not from here.
- *
- * Presentation lives in dialog-fallback.css, keyed on the classes written
- * below. The simulated backdrop is split in two there: a spread box-shadow
- * for the dimming, and a transparent ::before covering the viewport for
- * hit-testing — clicks on it target the dialog element outside its own box,
- * which dialog.js already treats as a backdrop click, and it blocks pointer
- * interaction with the page behind the modal.
- *
- * An adopter-provided polyfill (e.g. dialog-polyfill) still wins: elements it
- * already patched expose showModal() and are left untouched.
- */
-
-import { targetFor } from "./command.js";
-import enhance from "./enhance.js";
-import { CLASSES } from "./selectors.js";
-
-function supportsDialog() {
-  return (
-    typeof HTMLDialogElement !== "undefined" &&
-    typeof HTMLDialogElement.prototype.showModal === "function"
-  );
-}
-
-function focusInitial(dialog) {
-  const target = dialog.querySelector("[autofocus]") || dialog;
-  if (target === dialog && !dialog.hasAttribute("tabindex")) {
-    dialog.setAttribute("tabindex", "-1");
-  }
-  target.focus?.();
-}
-
-/**
- * Patch one dialog element with rudimentary show/showModal/close support.
- * No-op when the element is already controllable (native or polyfilled).
- *
- * @param {HTMLElement} dialog A <dialog> element.
- */
-export default function shimDialog(dialog) {
-  if (
-    typeof dialog.show === "function" &&
-    typeof dialog.showModal === "function" &&
-    typeof dialog.close === "function"
-  ) {
-    return;
-  }
-
-  const doc = dialog.ownerDocument;
-  let escController = null;
-  let savedScroll = null;
-
-  function stopEscapeListener() {
-    escController?.abort();
-    escController = null;
-  }
-
-  function handleSubmit(event) {
-    const form = event.target;
-    // Read the attribute: on these browsers "dialog" is an invalid method
-    // value, so the reflected form.method property reports "get" and the
-    // form would otherwise really submit and navigate away.
-    if (form?.getAttribute?.("method")?.toLowerCase() !== "dialog") return;
-    event.preventDefault();
-    const submitter =
-      event.submitter || (doc.activeElement?.form === form ? doc.activeElement : null);
-    dialog.close(submitter?.value || "");
-  }
-
-  function handleEscape(event) {
-    if (event.key !== "Escape") return;
-    event.preventDefault();
-    const cancel = new Event("cancel", { cancelable: true });
-    // dialog.js always claims the cancel event and decides itself whether to
-    // close; only an unwired dialog falls through to the direct close.
-    if (dialog.dispatchEvent(cancel)) {
-      dialog.close();
-    }
-  }
-
-  function open(modal) {
-    if (dialog.open) return;
-    // Old WebKit clamps the scroll position to 0 when the root element gains
-    // overflow:hidden (the has-modal-open lock applied right after this),
-    // losing the user's place. Remember it and put it back after close.
-    const win = doc.defaultView;
-    savedScroll = modal && win ? { x: win.scrollX, y: win.scrollY } : null;
-    dialog.setAttribute("open", "");
-    dialog.classList.toggle(CLASSES.fallbackModal, modal);
-    if (modal) {
-      escController = new AbortController();
-      doc.addEventListener("keydown", handleEscape, { signal: escController.signal });
-    }
-    focusInitial(dialog);
-  }
-
-  Object.defineProperty(dialog, "open", {
-    configurable: true,
-    get() {
-      return this.hasAttribute("open");
-    },
-    set(value) {
-      this.toggleAttribute("open", Boolean(value));
-    },
-  });
-
-  dialog.returnValue = "";
-  dialog.classList.add(CLASSES.dialogFallback);
-  dialog.addEventListener("submit", handleSubmit);
-  dialog.show = () => open(false);
-  dialog.showModal = () => open(true);
-  dialog.close = (returnValue = "") => {
-    if (!dialog.open) return;
-    stopEscapeListener();
-    dialog.returnValue = returnValue;
-    dialog.removeAttribute("open");
-    dialog.classList.remove(CLASSES.fallbackModal);
-    dialog.dispatchEvent(new Event("close"));
-    // After the close event: dialog.js has lifted the scroll lock and moved
-    // focus back to the trigger, so the restored position sticks.
-    if (savedScroll) {
-      doc.defaultView?.scrollTo?.(savedScroll.x, savedScroll.y);
-      savedScroll = null;
-    }
-  };
-}
-
-if (typeof document !== "undefined" && !supportsDialog()) {
-  enhance({
-    dialog: (el) => {
-      shimDialog(el);
-    },
-  });
-
-  // A dialog inserted right before its trigger's click may not be scanned by
-  // enhance() yet, so shim command targets in capture phase too — before the
-  // delegated command routing resolves them.
-  document.addEventListener(
-    "click",
-    (event) => {
-      const trigger = event.target?.closest?.("button[commandfor][command]");
-      if (!trigger) return;
-      const dialog = targetFor(trigger);
-      if (dialog?.localName === "dialog") {
-        shimDialog(dialog);
-      }
-    },
-    true,
-  );
-}