actual-css 0.2.0 → 0.3.1

package/docs/pages/components/dialog.md

@@ -0,0 +1,367 @@
+# Dialog
+
+> Centered modal overlay for focused tasks, confirmations, or forms, built on the native `<dialog>` element.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.modal` | Component | Centered modal surface built on the native `<dialog>` element. |
+| `.scrollable` | Variant | Keeps the header and footer visible while the dialog body scrolls. |
+| `.dialog-confirmation` | Variant | Separates a confirmation message from its full-width action band. |
+| `.dialog-icon` | Component | Circular intent-aware icon well for confirmation messages. |
+| `.dialog-close` | Component | Icon-only close button anchored to the modal's top end, out of the content flow. |
+
+## Usage
+
+Modals use the platform-native `<dialog class="modal">` element with `commandfor` and `command` buttons.
+
+Use `command="show-modal"` to open a modal dialog.
+
+Add `aria-haspopup="dialog"` and `aria-controls="<id>"` to opening buttons so
+their semantics are present before either native or framework JavaScript runs.
+The command runtime is stateless and does not pre-scan triggers.
+
+Use `command="request-close"` for cancel-style buttons so close requests go
+through the dialog's cancel lifecycle.
+
+Use `closedby="any"` as the no-JavaScript light-dismiss path: the native dialog
+closes on backdrop click and Escape. Add `data-dialog-dismissible` so the
+optional runtime takes over backdrop click and closes with the dialog's
+transition; it rewrites `closedby="any"` to `closedby="closerequest"` so the
+native dialog and the runtime never double-handle. `data-dialog-dismissible`
+only gates backdrop click — Escape and explicit close requests always close,
+unless the application cancels the `actual:dialog-cancel` event.
+
+## Alert dialog
+
+Use this shape when the dialog interrupts the flow and asks for a decision. It
+has no close icon and no light dismiss; the footer actions are the way out.
+`closedby="none"` keeps Escape and backdrop clicks from closing it, so a
+critical confirmation cannot be dismissed accidentally. With the optional
+runtime, backdrop clicks give a small static feedback instead of closing.
+
+```html demo
+<button class="btn"
+        type="button"
+        commandfor="delete-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="delete-dialog">
+  Delete project
+</button>
+
+<dialog class="modal" id="delete-dialog" closedby="none">
+  <form method="dialog">
+    <header>
+      <h3>Delete project?</h3>
+      <p>This action cannot be undone.</p>
+    </header>
+
+    <div>
+      <p>The project, saved reports, and connected automations will be removed permanently.</p>
+    </div>
+
+    <footer>
+      <button class="btn outline" value="cancel">Cancel</button>
+
+      <button class="btn danger"
+              value="delete">
+        Delete
+      </button>
+    </footer>
+  </form>
+</dialog>
+```
+
+For a compact destructive confirmation with a leading status icon, compose
+`dialog-confirmation` with the media object. The icon well accepts the shared
+intent and emphasis classes; `dialog-icon danger soft` creates the tinted red
+circle while keeping the glyph centered. The footer becomes a separate action
+band without changing the semantics of the form or its buttons.
+
+```html demo
+<button class="btn danger"
+        type="button"
+        commandfor="deactivate-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="deactivate-dialog">
+  Deactivate account
+</button>
+
+<dialog class="modal dialog-confirmation"
+        id="deactivate-dialog"
+        closedby="none"
+        style="--modal-size: 40rem">
+  <form method="dialog">
+    <div class="media">
+      <span class="dialog-icon danger soft" aria-hidden="true">
+        <i class="ti ti-alert-triangle"></i>
+      </span>
+
+      <header>
+        <h3>Deactivate account</h3>
+        <p class="muted">Are you sure you want to deactivate your account? All of your data will be permanently removed. This action cannot be undone.</p>
+      </header>
+    </div>
+
+    <footer>
+      <button class="btn outline" value="cancel">Cancel</button>
+      <button class="btn danger" value="deactivate">Deactivate</button>
+    </footer>
+  </form>
+</dialog>
+```
+
+## Information modal
+
+Use this shape for contextual information or lightweight secondary content. It
+has no action button; the header close button dismisses the dialog.
+
+```html demo
+<button class="btn"
+        type="button"
+        commandfor="details-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="details-dialog">
+  View details
+</button>
+
+<dialog class="modal"
+        id="details-dialog"
+        closedby="any"
+        data-dialog-dismissible>
+  <button class="dialog-close"
+          type="button"
+          commandfor="details-dialog"
+          command="request-close"
+          aria-controls="details-dialog"
+          aria-label="Close dialog"></button>
+
+  <div class="stack">
+    <header>
+      <hgroup>
+        <h3>Release details</h3>
+        <p>Changes included in this version.</p>
+      </hgroup>
+    </header>
+
+    <div>
+      <p>The release improves dialog behavior, scroll handling, and progressive enhancement for modern browsers.</p>
+      <p>There are no decisions to make here; the content can simply be dismissed when finished.</p>
+    </div>
+  </div>
+</dialog>
+```
+
+## Scrollable modal
+
+Use `modal scrollable` when the header and footer should stay visible while the
+dialog body scrolls. Modal dialogs lock page scroll while a modal is open: the
+runtime writes `html.has-modal-open`, and the stylesheet applies `overflow:
+hidden` (and reserves the scrollbar gutter with `scrollbar-gutter: stable` when
+one was present).
+
+```html demo
+<button class="btn"
+        type="button"
+        commandfor="scroll-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="scroll-dialog">
+  Open scrollable modal
+</button>
+
+<dialog class="modal scrollable"
+        id="scroll-dialog"
+        closedby="any"
+        data-dialog-dismissible>
+  <form method="dialog">
+    <header>
+      <h3>Terms review</h3>
+      <p>Review the full text before continuing.</p>
+    </header>
+
+    <div class="stack">
+      <p>Actual CSS keeps long dialog content inside the dialog surface instead of letting it run past the viewport.</p>
+      <p>Section 1. The service stores project settings, interface preferences, and theme choices so teams can keep a consistent working environment.</p>
+      <p>Section 2. Administrators can invite users, remove inactive accounts, and review access periodically.</p>
+      <p>Section 3. Billing changes may affect future invoices. Existing invoices remain available from the account area.</p>
+      <p>Section 4. Export tools are provided for common formats. Large exports may take a few minutes to prepare.</p>
+      <p>Section 5. Support requests should include relevant browser, operating system, and account context.</p>
+      <p>Section 6. Experimental features can change or disappear before a stable release.</p>
+      <p>Section 7. Continued use confirms acceptance of the current terms.</p>
+    </div>
+
+    <footer>
+      <button class="btn outline" value="cancel">Cancel</button>
+
+      <button class="btn primary" value="accept">
+        Accept
+      </button>
+    </footer>
+  </form>
+</dialog>
+```
+
+## Overlays inside modals
+
+Flyouts and tooltips opened from inside a modal dialog are mounted inside the
+dialog so they stay in the same top-layer context.
+
+```html demo
+<button class="btn"
+        type="button"
+        commandfor="overlay-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="overlay-dialog">
+  Open modal overlays
+</button>
+
+<dialog class="modal"
+        id="overlay-dialog"
+        closedby="any"
+        data-dialog-dismissible>
+  <button class="dialog-close"
+          type="button"
+          commandfor="overlay-dialog"
+          command="request-close"
+          aria-controls="overlay-dialog"
+          aria-label="Close dialog"></button>
+
+  <div class="stack">
+    <header>
+      <hgroup>
+        <h3>Modal overlays</h3>
+        <p>Flyouts and tooltips remain above the dialog surface.</p>
+      </hgroup>
+    </header>
+
+    <div class="cluster">
+      <button class="btn"
+              type="button"
+              data-enhance="flyout"
+              aria-expanded="false"
+              aria-controls="dialog-actions-menu">
+        Actions
+      </button>
+
+      <button class="btn outline"
+              type="button"
+              data-tooltip="Tooltip inside a dialog">
+        Tooltip
+      </button>
+    </div>
+
+    <menu class="flyout menu" id="dialog-actions-menu" hidden>
+      <li><button class="menu-item" type="button">Archive</button></li>
+      <li><button class="menu-item" type="button">Duplicate</button></li>
+      <li><button class="menu-item" type="button">Share</button></li>
+    </menu>
+  </div>
+</dialog>
+```
+
+## JavaScript options
+
+Add options directly on the dialog element. Without JavaScript, modern browsers
+still use the native dialog behavior; the runtime adds declarative command
+handling, focus restoration, controlled light dismiss, and optional view
+transitions.
+
+Available options:
+
+* `data-dialog-dismissible` gates backdrop click only: the runtime takes over
+  light dismiss and closes the dialog (or rewrites `closedby="any"` to
+  `closedby="closerequest"` so the native dialog does not double-handle).
+  It never affects Escape or explicit close requests.
+* `data-dialog-modal="false"` opens with `show()` instead of `showModal()`.
+* `data-dialog-view-transition` enables a view transition that morphs the dialog to/from its trigger. Only active when the browser supports `document.startViewTransition` and the user allows motion.
+* `closedby` keeps its native meaning: `"any"` closes on backdrop click and
+  Escape, `"closerequest"` closes on Escape only, `"none"` disables both. The
+  runtime rewrites `closedby="any"` to `closedby="closerequest"` only when
+  `data-dialog-dismissible` opts it into light dismiss, and never overrides
+  `closedby="none"`. Use `closedby="none"` for critical dialogs that must be
+  closed by an explicit action.
+
+## Browser support
+
+Actual relies on the native `<dialog>` API in its supported JavaScript range
+(Safari 15.4+, Firefox 98+, Chromium 99+). No dialog polyfill or fallback shim
+is shipped.
+
+## Animation
+
+The base CSS gives supporting browsers small enter and exit transitions. Exit
+motion relies on `transition-behavior: allow-discrete` so the native dialog can
+remain in the top layer while `display` and `overlay` transition out. Browsers
+without that support keep native close behavior.
+
+The open dialog root intentionally ends at `transform: none`; fixed flyouts and
+tooltips mounted inside a modal dialog rely on viewport coordinates.
+
+### View transition
+
+Add `data-dialog-view-transition` to morph the dialog to/from its trigger using
+the View Transition API. The dialog appears to grow out of the trigger on open
+and shrink back into it on close, communicating the relationship between the
+two.
+
+The effect is progressive: it only runs when the browser supports
+`document.startViewTransition` and the user has not requested reduced motion.
+Otherwise the dialog simply opens and closes with the baseline dialog
+transition.
+
+```html demo
+<button class="btn"
+        type="button"
+        commandfor="vt-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="vt-dialog">
+  Open modal
+</button>
+
+<dialog class="modal"
+        id="vt-dialog"
+        data-dialog-view-transition
+        data-dialog-dismissible>
+  <form method="dialog">
+    <header>
+      <h3>Title</h3>
+      <p>This dialog morphs to and from the trigger button.</p>
+    </header>
+
+    <footer>
+      <button class="btn outline" value="cancel">Cancel</button>
+      <button class="btn primary" value="confirm">Confirm</button>
+    </footer>
+  </form>
+</dialog>
+```
+
+## Notes
+
+Prefer native dialog behavior whenever possible. The framework runtime should
+not replace the platform modal system; it should only make dialogs declarative,
+animation-friendly, and consistent across supported browsers.
+
+The close button is anchored to the dialog surface, not the content flow: it
+sits at the top `inline-end`, inside the panel. The button itself is out of
+flow, while the header reserves enough inline padding to keep its title clear.
+Keep the button a direct child of `dialog.modal` so the scrolling content
+(`> form` or `> .stack`) never competes with it.
+
+## CSS hooks
+
+- `--modal-size` — maximum dialog width.
+- `--dialog-viewport-gap` — distance kept between the dialog and the viewport edges.
+- `--dialog-icon-size` — diameter of the `.dialog-icon` circle.
+- `--dialog-icon-glyph-size` — size of the glyph centered inside `.dialog-icon`.
+- `--control-size` — inline and block size of the `.dialog-close` button. The
+  header reserves `calc(var(--control-size) + var(--space-30))` on its inline
+  end so the title never runs under the close.
+- `--dialog-close-icon-size` — size of the close glyph.

package/docs/pages/components/drawer.md

@@ -0,0 +1,113 @@
+# Drawer
+
+> Modal side-sheet that overlays the page for navigation or filters.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.drawer` | Component | Modal side-sheet built on the native `<dialog>` element. |
+| `.drawer-close` | Component | Icon-only close button that sits inside the drawer header. |
+
+## Usage
+
+- Use `dialog.drawer` for modal side-sheets that overlay the page.
+- Use `command="show-modal"` and `commandfor="<id>"` to open the drawer without JavaScript.
+- Use `form method="dialog"` for close buttons inside the drawer.
+- Use `data-dialog-dismissible` when backdrop click should close the drawer. It
+  only gates backdrop click: Escape and the close button always close.
+- Use `closedby="none"` when the drawer must not be dismissed by the user at all
+  (e.g. a form with unsaved changes): no backdrop close and no Escape close.
+- Use `[data-side="end"]` for a right-side drawer.
+- Permanent desktop sidebars belong in layout, not here.
+
+```html demo
+<button class="btn ghost"
+        type="button"
+        command="show-modal"
+        commandfor="main-drawer"
+        aria-haspopup="dialog"
+        aria-controls="main-drawer"
+        aria-label="Open navigation">
+  <i class="ti ti-menu-2" aria-hidden="true"></i>
+</button>
+
+<dialog class="drawer"
+        id="main-drawer"
+        aria-label="Main navigation"
+        closedby="any"
+        data-dialog-dismissible>
+  <header>
+    <strong>Menu</strong>
+
+    <form method="dialog">
+      <button class="drawer-close" type="submit" aria-label="Close navigation"></button>
+    </form>
+  </header>
+
+  <nav>
+    <ul class="nav-list stack">
+      <li><a href="#" aria-current="page">Home</a></li>
+      <li><a href="#">Users</a></li>
+      <li><a href="#">Settings</a></li>
+      <li><a href="#">Logout</a></li>
+    </ul>
+  </nav>
+</dialog>
+```
+
+## Non-dismissible drawer
+
+For drawers with unsaved settings or critical actions, use `closedby="none"` so
+the user cannot dismiss the drawer by accident: backdrop click shows a static
+indicator instead of closing, and Escape does nothing. Only the explicit footer
+actions and the close button can close the drawer.
+
+```html demo
+<button class="btn"
+        type="button"
+        command="show-modal"
+        commandfor="settings-drawer"
+        aria-haspopup="dialog"
+        aria-controls="settings-drawer">
+  Edit settings
+</button>
+
+<dialog class="drawer"
+        id="settings-drawer"
+        aria-label="Settings"
+        data-side="end"
+        closedby="none">
+  <form method="dialog">
+    <header>
+      <strong>Settings</strong>
+      <button class="drawer-close" type="submit" aria-label="Close settings"></button>
+    </header>
+
+    <div class="stack">
+      <p>Unsaved changes will be lost if you close without saving.</p>
+    </div>
+
+    <footer class="cluster" style="--cluster-justify: end">
+      <button class="btn" value="save">Save</button>
+    </footer>
+  </form>
+</dialog>
+```
+
+Backdrop click dismissal and Escape come from the native dialog element and
+follow its `closedby` value. Add `data-dialog-dismissible` when you want the
+optional runtime to take over backdrop click and close with the drawer's
+transition; the runtime rewrites `closedby="any"` to `closedby="closerequest"`
+so the two never double-handle. Without `data-dialog-dismissible`, a native
+`closedby="any"` dialog keeps its own light dismiss, and dialogs without
+light dismiss briefly flash instead of closing when the backdrop is clicked —
+useful for drawers that should not be dismissed accidentally.
+
+## CSS hooks
+
+- `--drawer-size` — panel width.
+- `--drawer-pad` — panel padding.
+- `--control-size` — size of the `.drawer-close` button. The drawer header
+  reserves `calc(var(--control-size) + var(--space-30))` on its inline end so
+  the title never runs under the close.

package/docs/pages/components/fab.md

@@ -0,0 +1,118 @@
+# Floating action button
+
+> **Optional** — import `actual-css/css/optional/fab` or `actual-css/css/optional/index`.
+
+FAB fixes a primary action near the viewport's block-end and inline-end edges.
+The existing button component owns its size, shape, intent, and interaction.
+
+```html
+<div class="fab">
+  <button class="btn circle primary lg icon-only" type="button" aria-label="Create">
+    <span aria-hidden="true">+</span>
+  </button>
+</div>
+```
+
+Use native `details` for a no-JavaScript speed dial. List actions in their
+visual top-to-bottom order so keyboard focus follows the same sequence.
+
+```html
+<details class="fab">
+  <summary
+    class="btn circle primary icon-only"
+    style="--btn-min-size: 3.5rem"
+    aria-label="Create"
+  >
+    <span aria-hidden="true">+</span>
+  </summary>
+
+  <div class="fab-actions">
+    <div class="fab-action">
+      <span class="fab-label">Document</span>
+      <button class="btn circle lg icon-only" type="button" aria-label="New document">…</button>
+    </div>
+    <div class="fab-action">
+      <span class="fab-label">Upload</span>
+      <button class="btn circle lg icon-only" type="button" aria-label="Upload file">…</button>
+    </div>
+    <div class="fab-action">
+      <span class="fab-label">Folder</span>
+      <button class="btn circle lg icon-only" type="button" aria-label="New folder">…</button>
+    </div>
+  </div>
+</details>
+```
+
+## Preview
+
+This documentation-only surface simulates a viewport by replacing the FAB's
+fixed positioning with absolute positioning. The card is background content,
+not the FAB's containing component. Production `.fab` remains viewport-fixed.
+
+```html demo
+<div class="docs-fab-preview">
+  <article class="card">
+    <h3>Documents</h3>
+    <p>Your recent documents will appear here.</p>
+  </article>
+
+  <details class="fab" open>
+    <summary
+      class="btn circle primary icon-only"
+      style="--btn-min-size: 3.5rem"
+      aria-label="Create"
+    >
+      <span aria-hidden="true">+</span>
+    </summary>
+
+    <div class="fab-actions">
+      <div class="fab-action">
+        <span class="fab-label">Document</span>
+        <button class="btn circle lg icon-only" type="button" aria-label="New document">
+          <i class="ti ti-file-plus" aria-hidden="true"></i>
+        </button>
+      </div>
+      <div class="fab-action">
+        <span class="fab-label">Upload</span>
+        <button class="btn circle lg icon-only" type="button" aria-label="Upload file">
+          <i class="ti ti-upload" aria-hidden="true"></i>
+        </button>
+      </div>
+      <div class="fab-action">
+        <span class="fab-label">Folder</span>
+        <button class="btn circle lg icon-only" type="button" aria-label="New folder">
+          <i class="ti ti-folder-plus" aria-hidden="true"></i>
+        </button>
+      </div>
+    </div>
+  </details>
+</div>
+```
+
+The native baseline manages click, keyboard activation, and the open state. It
+does not close automatically after an action, on outside click, or on Escape;
+add application behavior only when the product requires those policies.
+
+Each `.fab-action` keeps its `.fab-label` and secondary button on one compact
+line. The example uses the button's existing `.lg` density for 44px secondary
+actions and its `--btn-min-size` hook for a dominant 56px trigger. Size still
+belongs to Button rather than introducing FAB-specific size modifiers.
+When the summary contains one decorative icon, FAB rotates it by 45 degrees in
+the open state so a plus naturally becomes a close symbol.
+
+## Class reference
+
+| Class | Description |
+|---|---|
+| `.fab` | Fixed viewport placement; use `details` for a speed dial. |
+| `.fab-actions` | Collapsible vertical action list. |
+| `.fab-action` | One horizontal label-and-button unit. |
+| `.fab-label` | Compact floating label for an action. |
+
+## CSS hooks
+
+- `--fab-offset` — minimum viewport-edge offset.
+- `--fab-gap` — gap between actions and between the trigger and action list.
+
+FAB is hidden in print and uses `--z-menu`, leaving tooltips and status UI above
+it. Dialogs remain in the browser's top layer.

package/docs/pages/components/key.md

@@ -0,0 +1,33 @@
+# Key
+
+> Keyboard keys and shortcut tokens for app UI, command palettes, menus, and help text.
+
+- Use `<kbd class="key">` outside prose.
+- Plain `<kbd>` inside `.prose` gets the same visual treatment for authored content.
+- `.shortcut` is a documented composition, not a component class. Compose multiple `.key` elements with text or layout utilities.
+- Use short, familiar labels such as `Ctrl`, `Shift`, `Esc`, or `K`.
+
+## Basic usage
+
+```html demo
+<p>Press <kbd class="key">Esc</kbd> to close the panel.</p>
+
+<div class="cluster" aria-label="Keyboard shortcut Control K">
+  <kbd class="key">Ctrl</kbd>
+  <kbd class="key">K</kbd>
+</div>
+```
+
+## In menus
+
+In menus, keep the command label and shortcut in the same interactive item.
+
+```html demo
+<button type="button">
+  <span>Search</span>
+  <span class="cluster" aria-label="Keyboard shortcut Control K">
+    <kbd class="key">Ctrl</kbd>
+    <kbd class="key">K</kbd>
+  </span>
+</button>
+```

package/docs/pages/components/meter.md

@@ -0,0 +1,23 @@
+# Meter
+
+> Scalar measurement within a known range, not a progress indicator.
+
+- Use native `<meter class="meter">`.
+- Shares progress styling DNA.
+- Represents a scalar measurement within a known range, not task completion.
+- Use explicit bar height to avoid padding issues.
+
+```html demo
+<div class="stack">
+  <meter class="meter" value="0.8" min="0" max="1" low="0.3" high="0.7" optimum="1"></meter>
+  <meter class="meter" value="0.5" min="0" max="1" low="0.3" high="0.7" optimum="1"></meter>
+  <meter class="meter" value="0.2" min="0" max="1" low="0.3" high="0.7" optimum="1"></meter>
+</div>
+```
+
+The three standard meter zones (optimum, suboptimum, even-less-good) map to the
+shared `--success`, `--warning`, and `--danger` colors.
+
+## CSS hooks
+
+- `--bar-height` — bar thickness, shared with `.progress`.