actual-css 0.2.0 → 0.3.1

package/docs/pages/forms/labels.md

@@ -0,0 +1,42 @@
+# Labels
+
+> The field wrapper is `.field`. Choose between a wrapped `<label>` and a detached `for`/`id` pair based on the layout.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.field` | Composition | Field wrapper; canonical on `<label>` or `<div>`. |
+| `.field-label` | Composition | Label text, element-agnostic — works on `<span>`, a detached `<label for>`, or a `<legend>`. |
+| `.required-mark` | Composition | Visual required marker (`aria-hidden`) added inside a label. |
+
+Use a **wrapped label** for simple hand-authored forms. The whole label area becomes the click target, there is no `id` noise, and the markup is harder to break.
+
+```html demo
+<label class="field">
+  <span class="field-label">Full name</span>
+  <input class="input" type="text" name="name" autocomplete="name" />
+</label>
+```
+
+Use **`for`/`id`** when the layout needs the label and control in different grid areas, when the markup is generated by a backend or form library, or when a single label is paired with multiple controls. `.field-label` is element-agnostic, so it works on a detached `<label>`.
+
+```html demo
+<div class="field">
+  <label class="field-label" for="profile-email">
+    Email address <span class="required-mark" aria-hidden="true">*</span>
+  </label>
+  <input class="input"
+         id="profile-email"
+         name="email"
+         type="email"
+         autocomplete="email"
+         required
+         aria-describedby="profile-email-help" />
+  <span class="field-help" id="profile-email-help">
+    We only use this for account notifications.
+  </span>
+</div>
+```
+
+The mixed shape `<label for="x">…<input id="x"></label>` is allowed by the spec but rarely useful. Prefer either pure wrapped or pure `for`/`id`.

package/docs/pages/forms/otp.md

@@ -0,0 +1,50 @@
+# One-time code input
+
+> **Optional** — import `actual-css/css/optional/otp` or `actual-css/css/optional/index`.
+
+OTP presents one native input as separate visual cells. Keeping a single input
+preserves paste, selection, autofill, password-manager, and
+`autocomplete="one-time-code"` behavior without JavaScript.
+
+```html demo
+<label class="field">
+  <span class="field-label">Verification code</span>
+  <span class="otp">
+    <input
+      class="input"
+      type="text"
+      autocomplete="one-time-code"
+      inputmode="numeric"
+      maxlength="6"
+      pattern="[0-9]{6}"
+      required
+      aria-describedby="otp-help"
+    />
+    <span aria-hidden="true"></span>
+    <span aria-hidden="true"></span>
+    <span aria-hidden="true"></span>
+    <span aria-hidden="true"></span>
+    <span aria-hidden="true"></span>
+    <span aria-hidden="true"></span>
+  </span>
+  <span class="field-help" id="otp-help">Enter the six-digit code.</span>
+</label>
+```
+
+Add exactly one visual `span` per expected character. Their count must match
+`maxlength` and the input's validation pattern. `inputmode="numeric"` requests
+a numeric keyboard but does not enforce numeric input; validate the submitted
+value as usual.
+
+The component follows shared `.sm` and `.lg` density through `--control-size`.
+Use `aria-invalid="true"` for explicit invalid state, or place it in the
+standard `.needs-validation.was-validated` form flow.
+
+## CSS hooks
+
+- `--otp-cell-size` — width and height of every cell; follows `--control-size`.
+- `--otp-gap` — space between cells.
+- `--otp-font-size` — code glyph size; density does not change typography.
+
+Surface, border, focus, disabled, and danger colors come from the shared form
+and theme tokens.

package/docs/pages/forms/overview.md

@@ -0,0 +1,188 @@
+# Forms
+
+> Cohesive set of form elements that share focus styles, helpers, and validation patterns.
+
+- Form controls are styled with explicit classes, not by parent scope.
+- Control classes: `.input`, `.textarea`, `.select`, `.check`, `.radio`, `.switch`, `.range`, `.file`, `.color`.
+- Reusable layout classes: `.field`, `.field-label`, `.field-help`, `.field-error`, `.field-group`, `.choice`, `.form-actions`, `.form-actions.sticky`.
+- Floating labels available as optional CSS via `.floating-field` — standard `.field` labels remain the recommended default.
+- Proper focus style that preserves keyboard navigation.
+- `.field-group` and `.choice` provide layout without depending on parent scope.
+- Customizable select is progressive enhancement only — the native select remains the baseline.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.input` | Component | Text input; shares the text-control recipe with `.textarea` and `.select`. |
+| `.textarea` | Component | Multi-line text control. |
+| `.select` | Component | Dropdown — native baseline with a CSS chevron and an opt-in enhanced picker. |
+| `.check` | Component | Styled checkbox. |
+| `.radio` | Component | Styled radio button. |
+| `.switch` | Component | Toggle switch on a checkbox input with `role="switch"`. |
+| `.range` | Component | Native range slider with a theme-aware accent color. |
+| `.file` | Component | Native file input with a themed picker button. |
+| `.color` | Component | Native color picker in a control-sized box. |
+| `.field` | Composition | Field wrapper that works on `<label>` and `<div>`. |
+| `.field-label` | Composition | Label text; element-agnostic — `<span>`, detached `<label>`, or `<legend>`. |
+| `.field-help` | Composition | Supporting helper text under a control. |
+| `.field-error` | Composition | Inline error message shown while the field is invalid. |
+| `.field-group` | Composition | Grouped `<fieldset>` container with a tunable legend gutter. |
+| `.choice` | Composition | Choice-label layout wrapping a `.check`, `.radio`, or `.switch`. |
+| `.form-actions` | Composition | Class-only flex row that closes a form; works inside or outside the `<form>`. |
+
+## Example form
+
+A full form using the control classes, field wrappers, and form actions:
+
+```html demo
+<form novalidate>
+  <div class="stack">
+
+    <label class="field">
+      <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
+      <input class="input" type="text" autocomplete="name" required placeholder="Jane Doe" />
+    </label>
+
+    <label class="field">
+      <span class="field-label">Email address <span class="required-mark" aria-hidden="true">*</span></span>
+      <input class="input" type="email"
+             autocomplete="email"
+             required
+             aria-invalid="true"
+             aria-describedby="email-error"
+             value="jane@" />
+      <span class="field-error" id="email-error" role="alert">
+        Enter a valid email address
+      </span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Website</span>
+      <input class="input" type="url"
+             autocomplete="url"
+             aria-describedby="website-help"
+             placeholder="https://example.com" />
+      <span class="field-help" id="website-help">Your public portfolio or personal site</span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Bio</span>
+      <textarea class="textarea" aria-describedby="bio-help"
+                maxlength="200"
+                placeholder="Tell us a bit about yourself…"></textarea>
+      <span class="field-help" id="bio-help">Max 200 characters. Shown on your public profile.</span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Language</span>
+      <select class="select" autocomplete="language">
+        <option value="">Choose a language</option>
+        <optgroup label="Available languages">
+          <option value="en" selected>English</option>
+          <option value="fr">Français</option>
+          <option value="nl">Nederlands</option>
+        </optgroup>
+        <optgroup label="Not yet available">
+          <option value="de" disabled>Deutsch</option>
+        </optgroup>
+      </select>
+    </label>
+
+    <fieldset class="field-group">
+      <legend class="field-label">Availability</legend>
+      <div class="stack">
+        <label class="choice">
+          <input class="radio" type="radio" name="availability" value="available" checked />
+          <span>Available for work</span>
+        </label>
+        <label class="choice">
+          <input class="radio" type="radio" name="availability" value="open" />
+          <span>Open to opportunities</span>
+        </label>
+        <label class="choice">
+          <input class="radio" type="radio" name="availability" value="unavailable" />
+          <span>Not available</span>
+        </label>
+      </div>
+    </fieldset>
+
+    <label class="field">
+      <span class="field-label">Experience level</span>
+      <input class="range" type="range"
+             min="0"
+             max="10"
+             value="5"
+             aria-valuetext="5 years"
+             aria-describedby="range-help" />
+      <span class="field-help" id="range-help">Years of professional experience</span>
+    </label>
+
+    <label class="choice">
+      <input class="switch" type="checkbox" role="switch" checked />
+      <span>
+        <span class="field-label">Email notifications</span>
+        <span class="field-help">Receive updates about your account activity</span>
+      </span>
+    </label>
+
+    <label class="choice">
+      <input class="check" type="checkbox" />
+      <span>
+        I agree to the <a href="#">terms of service</a>
+        <span class="field-help">Required to create an account</span>
+      </span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Profile picture</span>
+      <input class="file" type="file" accept="image/*" aria-describedby="file-help" />
+      <span class="field-help" id="file-help">JPG, PNG or WebP — max 2 MB</span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Username</span>
+      <input class="input" type="text"
+             value="janedoe"
+             disabled
+             aria-describedby="username-help" />
+      <span class="field-help" id="username-help">Contact support to change your username</span>
+    </label>
+
+  </div>
+
+  <div class="form-actions">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary">Save changes</button>
+  </div>
+</form>
+```
+
+## Notes
+
+- `required` is enough on native inputs. `aria-required="true"` is redundant and not used in these examples.
+- `required` is the semantic source of truth. Add `<span class="required-mark" aria-hidden="true">*</span>` inside a label only when a visual required marker is wanted; the framework does not add one automatically.
+- `.field` is the canonical field wrapper. It works on `<label>` and `<div>`.
+- `.field-label` is element-agnostic. Use it on `<span>` inside a wrapped label, on `<label for="…">` in a detached layout, or on `<legend>` inside a fieldset.
+- `.field-group` styles a `<fieldset class="field-group">` as a grouped field container. Its legend gutter is tunable with `--fieldset-legend-padding-inline` (`var(--space-10)`).
+- Use native `<optgroup>` and `disabled` options in `.select` controls when applicable; the customizable picker preserves both as a progressive enhancement.
+- `.choice` is the choice-label API. Use `.check` or `.radio` on the nested control. The control goes first, the label group second, so multi-line labels align the control with the first line.
+- For a switch, use `class="switch"` and `role="switch"`.
+- Core range controls stay native and are enhanced by `accent-color`. An optional richer range skin may come later if real projects need it.
+- `.form-actions` carries a default top margin. Override it with `--form-actions-margin-block-start`, `--form-actions-align`, or `--form-actions-justify`. It is class-only and may live inside or outside `<form>`. See Detached Actions below.
+- `.join` visually joins adjacent controls into a single unit. Use `.join-addon` for static prefix/suffix content. The container still carries `role="group"` for accessibility.
+
+## Optional automatic required marks
+
+If a form consistently marks every required field, opt into automatic visual markers in application CSS. Scope the rule to that form so other forms stay explicit, and retain a per-field opt-out:
+
+```css
+form[data-required-marks="auto"]
+  .field:not([data-required-mark="none"]):has(:required)
+  > .field-label::after {
+  content: " *";
+  color: var(--danger);
+}
+```
+
+`required` remains the accessible source of truth; this recipe adds only a visual cue. Use `data-required-mark="none"` on a `.field` when a required control should not receive the generated marker.

package/docs/pages/forms/password.md

@@ -0,0 +1,40 @@
+# Password Toggle
+
+> A password field reveals its value through a linked button. The markup is a
+> plain command invoker; the behavior ships with the JS runtime
+> (`actual-css/js` or `actual-css/js/password`).
+
+Point a `button` at the input with `commandfor` and
+`command="--password-toggle"`. Use `.join` when the button should sit attached
+to the field.
+
+```html demo
+<div class="field">
+  <label class="field-label" for="pw">Password</label>
+  <div class="join">
+    <input class="input" type="password" id="pw" name="password"
+           autocomplete="current-password" required />
+    <button class="btn outline" type="button" commandfor="pw"
+            command="--password-toggle" aria-controls="pw"
+            aria-label="Show password" aria-pressed="false"><i class="ti ti-eye" aria-hidden="true"></i></button>
+  </div>
+</div>
+```
+
+Start with `aria-pressed="false"`; this makes the toggle semantics available
+before JavaScript runs. The runtime flips the input between `type="password"`
+and `type="text"` and mirrors the state on every linked trigger, which
+`.btn[aria-pressed="true"]` already styles. Keep the trigger label stable
+("Show password") — `aria-pressed` announces the state, so a label that flips
+to "Hide" reads as a double negation to screen readers. Style an icon swap off
+the attribute instead:
+
+```css
+[command="--password-toggle"][aria-pressed="true"] .icon-show { display: none; }
+[command="--password-toggle"]:not([aria-pressed="true"]) .icon-hide { display: none; }
+```
+
+A revealed value does not survive navigation: a non-canceled form submit and
+`pagehide` both revert the input to hidden, so back navigation cannot land on
+a readable password. A canceled submit (failed validation, ajax) keeps the
+value revealed.

package/docs/pages/forms/range.md

@@ -0,0 +1,17 @@
+# Range
+
+> Native range inputs with theme-aware accent color.
+
+Core: native range, enhanced by `accent-color`. Optional richer skin may come later.
+
+```html demo
+<label class="field">
+  <span class="field-label">Volume</span>
+  <input class="range" type="range" min="0" max="100" value="50" />
+</label>
+```
+
+## CSS hooks
+
+- `--range-thumb-size` — thumb diameter.
+- `--range-track-height` — track thickness.

package/docs/pages/forms/states-and-sizes.md

@@ -0,0 +1,321 @@
+# States And Sizes
+
+> Read-only, disabled, and shared size modifiers for form controls.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.sm` | Modifier | Compact control height and spacing rhythm; sets `--control-size` to `--control-size-sm`. |
+| `.lg` | Modifier | Large control height and spacing rhythm; sets `--control-size` to `--control-size-lg`. |
+
+Use `readonly` for text-like values that can still be focused, selected, and submitted. Use `disabled` for unavailable controls that should not receive focus or submit a value.
+
+The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, selects, textareas, buttons, and switches. Put the modifier on the control itself, or on a `.field` wrapper when the whole field should share that size.
+
+```html demo
+<form novalidate>
+  <fieldset class="field-group">
+    <legend class="field-label">Text control states</legend>
+    <div class="stack container-query">
+      <div class="grid-3 items-start">
+        <label class="field">
+          <span class="field-label">Editable</span>
+          <input class="input" type="text" value="Ocean Beach Clinic" />
+        </label>
+
+        <label class="field">
+          <span class="field-label">Read-only</span>
+          <input class="input" type="text" value="INV-2048" readonly />
+          <span class="field-help">Focusable and submitted with the form.</span>
+        </label>
+
+        <label class="field">
+          <span class="field-label">Disabled</span>
+          <input class="input" type="text" value="Locked by billing" disabled />
+          <span class="field-help">Unavailable and not submitted.</span>
+        </label>
+      </div>
+
+      <div class="grid-3 items-start">
+        <label class="field">
+          <span class="field-label">Editable notes</span>
+          <textarea class="textarea">Patient asked for an invoice copy.</textarea>
+        </label>
+
+        <label class="field">
+          <span class="field-label">Read-only notes</span>
+          <textarea class="textarea" readonly>Insurance details imported from the patient record.</textarea>
+        </label>
+
+        <label class="field">
+          <span class="field-label">Disabled notes</span>
+          <textarea class="textarea" disabled>Notes are disabled until the transaction is selected.</textarea>
+        </label>
+      </div>
+    </div>
+  </fieldset>
+
+  <fieldset class="field-group">
+    <legend class="field-label">Choice and select states</legend>
+    <div class="stack container-query">
+      <div class="grid-3 items-start">
+        <label class="field">
+          <span class="field-label">Editable select</span>
+          <select class="select">
+            <option>Card</option>
+            <option>Bank transfer</option>
+            <option>Cash</option>
+          </select>
+        </label>
+
+        <label class="field">
+          <span class="field-label">Invalid select</span>
+          <select class="select" aria-invalid="true">
+            <option>Choose a method</option>
+            <option>Card</option>
+            <option>Bank transfer</option>
+          </select>
+          <span class="field-error">Choose a payment method.</span>
+        </label>
+
+        <label class="field">
+          <span class="field-label">Disabled select</span>
+          <select class="select" disabled>
+            <option>Card</option>
+            <option>Bank transfer</option>
+            <option>Cash</option>
+          </select>
+        </label>
+      </div>
+
+      <div class="grid-5 items-start">
+        <label class="choice">
+          <input class="check" type="checkbox" />
+          <span>
+            <span class="field-label">Unchecked checkbox</span>
+            <span class="field-help">Available and not selected.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="check" type="checkbox" checked />
+          <span>
+            <span class="field-label">Checked checkbox</span>
+            <span class="field-help">Available and selected.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="check" type="checkbox" checked disabled />
+          <span>
+            <span class="field-label">Disabled checked</span>
+            <span class="field-help">Selected but unavailable.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="check" type="checkbox" disabled />
+          <span>
+            <span class="field-label">Disabled unchecked</span>
+            <span class="field-help">Unavailable and not selected.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="check" type="checkbox" id="indet-demo" />
+          <span>
+            <span class="field-label">Indeterminate checkbox</span>
+            <span class="field-help">Partially selected — set via <code>element.indeterminate = true</code>. Try it: <button class="btn text sm" type="button" onclick="document.getElementById('indet-demo').indeterminate = !document.getElementById('indet-demo').indeterminate">toggle</button></span>
+          </span>
+        </label>
+      </div>
+
+      <div class="grid-4 items-start">
+        <label class="choice">
+          <input class="radio" type="radio" name="demo-radio-state" />
+          <span>
+            <span class="field-label">Unselected radio</span>
+            <span class="field-help">Available and not selected.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="radio" type="radio" name="demo-radio-state" checked />
+          <span>
+            <span class="field-label">Selected radio</span>
+            <span class="field-help">Available and selected.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="radio" type="radio" name="demo-radio-disabled" checked disabled />
+          <span>
+            <span class="field-label">Disabled selected</span>
+            <span class="field-help">Selected but unavailable.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="radio" type="radio" name="demo-radio-disabled" disabled />
+          <span>
+            <span class="field-label">Disabled unselected</span>
+            <span class="field-help">Unavailable and not selected.</span>
+          </span>
+        </label>
+      </div>
+
+      <div class="grid-4 items-start">
+        <label class="choice">
+          <input class="switch" type="checkbox" role="switch" />
+          <span>
+            <span class="field-label">Switch off</span>
+            <span class="field-help">Available and inactive.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="switch" type="checkbox" role="switch" checked />
+          <span>
+            <span class="field-label">Switch on</span>
+            <span class="field-help">Available and enabled.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="switch" type="checkbox" role="switch" checked disabled />
+          <span>
+            <span class="field-label">Disabled on</span>
+            <span class="field-help">On but unavailable.</span>
+          </span>
+        </label>
+
+        <label class="choice">
+          <input class="switch" type="checkbox" role="switch" disabled />
+          <span>
+            <span class="field-label">Disabled off</span>
+            <span class="field-help">Off and unavailable.</span>
+          </span>
+        </label>
+      </div>
+    </div>
+  </fieldset>
+
+  <fieldset class="field-group">
+    <legend class="field-label">Control sizes</legend>
+    <div class="stack container-query">
+      <div class="grid-3 items-start">
+        <label class="field sm">
+          <span class="field-label">Small field</span>
+          <input class="input" type="text" value="sm" />
+        </label>
+
+        <label class="field">
+          <span class="field-label">Default field</span>
+          <input class="input" type="text" value="default" />
+        </label>
+
+        <label class="field lg">
+          <span class="field-label">Large field</span>
+          <input class="input" type="text" value="lg" />
+        </label>
+      </div>
+
+      <div class="grid-3 items-start">
+        <label class="field sm">
+          <span class="field-label">Small select</span>
+          <select class="select">
+            <option>Compact</option>
+          </select>
+        </label>
+
+        <label class="field">
+          <span class="field-label">Default select</span>
+          <select class="select">
+            <option>Default</option>
+          </select>
+        </label>
+
+        <label class="field lg">
+          <span class="field-label">Large select</span>
+          <select class="select">
+            <option>Comfortable</option>
+          </select>
+        </label>
+      </div>
+
+      <div class="grid-3 items-start">
+        <label class="field sm">
+          <span class="field-label">Small textarea</span>
+          <textarea class="textarea" rows="2">Short note</textarea>
+        </label>
+
+        <label class="field">
+          <span class="field-label">Default textarea</span>
+          <textarea class="textarea" rows="2">Default note</textarea>
+        </label>
+
+        <label class="field lg">
+          <span class="field-label">Large textarea</span>
+          <textarea class="textarea" rows="2">Comfortable note</textarea>
+        </label>
+      </div>
+
+      <div class="grid-3 items-start">
+        <button class="btn outline sm" type="button">Small</button>
+        <button class="btn outline" type="button">Default</button>
+        <button class="btn outline lg" type="button">Large</button>
+      </div>
+
+      <div class="grid-4 items-start">
+        <label class="choice sm">
+          <input class="check" type="checkbox" checked />
+          <span>Small checkbox</span>
+        </label>
+        <label class="choice">
+          <input class="check" type="checkbox" checked />
+          <span>Default checkbox</span>
+        </label>
+        <label class="choice lg">
+          <input class="check" type="checkbox" checked />
+          <span>Large checkbox</span>
+        </label>
+        <label class="choice">
+          <input class="check" type="checkbox" id="indet-size" />
+          <span>Indeterminate <button class="btn text sm" type="button" onclick="document.getElementById('indet-size').indeterminate = !document.getElementById('indet-size').indeterminate">toggle</button></span>
+        </label>
+      </div>
+
+      <div class="grid-3 items-start">
+        <label class="choice sm">
+          <input class="radio" type="radio" name="demo-radio-size" checked />
+          <span>Small radio</span>
+        </label>
+        <label class="choice">
+          <input class="radio" type="radio" name="demo-radio-size" />
+          <span>Default radio</span>
+        </label>
+        <label class="choice lg">
+          <input class="radio" type="radio" name="demo-radio-size" />
+          <span>Large radio</span>
+        </label>
+      </div>
+
+      <div class="grid-3 items-start">
+        <label class="choice sm">
+          <input class="switch" type="checkbox" role="switch" checked />
+          <span>Small switch</span>
+        </label>
+        <label class="choice">
+          <input class="switch" type="checkbox" role="switch" checked />
+          <span>Default switch</span>
+        </label>
+        <label class="choice lg">
+          <input class="switch" type="checkbox" role="switch" checked />
+          <span>Large switch</span>
+        </label>
+      </div>
+    </div>
+  </fieldset>
+</form>
+```