@cahyo-dimas/freeday 3.4.0 → 3.6.0

package/dist/freeday.js

@@ -1924,6 +1924,167 @@
   window.FreedayChip = { initGroup: initGroup, initRemove: initRemove, initAll: initAll };
 })();
 
+/* Freeday, confirm API (optional, zero-dependency). Note #060.
+ * Freeday.confirm({ title, message, details, acceptText, rejectText, tone }) opens a .fdy-modal
+ * and resolves a Promise<boolean>: true on accept; false on reject, Escape or a backdrop click.
+ *   details:  string[] shown as a list under the message, for a confirm that has to NAME its
+ *             findings ("these three fields will be refused") instead of folding them into one
+ *             long sentence
+ *   tone:     'primary' (default) | 'danger', the accept button's variant
+ *
+ * One dialog, one answer: every way out resolves the same Promise, and a Promise settles once, so
+ * a caller never hears "no" after "yes" (a framework dialog that reports reject and then hide, or
+ * hide after accept, does exactly that). Text is set with textContent, never parsed as HTML.
+ * Focus starts on the reject button: Enter on a dialog that just opened must not delete anything.
+ * The dialog is removed when it closes; the native <dialog> returns focus to where it was.
+ * Buttons carry data-fdy-confirm-accept / data-fdy-confirm-reject, stable hooks for tests, because
+ * an accept labelled "Delete" collides by accessible name with every row's own Delete button.
+ */
+(function () {
+  'use strict';
+
+  /* User-facing strings, English by default. Per call, acceptText / rejectText override them; a
+   * label that names the action ("Delete order") is better than either default. */
+  var TEXT = {
+    accept: 'Confirm',
+    reject: 'Cancel'
+  };
+
+  var seq = 0;
+
+  function el(tag, className, text) {
+    var node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text != null) node.textContent = text;
+    return node;
+  }
+
+  function confirm(opts) {
+    opts = opts || {};
+    return new Promise(function (resolve) {
+      seq += 1;
+      var titleId = 'fdy-confirm-title-' + seq;
+      var dialog = el('dialog', 'fdy-modal fdy-modal--sm');
+      dialog.setAttribute('aria-labelledby', titleId);
+      dialog.setAttribute('data-fdy-confirm', '');
+
+      var header = el('header', 'fdy-modal__header');
+      var title = el('h2', 'fdy-modal__title', opts.title || '');
+      title.id = titleId;
+      header.appendChild(title);
+
+      var body = el('div', 'fdy-modal__body');
+      if (opts.message) {
+        var message = el('p', null, opts.message);
+        message.id = titleId + '-desc';
+        dialog.setAttribute('aria-describedby', message.id);
+        body.appendChild(message);
+      }
+      var details = Array.isArray(opts.details) ? opts.details : [];
+      if (details.length > 0) {
+        var list = el('ul');
+        details.forEach(function (line) { list.appendChild(el('li', null, line)); });
+        body.appendChild(list);
+      }
+
+      var footer = el('footer', 'fdy-modal__footer');
+      var reject = el('button', 'fdy-btn fdy-btn--ghost', opts.rejectText || TEXT.reject);
+      reject.type = 'button';
+      reject.setAttribute('data-fdy-confirm-reject', '');
+      var accept = el('button', opts.tone === 'danger' ? 'fdy-btn fdy-btn--danger' : 'fdy-btn', opts.acceptText || TEXT.accept);
+      accept.type = 'button';
+      accept.setAttribute('data-fdy-confirm-accept', '');
+      footer.appendChild(reject);
+      footer.appendChild(accept);
+
+      dialog.appendChild(header);
+      dialog.appendChild(body);
+      dialog.appendChild(footer);
+
+      function settle(answer) {
+        resolve(answer);
+        if (dialog.open) dialog.close();
+      }
+
+      accept.addEventListener('click', function () { settle(true); });
+      reject.addEventListener('click', function () { settle(false); });
+      // Escape fires `cancel` then `close`; a backdrop click lands on the <dialog> itself, since its
+      // children fill the box edge to edge. Both mean "no".
+      dialog.addEventListener('close', function () {
+        settle(false);
+        if (dialog.parentNode) dialog.parentNode.removeChild(dialog);
+      });
+      dialog.addEventListener('click', function (e) { if (e.target === dialog) settle(false); });
+
+      document.body.appendChild(dialog);
+      dialog.showModal();
+      reject.focus();
+    });
+  }
+
+  window.Freeday = window.Freeday || {};
+  window.Freeday.confirm = confirm;
+})();
+
+/* Freeday, copy-to-clipboard enhancer (optional, zero-dependency). Note #062.
+ * A button carrying data-fdy-copy="<value>" copies that value and says so with a toast. For
+ * reference values a reader takes elsewhere: an external document number, an event ID.
+ *
+ *   <dd><span class="fdy-mono">INV-2026-00042</span>
+ *     <button type="button" class="fdy-btn fdy-btn--ghost fdy-btn--icon fdy-btn--sm"
+ *             data-fdy-copy="INV-2026-00042" aria-label="Copy invoice number">…svg…</button></dd>
+ *
+ * The value is the attribute, not a lookup of some neighbour's text: a framework writes it from
+ * the same variable as the visible text, and a row of a table needs no ids to find its own cell.
+ * One delegated listener on the document, so buttons rendered later need no hydration.
+ *
+ * The Clipboard API exists only in a secure context. Over plain http writeText is missing, and a
+ * copy that silently did nothing is the failure this refuses: the reader is told to copy by hand.
+ * Emits bubbling "fdy-copy" {value, ok} on the button. A click inside a clickable table row still
+ * reaches the row's own handler; stop it there if the row should not open. Exposes window.FreedayCopy.
+ */
+(function () {
+  'use strict';
+
+  /* User-facing strings, English by default and overridable per button with data-fdy-text-<key>,
+   * like every other enhancer's. */
+  var TEXT = {
+    copied: 'Copied.',
+    failed: 'Could not copy. Select the text and copy it manually.'
+  };
+  function textOf(el, key) {
+    var custom = el.getAttribute('data-fdy-text-' + key);
+    return custom != null && custom !== '' ? custom : TEXT[key];
+  }
+
+  function report(btn, value, ok) {
+    if (window.Freeday && typeof window.Freeday.toast === 'function') {
+      window.Freeday.toast(ok
+        ? { variant: 'success', message: textOf(btn, 'copied'), key: 'fdy-copy' }
+        : { variant: 'danger', message: textOf(btn, 'failed'), key: 'fdy-copy', timeout: 0 });
+    }
+    btn.dispatchEvent(new CustomEvent('fdy-copy', { bubbles: true, detail: { value: value, ok: ok } }));
+  }
+
+  function copy(btn) {
+    var value = btn.getAttribute('data-fdy-copy') || '';
+    if (value === '') return;
+    var clip = navigator.clipboard;
+    if (!clip || typeof clip.writeText !== 'function') { report(btn, value, false); return; }
+    clip.writeText(value).then(
+      function () { report(btn, value, true); },
+      function () { report(btn, value, false); }
+    );
+  }
+
+  document.addEventListener('click', function (e) {
+    var btn = e.target.closest && e.target.closest('[data-fdy-copy]');
+    if (btn && !btn.disabled) copy(btn);
+  });
+
+  window.FreedayCopy = { copy: copy };
+})();
+
 /* Freeday, date picker enhancer (optional, zero-dependency).
  * Builds an input-styled trigger + calendar popover from an empty wrapper.
  * Locale comes from <html lang> (via Intl), month/weekday/value formatting is not hardcoded.
@@ -2529,15 +2690,30 @@
       fromApi.setRange(f, t);     // start stays free, picking a later start clears the end below
       toApi.setRange(f, t);
     }
+    /* An end the new start overtook is cleared, and the clear is ANNOUNCED like a pick: a binding
+     * that only hears picks (Blazor's To) otherwise keeps the end the range no longer has. */
+    function clearEnd(el, api) {
+      api.clear();
+      el.dispatchEvent(new CustomEvent('fdy-datepicker-change', { bubbles: true, detail: { value: '' } }));
+    }
+    /* "Settled" = both ends chosen, or both empty: the only states worth a reload (#063). A pick of
+     * the first end, or a start that overtook the end, is half a range. */
+    function settle() {
+      var f = fromApi.getValue(), t = toApi.getValue();
+      if ((f === '') !== (t === '')) return;
+      root.dispatchEvent(new CustomEvent('fdy-daterange-settled', { bubbles: true, detail: { from: f, to: t } }));
+    }
     fromEl.addEventListener('fdy-datepicker-change', function () {
       var f = fromApi.getValue(), t = toApi.getValue();
-      if (f && t && t < f) toApi.clear();
+      if (f && t && t < f) clearEnd(toEl, toApi);
       sync();
+      settle();
     });
     toEl.addEventListener('fdy-datepicker-change', function () {
       var f = fromApi.getValue(), t = toApi.getValue();
-      if (f && t && t < f) fromApi.clear();
+      if (f && t && t < f) clearEnd(fromEl, fromApi);
       sync();
+      settle();
     });
     sync();
   }
@@ -2720,7 +2896,7 @@
  *   data-fdy-msg-min | -max | -step | -mismatch, then generic data-fdy-msg.
  * Cross-field match (e.g. confirm password): data-fdy-match="#otherId".
  *
- * Timing: validates on submit (blocks + focuses the first invalid control); after
+ * Timing: validates on submit (blocks, reveals + focuses the first invalid control); after
  * the first submit attempt each field re-validates on input/blur so errors clear
  * live. Add data-fdy-eager to validate on blur from the start.
  *
@@ -2833,6 +3009,34 @@
     }
   }
 
+  /* focus() on a control that is not rendered does nothing and reports nothing: the field turns red
+   * where nobody can see it, and the submit reads as a dead button (#059). So whatever hides the
+   * control is undone first, each through that component's own control, so its state agrees with
+   * what is shown:
+   *   closed <details>        opened (accordion, tree, nav group)
+   *   hidden [role=tabpanel]  its tab is clicked; freeday-tabs selects on click
+   *   hidden .fdy-step-panel  its step button is clicked. A step not yet reached has a disabled
+   *                           button, so this only ever goes BACK and never skips a step guard.
+   * Anything else that hides it belongs to the app, and is left alone. */
+  function reveal(el) {
+    for (var node = el.parentElement; node; node = node.parentElement) {
+      if (node.localName === 'details' && !node.open) {
+        node.open = true;
+      } else if (node.hidden && node.getAttribute('role') === 'tabpanel' && node.id) {
+        var tab = Array.prototype.filter.call(document.querySelectorAll('[role="tab"]'), function (t) {
+          return t.getAttribute('aria-controls') === node.id;
+        })[0];
+        if (tab) tab.click();
+      } else if (node.hidden && node.classList.contains('fdy-step-panel')) {
+        var stepper = node.closest('[data-fdy-stepper]');
+        if (!stepper) continue;
+        var index = Array.prototype.indexOf.call(stepper.querySelectorAll('.fdy-step-panel'), node);
+        var btn = stepper.querySelectorAll('.fdy-step__btn')[index];
+        if (btn && !btn.disabled) btn.click();
+      }
+    }
+  }
+
   function initForm(form) {
     if (form.dataset.fdyFormReady === '1') return;
     form.dataset.fdyFormReady = '1';
@@ -2867,6 +3071,7 @@
       });
       if (invalid.length) {
         e.preventDefault();
+        reveal(invalid[0]);
         invalid[0].focus();
         form.dispatchEvent(new CustomEvent('fdy-form-invalid', { bubbles: true, detail: { invalid: invalid } }));
       } else {
@@ -3378,6 +3583,84 @@
   window.FreedayRating = { init: initRating, initAll: initAll };
 })();
 
+/* Freeday, list search enhancer (optional, zero-dependency). Note #061.
+ * Turns an .fdy-input-group into a search box that searches while the reader pauses, at once on
+ * Enter, and has a clear button. All three paths end in ONE bubbling event on the group,
+ * "fdy-search" {term}, so an app listens once instead of wiring keyup, a timer and a click.
+ *
+ * Markup (the group, not a new block; the clear button is yours, so is its aria-label):
+ *   <div class="fdy-input-group" data-fdy-search [data-fdy-search-delay="400"]>
+ *     <span class="fdy-input-group__addon fdy-input-group__addon--icon">…svg…</span>
+ *     <input class="fdy-input" type="text" aria-label="Search orders">
+ *     <button type="button" class="fdy-input-group__btn" data-fdy-search-clear aria-label="Clear search">×</button>
+ *   </div>
+ *
+ * type="text", not "search": WebKit's own × is unthemed and fires no Enter, which is what made
+ * clearing a field leave the old rows on screen until somebody pressed Enter on an empty box.
+ * The clear button is hidden while the box is empty. Clearing writes through the native value
+ * setter and fires a native `input`, so v-model, a React onChange and Blazor @bind all follow.
+ * `term` is trimmed; "" means "show everything again". Exposes window.FreedaySearch.
+ */
+(function () {
+  'use strict';
+
+  var DEFAULT_DELAY = 400;
+  var nativeValue = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set;
+
+  function initSearch(root) {
+    if (root.dataset.fdySearchReady === '1') return;
+    var input = root.querySelector('input');
+    if (!input) return;
+    root.dataset.fdySearchReady = '1';
+    var clearBtn = root.querySelector('[data-fdy-search-clear]');
+    var delayAttr = parseInt(root.getAttribute('data-fdy-search-delay'), 10);
+    var delay = isNaN(delayAttr) ? DEFAULT_DELAY : delayAttr;
+    var timer = null;
+
+    function cancel() { if (timer !== null) { clearTimeout(timer); timer = null; } }
+    function emit() {
+      cancel();
+      root.dispatchEvent(new CustomEvent('fdy-search', { bubbles: true, detail: { term: input.value.trim() } }));
+    }
+    function syncClear() { if (clearBtn) clearBtn.hidden = input.value === ''; }
+
+    input.addEventListener('input', function () {
+      syncClear();
+      cancel();
+      timer = setTimeout(emit, delay);
+    });
+    input.addEventListener('keydown', function (e) {
+      if (e.key !== 'Enter') return;
+      e.preventDefault(); // inside a <form>, Enter would submit it as well
+      emit();
+    });
+    if (clearBtn) {
+      clearBtn.addEventListener('click', function () {
+        nativeValue.call(input, '');
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        emit(); // at once, and it cancels the pause the input event just started
+        input.focus();
+      });
+    }
+    syncClear();
+  }
+
+  function initAll(context) {
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-search]')) initSearch(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-search]'), initSearch);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { initAll(); });
+  } else {
+    initAll();
+  }
+
+  window.FreedaySearch = { init: initSearch, initAll: initAll };
+})();
+
 /* Freeday, combobox enhancer (optional, zero-dependency).
  * Implements the WAI-ARIA APG "select-only combobox" pattern for every
  * [data-fdy-combo] on the page. Progressive enhancement: the markup is the

package/dist/freeday.media.css

@@ -0,0 +1,27 @@
+/* Freeday breakpoints as @custom-media. GENERATED by tokens/build.mjs. Do not edit by hand.
+ *
+ * Requires postcss-custom-media (or any PostCSS setup that includes postcss-preset-env); without it
+ * a browser ignores the at-rules and every @media (--fdy-*) in your CSS never matches. Import it
+ * ONCE, above the rules that use it:
+ *
+ *   @import '@cahyo-dimas/freeday/media';
+ *   @media (--fdy-below-sm) { .page-header { display: block } }
+ *
+ * This file carries no rules of its own, so importing it costs nothing at runtime; it is not part
+ * of freeday.css or freeday.bundle.css. */
+@custom-media --fdy-below-sm (max-width: 599.98px);
+@custom-media --fdy-from-sm (min-width: 600px);
+@custom-media --fdy-below-md (max-width: 959.98px);
+@custom-media --fdy-from-md (min-width: 960px);
+@custom-media --fdy-below-lg (max-width: 1279.98px);
+@custom-media --fdy-from-lg (min-width: 1280px);
+@custom-media --fdy-below-xl (max-width: 1919.98px);
+@custom-media --fdy-from-xl (min-width: 1920px);
+
+/* NOT ramp steps. Each mirrors one hard-wired rule in the kit, and a rule that must fire with it
+ * uses THIS condition, never the nearest ramp step: aligning shell-dependent code to --fdy-below-md
+ * leaves 721–959px broken, and aligning a filter-bar rule to --fdy-below-sm leaves 600–640px
+ * half-stacked. See tokens/breakpoints.mjs for what each one governs. */
+@custom-media --fdy-nav-drawer (max-width: 720px);
+@custom-media --fdy-nav-static (min-width: 721px);
+@custom-media --fdy-filterbar-stacked (max-width: 640px);

package/docs/agent-onboarding.md

@@ -96,6 +96,7 @@ Blazor). Then verify the agent can actually read those files. An agent that can'
 | `docs/agent-onboarding.md` | This file. |
 | `CHANGELOG.md` | **What changed between the version this project had and the one it has now.** Read it after every upgrade; each entry says what broke, what is new, and why. |
 | `dist/` | Built CSS + enhancers. **`freeday.bundle.css` = tokens + components** (what `@cahyo-dimas/freeday/css` resolves to); `freeday.css` is components **only**, `freeday.tokens.css` tokens only, so linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
+| `dist/freeday.media.css` | The breakpoints as `@custom-media` (`@cahyo-dimas/freeday/media`), so a responsive rule in your CSS states the kit's condition instead of a retyped literal. Needs PostCSS; carries no rules, and is **not** in the bundle. |
 | `src/components/*.css` | The authoritative source for every class, when a doc is ambiguous. |
 | `tokens/tokens.json` | Every token in W3C DTCG format, machine-readable. |
 | `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 11 components each (plus `FdyTableFooter`). |
@@ -136,8 +137,17 @@ Recent additions most likely to replace something an app hand-rolled (all detail
 | `size="cfl"` on `FdyModal` | writing `.fdy-modal--cfl` by hand to reach the 46rem width |
 | `dialogOnly` + `open()` on `FdyCfl` | a hand-rolled picker, because the trigger is a chip or a table cell and not a 22rem field |
 | `.fdy-field--full` | `max-width: none` on the form container, once per form, because the fields are a flex column and not a `.fdy-form-grid` |
+| `.fdy-page__columns` | a hand-rolled 8/4 or 3/6/3 grid per screen, with a summary rail that falls under every section on a phone |
+| `.fdy-dl--grid` | a facts grid whose columns follow the window, so a side rail gets two 110px columns |
+| `.fdy-card__head` | a card title row with its "View all" link at the bottom, moving every time the content grows |
+| `settled` on `FdyDateRange` | reloading a list on each end of a range, the first time with the start alone |
+| `{ filtered, clearFilters }` on `FdyTable`'s empty state | one "No data" sentence for both "nothing matches" and "nothing yet" |
+| `Freeday.confirm()` | a confirm dialog assembled from a modal, two buttons and a flag so it answers only once |
+| `[data-fdy-search]` | a search box that only searches on Enter, so emptying it leaves the old rows on screen |
+| `[data-fdy-copy]` | selecting an ID by hand, or a copy button that silently does nothing over http |
 | `.fdy-nav--flat` | undoing the caret, the pointer cursor and the group divider yourself, on a sidebar whose group labels never collapse |
 | `--fdy-app-sidebar-w` | overriding `width` on `.fdy-app__sidebar`, which is also the rule that animates the collapse |
+| `@media (--fdy-filterbar-stacked)` / `(--fdy-nav-drawer)`, from `@cahyo-dimas/freeday/media` | a literal `640px` or `720px` retyped into your stylesheet, which no longer matches the kit's rule the day the kit retunes it — and which you could only have found by reading `filterbar.css` |
 
 ## 3. Starting a new screen
 

package/docs/getting-started.md

@@ -191,7 +191,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.4.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.6.0"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Freeday: token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,10 @@
       "types": "./dist/asset.d.ts",
       "default": "./dist/freeday.tokens.css"
     },
+    "./media": {
+      "types": "./dist/asset.d.ts",
+      "default": "./dist/freeday.media.css"
+    },
     "./breakpoints": {
       "types": "./tokens/breakpoints.d.ts",
       "default": "./tokens/breakpoints.mjs"
@@ -92,7 +96,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test --test-concurrency=3 browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/bottom-nav.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/cfl-narrow.mjs browser/harness-contract.mjs",
+    "test:browser": "node --test --test-concurrency=3 browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/bottom-nav.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/cfl-narrow.mjs browser/form-reveal.mjs browser/confirm-search-copy.mjs browser/daterange-settled.mjs browser/display-parts.mjs browser/table-empty.mjs browser/page-columns.mjs browser/table-hover.mjs browser/harness-contract.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit",

package/src/components/avatar.css

@@ -8,6 +8,8 @@
 .fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
+/* Square: a mark that is not a person (a company logo, a card's icon chip, #070). */
+.fdy-avatar--square{border-radius:var(--radius-md);}
 .fdy-avatar-group{display:inline-flex;}
 .fdy-avatar-group .fdy-avatar{border:2px solid var(--color-surface);margin-left:calc(var(--space-2)*-1);}
 .fdy-avatar-group .fdy-avatar:first-child{margin-left:0;}

package/src/components/breakpoints.css

@@ -1,7 +1,13 @@
 /* Freeday. Responsive display utilities (pairs with freeday-breakpoint.js).
  * Breakpoint scale (min-width, px): sm 600 · md 960 · lg 1280 · xl 1920.
+ * Two further widths exist and are NOT ramp steps: `nav` (app-shell.css, off-canvas drawer vs
+ * static sidebar) and `filterbar` (filterbar.css, the width its fields stack at). Both are named
+ * in tokens/breakpoints.mjs; a rule that has to fire with one of them aligns to it, not to the
+ * nearest ramp step, which is a band of broken widths in both directions.
  * NOTE: media-query breakpoints must be literal. CSS can't read custom properties
- * inside @media, so these px are structural, not stray magic numbers. */
+ * inside @media, so these px are structural, not stray magic numbers. An app that runs PostCSS
+ * need not retype them: `@cahyo-dimas/freeday/media` declares every width above as a
+ * @custom-media, so it can write `@media (--fdy-below-sm)` and never drift (#058 §2). */
 .fdy-hidden{display:none !important;}
 
 /* hide-below-X, hidden when the viewport is narrower than X (content shows at X and up) */

package/src/components/card.css

@@ -32,6 +32,13 @@
    absolutely positioned dismiss button back into the flow. Do not merge these two rules. */
 :where(:is(.fdy-card,.fdy-list__row):has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch)){position:relative;}
 .fdy-card__body{padding:var(--space-5);}
+/* Header band (#070): an identity mark, the title, and the card's way out pinned right. Beside the
+   title the action sits in one place on every card; under the content it moved each time the
+   content grew. Outside __body's padding, so its rule spans the card edge to edge. The mark is an
+   .fdy-avatar (--sm --square --tone-N), so its tints are the ones the contrast gate already covers. */
+.fdy-card__head{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);border-bottom:var(--bw) solid var(--color-border-muted);}
+.fdy-card__head .fdy-card__title{flex:1 1 auto;min-width:0;margin:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.fdy-card__action{flex:none;display:inline-flex;align-items:center;gap:var(--space-2);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
 .fdy-card__footer{padding:var(--space-3) var(--space-5);border-top:var(--bw) solid var(--color-border-muted);background:linear-gradient(180deg,var(--color-surface),var(--color-surface-2));display:flex;gap:var(--space-2);justify-content:flex-end;}

package/src/components/composition.css

@@ -95,3 +95,39 @@
 .fdy-text-success{color:var(--color-success-strong);}
 .fdy-text-warning{color:var(--color-warning-strong);}
 .fdy-text-danger{color:var(--color-danger-strong);}
+/* Document columns (#065): a form or record page with an optional identity rail on the left
+ * (__lead) and a summary rail on the right (__aside). The widths follow which rails are PRESENT,
+ * so the layout is decided once here and not again by every screen:
+ *   __main alone            one column
+ *   __main + __aside        8 / 4         (from md)
+ *   __lead + __main         3 / 9         (from md)
+ *   all three               3 / 6 / 3     (from lg; between md and lg both rails share the left)
+ * Stacked, the summary rail comes FIRST: last, it sits under every section, and its button with it.
+ * From md each rail is sticky and scrolls on its own, so the total and the status stay answerable
+ * while the main column scrolls with the page, and a rail taller than the screen never hangs its
+ * end off it. Screen only: a printed page is not held to a window. */
+.fdy-page__columns{--_fdy-rail-top:var(--fdy-page-sticky-top,var(--space-4));display:grid;grid-template-columns:minmax(0,1fr);gap:var(--space-6);align-items:start;}
+/* Under the shell the sticky topbar is in the way; --fdy-page-sticky-top overrides either default. */
+.fdy-app .fdy-page__columns{--_fdy-rail-top:var(--fdy-page-sticky-top,calc(var(--space-16) + var(--space-4)));}
+.fdy-page__columns > *{min-width:0;}
+@media (max-width:959.98px){.fdy-page__aside{order:-1;}}
+@media (min-width:960px){
+  .fdy-page__columns:has(> .fdy-page__aside){grid-template-columns:minmax(0,2fr) minmax(0,1fr);}
+  .fdy-page__columns:has(> .fdy-page__lead){grid-template-columns:minmax(0,1fr) minmax(0,3fr);}
+  /* Both rails, two columns: they stack on the left while __main spans both rows on the right. */
+  .fdy-page__columns:has(> .fdy-page__lead):has(> .fdy-page__aside) > .fdy-page__main{grid-row:span 2;}
+}
+@media (min-width:1280px){
+  .fdy-page__columns:has(> .fdy-page__lead):has(> .fdy-page__aside){grid-template-columns:minmax(0,1fr) minmax(0,2fr) minmax(0,1fr);}
+  .fdy-page__columns:has(> .fdy-page__lead):has(> .fdy-page__aside) > .fdy-page__main{grid-row:auto;}
+}
+/* The padding, taken back by the margin, is room for a focus ring at a card's edge: a scrolling box
+   clips whatever draws outside it. */
+@media screen and (min-width:960px){
+  .fdy-page__lead,.fdy-page__aside{position:sticky;top:var(--_fdy-rail-top);max-height:calc(100dvh - var(--_fdy-rail-top) - var(--space-4));overflow-y:auto;overscroll-behavior:contain;padding:var(--space-1);margin:calc(var(--space-1) * -1);}
+}
+/* Two sticky rails in ONE column would slide over each other: between md and lg, with both rails
+   present, they scroll with the page instead. */
+@media screen and (min-width:960px) and (max-width:1279.98px){
+  .fdy-page__columns:has(> .fdy-page__lead):has(> .fdy-page__aside) > :is(.fdy-page__lead,.fdy-page__aside){position:static;max-height:none;overflow:visible;}
+}

package/src/components/description-list.css

@@ -1,6 +1,16 @@
 /* Freeday. Description list (key-value detail view) */
 .fdy-dl{display:grid;grid-template-columns:auto 1fr;gap:var(--space-2) var(--space-5);margin:0;}
 .fdy-dl dt{color:var(--color-text-muted);font-size:var(--text-sm);}
-.fdy-dl dd{margin:0;color:var(--color-text);font-size:var(--text-sm);font-weight:var(--weight-medium);}
+/* overflow-wrap: an email, an order code or a 13-digit phone number is one unbreakable token, and
+   without it the value prints over whatever sits beside it (#066). */
+.fdy-dl dd{margin:0;min-width:0;color:var(--color-text);font-size:var(--text-sm);font-weight:var(--weight-medium);overflow-wrap:anywhere;}
 .fdy-dl--rows{grid-template-columns:1fr;gap:var(--space-1);}
 .fdy-dl--rows dt{margin-top:var(--space-2);}
+/* Facts grid (#066): each pair a <div> (allowed inside <dl>), caption above value, as many columns
+   as the list's OWN width holds, never more than three. Sized by the element rather than the
+   window, so a grid in a narrow side rail stays one column with no modifier: a window breakpoint
+   gave a rail two columns of about 110px. min(100%, …) keeps a single column from overflowing a
+   rail narrower than the column floor. */
+.fdy-dl--grid{grid-template-columns:repeat(auto-fill,minmax(min(100%,max(var(--fdy-dl-col-min,14rem),calc((100% - 2 * var(--space-6)) / 3))),1fr));gap:var(--space-5) var(--space-6);}
+.fdy-dl--grid > div{min-width:0;}
+.fdy-dl--grid dd{margin-top:var(--space-1);}

package/src/components/filterbar.css

@@ -41,7 +41,14 @@
 /* Opt-in: sit the actions inline right after the last field instead of at the far edge, so when the
  * bar wraps they read as attached to the filters rather than shoved to the right of a lonely row. */
 .fdy-filterbar--actions-inline .fdy-filterbar__actions{margin-left:0;}
-/* Stack on narrow screens so nothing overflows the row. */
+/* Stack on narrow screens so nothing overflows the row.
+ * 640 is deliberately not a ramp step (sm is 600): it is a real phone-landscape width, and moving
+ * it now would reflow every filter bar in every consuming app. So it is NAMED instead — `filterbar`
+ * in tokens/breakpoints.mjs, `--fdy-filterbar-stacked` in the media sheet — because an app rule
+ * that must fire with the stack (releasing a --w-grow field's max-width, say) has to match this
+ * exact condition, and aligning it to sm from the docs alone leaves 600–640px half-stacked: the
+ * fields are already full width while the app still caps the growing one. Raised from
+ * IDU_AI_DOC_SAPB1_CLIENT and IDU_AI_DOC_SAAS (#058 §1). */
 @media (max-width:640px){
   .fdy-filterbar>.fdy-field,.fdy-filterbar>.fdy-field--w-sm,.fdy-filterbar>.fdy-field--w-lg,.fdy-filterbar>.fdy-field--w-xl,.fdy-filterbar>.fdy-field--w-2xl,.fdy-filterbar>.fdy-field--w-grow{width:100%;flex:1 1 100%;}
   .fdy-filterbar__actions{width:100%;margin-left:0;}

package/src/components/selection.css

@@ -21,6 +21,12 @@
 .fdy-switch input::before{content:"";position:absolute;top:2px;left:2px;width:calc(var(--control-switch-h) - 4px);height:calc(var(--control-switch-h) - 4px);border-radius:50%;background:var(--color-switch-thumb);box-shadow:var(--shadow-1);transition:transform var(--dur-base) var(--ease-spring);}
 .fdy-switch input:checked{background:var(--color-primary);}
 .fdy-switch input:checked::before{transform:translateX(calc(var(--control-switch-w) - var(--control-switch-h)));}
+/* State hint (#068): one line saying what the CURRENT state means, never "on means X, off means Y",
+   which leaves the reader to work out which half applies. The control's aria-describedby points at
+   the .fdy-help WRAPPING both lines: a hidden child of a referenced node is skipped, so a screen
+   reader hears only the line on screen. Point it at the two children and both are read. */
+.fdy-field:has(:is(.fdy-switch,.fdy-check) input:checked) [data-fdy-when="off"],
+.fdy-field:not(:has(:is(.fdy-switch,.fdy-check) input:checked)) [data-fdy-when="on"]{display:none;}
 
 /* Standalone checkbox (e.g. table row/select-all), supports :indeterminate */
 .fdy-checkbox{appearance:none;-webkit-appearance:none;flex:none;width:var(--control-box);height:var(--control-box);margin:0;border:1.5px solid var(--color-control-border);border-radius:var(--radius-sm);background:var(--color-surface);box-shadow:inset 0 1px 2px var(--color-shadow-inset);cursor:pointer;display:grid;place-content:center;transition:background var(--dur-fast) var(--ease-standard),border-color var(--dur-fast) var(--ease-standard);}

package/src/components/states.css

@@ -6,3 +6,10 @@
 .fdy-state__text{font-size:var(--text-sm);color:var(--color-text-muted);max-width:24rem;line-height:var(--leading-normal);}
 .fdy-state__actions{margin-top:var(--space-2);display:flex;gap:var(--space-2);flex-wrap:wrap;justify-content:center;}
 .fdy-state--danger .fdy-state__icon{color:var(--color-danger-strong);}
+/* Compact (#069): the same state inside a small card, one line of icon and text instead of a
+   page-sized block. Danger matters most here: a widget that renders zero for a failed request
+   reads as "nothing to do", the opposite of what happened. */
+.fdy-state--compact{flex-direction:row;align-items:flex-start;text-align:left;gap:var(--space-2);padding:var(--space-2) 0;}
+.fdy-state--compact .fdy-state__icon{width:1rem;height:1rem;flex:none;}
+.fdy-state--compact .fdy-state__text{font-size:var(--text-xs);max-width:none;}
+.fdy-state--compact .fdy-state__actions{margin:0 0 0 auto;}

package/src/components/table.css

@@ -15,8 +15,17 @@
    itself, for the same reason: hover paints the full step, so the two must not be the same colour.
    Exposed as a Tier-3 token through the var() FALLBACK, never as a declaration — a custom property
    set here would outrank a host's own :root override. */
-.fdy-table--striped tbody tr:nth-child(even){background:var(--fdy-table-stripe,color-mix(in srgb,var(--color-surface-2) 55%,var(--color-surface)));}
-.fdy-table tbody tr:hover{background:var(--color-surface-2);}
+/* The resting colour is also published as --_fdy-row-rest, so a row that must not answer the
+   pointer can hover back to exactly what it was (see --hover-actionable). */
+.fdy-table--striped tbody tr:nth-child(even){--_fdy-row-rest:var(--fdy-table-stripe,color-mix(in srgb,var(--color-surface-2) 55%,var(--color-surface)));background:var(--_fdy-row-rest);}
+.fdy-table tbody tr:hover{background:var(--_fdy-row-hover,var(--color-surface-2));}
+/* Opt-in (#064): only a row that DOES something answers the pointer. A tint on a row with no click
+   handler promises a target that is not there: people click the row, nothing happens, and the
+   button they had to aim at was elsewhere in it. Striping, not hover, is what keeps the eye on a
+   line. The inert row's hover resolves to its own resting colour, so a stripe survives it; a frozen
+   cell falls back to its opaque surface, because it scrolls over its neighbours. */
+.fdy-table--hover-actionable tbody tr:not(.fdy-table__row--activatable){--_fdy-row-hover:var(--_fdy-row-rest,transparent);}
+.fdy-table--hover-actionable tbody tr:not(.fdy-table__row--activatable) td.fdy-table__freeze{--_fdy-row-hover:var(--_fdy-row-rest,var(--color-surface));}
 /* Monospace data, ids, codes, IPs, timestamps. Alignment-neutral so it works in any cell
    or inline (`<span class="fdy-mono">`), not just numeric columns. */
 .fdy-mono{font-family:var(--font-mono);font-variant-numeric:tabular-nums;}
@@ -25,8 +34,8 @@
 .fdy-table__num{text-align:right;font-variant-numeric:tabular-nums;font-family:var(--font-mono);}
 /* Loading / empty state cell (FdyTable spans it across all columns). */
 .fdy-table__state{text-align:center;color:var(--color-text-muted);padding:var(--space-6) var(--space-4);}
-/* Activatable row (FdyTable rowActivatable): pointer + keyboard focus ring. The hover tint already
-   comes from the base `.fdy-table tbody tr:hover` rule, so this only adds the affordance + focus. */
+/* Activatable row (FdyTable rowActivatable): pointer + keyboard focus ring. The hover tint comes from
+   the base `.fdy-table tbody tr:hover` rule, which --hover-actionable keeps for these rows only. */
 .fdy-table__row--activatable{cursor:pointer;}
 .fdy-table__row--activatable:focus-visible{outline:2px solid var(--color-primary);outline-offset:-2px;}
 /* Expandable detail row (FdyTable row-detail slot): a muted panel under its row, no hover tint. */
@@ -86,7 +95,7 @@
    (0,4,3) and beat the hover rule below. At (0,3,3) it ties, and the later rule wins, so a hovered
    row still bands unbroken across the freeze line. */
 .fdy-table--striped tbody tr:nth-child(even) td.fdy-table__freeze{background:var(--fdy-table-stripe,color-mix(in srgb,var(--color-surface-2) 55%,var(--color-surface)));}
-.fdy-table--sticky tbody tr:hover td.fdy-table__freeze{background:var(--color-surface-2);}
+.fdy-table--sticky tbody tr:hover td.fdy-table__freeze{background:var(--_fdy-row-hover,var(--color-surface-2));}
 /* A frozen header cell is stuck on both axes wherever the head is frozen too, so
    it has to outrank both. */
 .fdy-table--sticky thead .fdy-table__freeze{z-index:3;}

package/tokens/breakpoints.d.ts

@@ -4,6 +4,10 @@ export declare const breakpoints: {
   /** Width at which .fdy-app's sidebar turns from off-canvas drawer into a static column.
    *  Not part of the sm/md/lg/xl ramp; it mirrors app-shell.css and nothing else. */
   nav: number;
+  /** Width at or below which .fdy-filterbar stacks every field full-width.
+   *  Not part of the sm/md/lg/xl ramp; it mirrors filterbar.css and nothing else. A rule that
+   *  must fire with the stack uses this, not `sm` — `sm` leaves 600–640px half-stacked. */
+  filterbar: number;
   sm: number;
   md: number;
   lg: number;