actual-css 0.1.0

package/docs/utilities.md

@@ -0,0 +1,384 @@
+# 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/llms.txt

@@ -0,0 +1,17 @@
+# Actual CSS
+
+> Plain CSS component framework for new projects: semantic classes, shared variants, small tokens, theme hooks, and progressive enhancement.
+
+Actual CSS uses a small public grammar: `.component [intent] [variant] [size] [modifier]`. It claims unprefixed class names by design. Existing projects with collisions should use cascade layers, import order, or an application-side prefix transform.
+
+## Documentation
+
+- [Docs index](docs/README.md): the maintained map of user docs and design notes.
+
+## Package Entrypoints
+
+`package.json#exports` is the canonical package surface. Use `actual-css` for the
+full CSS framework and `actual-css/js` for the complete runtime. The composition
+guides in [README](README.md) and [JavaScript](docs/javascript.md) show supported
+CSS modules and individual enhancer imports without duplicating the full export
+list here.

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "actual-css",
+  "version": "0.1.0",
+  "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
+  "type": "module",
+  "packageManager": "bun@1.3.14",
+  "license": "MIT",
+  "author": "Thomas <thomas@lekoala.be>",
+  "repository": {
+    "type": "git",
+    "url": "https://onedev.kalyptus.ovh/actual-css.git"
+  },
+  "homepage": "https://onedev.kalyptus.ovh/actual-css",
+  "bugs": {
+    "url": "https://onedev.kalyptus.ovh/actual-css/issues"
+  },
+  "keywords": [
+    "css",
+    "css-framework",
+    "component-library",
+    "semantic",
+    "accessibility",
+    "dark-mode",
+    "themable",
+    "no-build",
+    "progressive-enhancement"
+  ],
+  "exports": {
+    ".": "./dist/actual.min.css",
+    "./css": "./src/css/actual.css",
+    "./css/layer": "./src/css/actual.layer.css",
+    "./css/components": "./src/css/components/index.css",
+    "./css/forms": "./src/css/forms/index.css",
+    "./css/themes": null,
+    "./css/themes/*": null,
+    "./css/*": "./src/css/*.css",
+    "./js": "./src/js/index.js",
+    "./js/command": "./src/js/command.js",
+    "./js/context-menu": "./src/js/context-menu.js",
+    "./js/dialog": "./src/js/dialog.js",
+    "./js/dialog-fallback": "./src/js/dialog-fallback.js",
+    "./js/enhance": "./src/js/enhance.js",
+    "./js/filter": "./src/js/filter.js",
+    "./js/floating": "./src/js/floating.js",
+    "./js/flyout": "./src/js/flyout.js",
+    "./js/input": "./src/js/input.js",
+    "./js/mask": "./src/js/mask.js",
+    "./js/password": "./src/js/password.js",
+    "./js/scrollspy": "./src/js/scrollspy.js",
+    "./js/selectors": "./src/js/selectors.js",
+    "./js/tab": "./src/js/tab.js",
+    "./js/tooltip": "./src/js/tooltip.js",
+    "./js/validation": "./src/js/validation.js",
+    "./js/status": "./src/js/status.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/actual.js",
+  "style": "./dist/actual.min.css",
+  "unpkg": "./dist/actual.min.css",
+  "jsdelivr": "./dist/actual.min.css",
+  "sideEffects": true,
+  "files": [
+    "dist",
+    "!dist/actual-themes.min.css",
+    "!dist/actual-themes.min.css.map",
+    "src/css",
+    "!src/css/themes",
+    "src/js",
+    "docs",
+    "CHANGELOG.md",
+    "llms.txt",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "build:demo": "bun scripts/build-demo.js",
+    "watch:demo": "bun scripts/build-demo.js --watch",
+    "build:dist": "bun scripts/build-dist.js",
+    "build:js": "bun scripts/build-js.js",
+    "build:size": "bun scripts/build-size.js",
+    "check:reserved": "bun scripts/check-reserved.js",
+    "check:links": "bun scripts/check-doc-links.js",
+    "check:templates": "bun scripts/check-templates.js",
+    "shot:forced": "bun scripts/forced-colors-shot.js",
+    "shot:page": "bun scripts/page-shot.js",
+    "check:sync": "bun scripts/check-sync.js",
+    "test": "bun test",
+    "build:all": "bun run build:demo && bun run build:dist && bun run check:reserved && bun run check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:js && bun run build:size",
+    "prepublishOnly": "bun run build:all"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.0",
+    "happy-dom": "^20.10.6",
+    "prismjs": "^1.30.0"
+  }
+}

package/src/css/actual.css

@@ -0,0 +1,17 @@
+@import "./reset.css";
+@import "./dialog-fallback.css";
+@import "./tokens.css";
+@import "./theme.css";
+@import "./base.css";
+@import "./intents.css";
+@import "./layout.css";
+@import "./grid.css";
+@import "./variants.css";
+@import "./prose.css";
+@import "./components/index.css";
+@import "./forms/index.css";
+@import "./utilities.css";
+/* Joined controls are a component, but must load after the controls it groups. */
+@import "./components/join.css";
+@import "./focus.css";
+@import "./print.css";

package/src/css/actual.full.css

@@ -0,0 +1,2 @@
+@import "actual.css";
+@import "optional/index.css";

package/src/css/actual.layer.css

@@ -0,0 +1,3 @@
+@layer actual;
+
+@import url("./actual.css") layer(actual);

package/src/css/base.css

@@ -0,0 +1,70 @@
+/*
+ * Base element styles for native HTML semantics.
+ *
+ * Sits between reset (browser defaults) and prose (rich content scope).
+ * These styles apply everywhere — cards, dialogs, heroes — not only in prose.
+ */
+
+body {
+  background: var(--surface);
+  color: var(--text);
+  font-family: var(--font-sans);
+  line-height: var(--line-height);
+}
+
+a {
+  color: inherit;
+  text-underline-offset: 0.18em;
+}
+
+a:focus-visible {
+  box-shadow: var(--focus-ring-shadow);
+}
+
+@media (hover: hover) {
+  a:hover {
+    text-decoration-thickness: 0.12em;
+  }
+}
+
+/* Global heading chrome: color (--heading or inherit), a tight line-height,
+   and progressive text-wrap. No font-size or font-weight is set globally —
+   components and .prose own the per-context scale. */
+:where(h1, h2, h3, h4, h5, h6) {
+  color: var(--heading, inherit);
+  line-height: var(--line-height-tight);
+  text-wrap: balance;
+}
+
+/* Compact heading groups. Structural only: display, gap, internal margin reset.
+   No font-size, color, or weight is applied here. */
+hgroup {
+  display: grid;
+  gap: var(--hgroup-gap);
+}
+
+hgroup > * {
+  margin-block: 0;
+}
+
+hr {
+  border: 0;
+  border-block-start: var(--border-width) solid var(--border);
+  margin-block: var(--space-6);
+}
+
+code,
+kbd,
+samp,
+pre {
+  font-family: var(--font-mono);
+}
+
+small {
+  font-size: 0.875em;
+}
+
+::selection {
+  background: var(--selection-bg, var(--primary));
+  color: var(--selection-fg, var(--primary-fg));
+}

package/src/css/components/accordion.css

@@ -0,0 +1,97 @@
+/*
+ * Accordion disclosures built on native details and summary.
+ *
+ * Keeps the clickable summary affordance aligned and usable without JavaScript
+ * or demo styles. Decorative palettes and custom markers belong outside the
+ * base component.
+ */
+.accordion {
+  --accordion-radius: var(--radius);
+
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--accordion-radius);
+  background: var(--surface-raised);
+}
+
+.accordion > details + details {
+  border-block-start: var(--border-width) solid var(--border);
+}
+
+.accordion summary {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  cursor: pointer;
+  list-style: none;
+  padding: var(--space-4);
+  color: var(--text);
+  font-weight: var(--font-weight-bold);
+}
+
+.accordion summary::-webkit-details-marker {
+  display: none;
+}
+
+.accordion summary::after {
+  content: "";
+  flex: 0 0 auto;
+  margin-inline-start: auto;
+  inline-size: 1rem;
+  block-size: 1rem;
+  background-color: var(--text-muted);
+  -webkit-mask-image: var(--icon-chevron-mask);
+  mask-image: var(--icon-chevron-mask);
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-size: contain;
+  mask-size: contain;
+  -webkit-mask-position: center;
+  mask-position: center;
+  transition: transform var(--duration);
+}
+
+.accordion details[open] summary::after {
+  transform: rotate(180deg);
+}
+
+.accordion details > summary + * {
+  padding-block: 0 var(--space-4);
+  padding-inline: var(--space-4);
+  color: var(--text-muted);
+  margin-block: 0;
+}
+
+.accordion details[open] > summary + * {
+  padding-block-start: var(--space-1);
+}
+
+.accordion details > summary + * > :first-child {
+  margin-block-start: 0;
+}
+
+.accordion details > summary + ul,
+.accordion details > summary + ol {
+  margin: 0;
+  padding-inline-start: 2rem;
+}
+
+@media (forced-colors: active) {
+  .accordion {
+    border-color: ButtonText;
+    background: Canvas;
+    color: CanvasText;
+  }
+
+  .accordion > details + details {
+    border-block-start-color: ButtonText;
+  }
+
+  .accordion summary {
+    color: CanvasText;
+  }
+
+  .accordion summary::after {
+    background-color: ButtonText;
+    forced-color-adjust: none;
+  }
+}