@cahyo-dimas/freeday 1.27.0 → 1.29.0

package/CHANGELOG.md

@@ -3,6 +3,107 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.29.0] — 2026-08-18
+Improvement note 001 from a second consuming app (a 40-screen back office). Eight findings; six
+executed, one already documented, one left as an owner decision.
+### Added
+- **`clearable` on `FdyCfl`** (Vue · React · Blazor). The value type already said `Row | null`, but
+  the emit was `Row` only — a choose-from-list could be **set and never unset**, which breaks every
+  *optional* foreign key (a device with no project, an expense with no workflow, a top-level record
+  with no parent). A user who picked the wrong row had to reload the form. The clear control is a
+  second `.fdy-input-group__btn`, emits `null`, returns focus to the trigger, and never touches the
+  dialog.
+- **`.fdy-label--required`** — the marker is painted through `::after` with **CSS alt text**
+  (`content:"*" / ""`), so the glyph appears and the accessibility tree gets nothing. The control
+  already carries `required`; a `<span>` an app has to remember to mark `aria-hidden` can be
+  forgotten, this cannot.
+- **`.fdy-icon`** — a `1em` square, `flex:none` box for the icons the kit deliberately does not
+  ship. Every icon slot it *does* ship (`.fdy-btn__icon`, `.fdy-nav__icon`, `.fdy-state__icon`)
+  already assumed something sensible inside; a standalone icon had no contract.
+- **`.fdy-text-success` · `.fdy-text-warning` · `.fdy-text-danger`** — the kit had three
+  *de-emphasis* text roles and no *state* role, so a consequential sentence ("Amount changed from X
+  to Y", "No approver assigned") had to fall back to `.fdy-text-caption`, which de-emphasises
+  exactly the line that should stand out. A badge is wrong (prose, not a status) and an alert is
+  wrong (a block, not one line in a row).
+### Fixed
+- **`.fdy-menu__item:focus-visible` gets a real ring.** It marked focus with the same fill as
+  `:hover`, and `freeday-menu.js` moves real DOM focus — so arrowing through a menu was invisible,
+  and hover and focus were identical to everyone else. `.fdy-nav__item`, in the same kit, has always
+  done it correctly. Reported by two different apps before it was fixed.
+- **A grouped `<fieldset>` now has its spacing.** `fieldset.fdy-field` already reset the UA border,
+  but the **rendered legend is laid out outside the flex flow**, so `gap` never reached it —
+  measured 0px between legend and first control. One declaration on the reset the kit already
+  ships, not a new block; `COMPONENTS.md` documents the compose (`.fdy-field` on the fieldset,
+  `.fdy-label` on the legend), which is what was actually missing.
+### Notes on the shape of the fix
+- **§7 (an Indonesian `aria-label`) is not what it looked like.** The report assumed the rest of the
+  kit's output is English; it is not — *every* user-visible string the vanilla enhancers write is
+  Indonesian (`Sebelumnya`, `Berikutnya`, `Berisi teks`, `Reset`, `Tutup`, `Menampilkan …`,
+  `Bulan berikutnya`, `Format tidak valid.`). Translating one would **create** the mixed interface
+  the note objects to. The real choice — an override hook, or switching the defaults and breaking
+  every Indonesian consumer — is recorded in `NEXT-UP.md` #6 with its trigger; `COMPONENTS.md` now
+  states the caveat in full and points English apps at the typed wrappers.
+- **§8 needed no code**, only the line it asked for: the filter button and its dialog share an
+  accessible name on purpose, so a test suite wants `getByRole`, not `getByLabel`.
+- Two traps found by measuring rather than reading: `.fdy-icon` as a bare inline element **ignored
+  `width` entirely** (it does not apply to non-replaced inline boxes) and rendered 936px wide until
+  it got a `display`; and stacking two colour roles (`.fdy-help.fdy-text-warning`) silently loses to
+  whichever rule the bundle happens to emit later — documented, and the docs page no longer does it.
+### Added — guards
+- Adapter specs for `clearable` in both Vue and React (real clicks: emits `null`, empties the field,
+  the control disappears with the value it cleared, focus lands on the trigger, dialog stays shut).
+- CSS gate: menu focus must render as more than the hover fill; the required marker must keep its
+  alt text; `.fdy-icon` must keep a display that accepts a width; the state roles must spend the
+  exact inks the contrast gate proves readable — that last one closes the seam between the two test
+  files, where a class could drift to a weaker token while every token assertion stayed green.
+- `contrast.test.mjs` now also asserts the state inks on **plain** surfaces, not just over their own
+  `-soft` fills.
+
+## [1.28.0] — 2026-08-18
+Improvement note 007, written while fixing a workspace picker whose cards showed a pointer cursor
+and swallowed every click.
+### Added
+- **`.fdy-btn--stretch`** — the pattern for **one card, one primary action, one escape hatch**, which
+  the kit had no shape for: `--button` is a card that *is* one control, `--interactive` a card that
+  merely *has* one, and a card with two actions can be neither (interactive content nested in a
+  `<button>` is invalid HTML). The primary control keeps its real `<button>`/`<a>` semantics and
+  spreads its hit area over the card with a pseudo-element.
+  This is shipped rather than documented because it **cannot be hand-rolled on a `.fdy-btn`**: the
+  button nudges itself with a transform on `:hover`/`:active`, a transformed element becomes the
+  containing block for its own absolutely positioned descendants, and the overlay therefore
+  re-anchors from the card to the button's own box mid-gesture. `mousedown` lands on the button,
+  `mouseup` somewhere else, and the browser fires `click` on their common ancestor — the button never
+  gets one. The symptom is identical to the bug being fixed.
+  The report found this on `--text`/`--ghost`, which break on press. The kit's **base** rule is
+  `.fdy-btn:hover{transform:translateY(-1px)}`, so the default and `--danger` fills break one step
+  earlier, on hover: neutralising only `:active` — the obvious half-fix — still leaks.
+- **Escape hatches are raised automatically.** Every focusable element in a card holding a stretched
+  target sits above the overlay without markup or CSS from the consumer, because forgetting a
+  `z-index` here fails silently — the control looks and hovers exactly as before and simply never
+  receives the click.
+### Fixed
+- `--interactive` is now documented as **presentational**: the only affordance in the kit whose
+  correctness lives outside it. The CSS cannot know whether a handler exists, so the modifier without
+  a control and a control without the modifier both fail silently. It now points at the shape that
+  makes the promise true.
+### Notes on the shape of the fix
+- **Raising the escape hatch must not outweigh the app.** The first version declared
+  `position:relative` at normal specificity and *measurably* dragged an absolutely positioned corner
+  dismiss button back into the flow — a control the app had pinned itself, moved by the kit, with no
+  error. `z-index` still wins, but the `position` it needs is now a zero-specificity `:where()`
+  default that any app rule beats. The two rules must stay split; the gate asserts it.
+- **Cards only.** The overlay anchors to the nearest *positioned* ancestor. `.fdy-list__row` is not
+  positioned (`.fdy-list` is), so a stretched target in a list row would cover the whole list —
+  documented, with `.fdy-list__row--button` as the answer for clickable rows.
+### Added — guards
+- `browser/card-stretch.mjs` drives real presses: the target receives clicks from anywhere on the
+  card, the click is dispatched **on the button** rather than on a common ancestor, the secondary
+  action and an inline link keep their own clicks, and an app-pinned control keeps its own
+  `position`. A synthetic `.click()` never enters `:active` and passes against the broken CSS, which
+  is why this spec is worth its weight.
+- `test/css.test.mjs` guards all of it at the CI gate. Mutation-checked against six defects,
+  including both of the ones written during this change.
+
 ## [1.27.0] — 2026-08-14
 Improvement note #44, found while building a settings screen whose only numeric field looked like it
 belonged to a different application.

package/COMPONENTS.md

@@ -212,6 +212,8 @@ One role per level of hierarchy — never re-use a card title for a page title.
 | `.fdy-title-card` | `<h3>` | A title inside a card or row (`.fdy-card__title` is equivalent). |
 | `.fdy-text-muted` · `.fdy-text-subtle` | any | Secondary / tertiary text colour. |
 | `.fdy-text-caption` | `<p>` | Small muted text: timestamps, help. |
+| `.fdy-text-success` · `.fdy-text-warning` · `.fdy-text-danger` | any | Inline text that carries **state** — a sentence, not a status. Use when a badge is wrong (it is prose) and an alert is wrong (it is one line inside a row): "Amount changed from X to Y", "No approver assigned". **Do not stack two colour roles** (`.fdy-help.fdy-text-warning`): both are single classes, so the one that happens to come later in the stylesheet wins — put the state class on its own element, and use `.fdy-help--error` for help text. |
+| `.fdy-icon` | `<svg>` or a wrapper | Icon box: `1em` square, `flex:none`, so the glyph tracks the text beside it at every scale. The kit ships no paths — bring your own, use the box. |
 | `.fdy-mono` | any | Tabular/monospace data (codes, amounts, ids). |
 
 ## Utilities
@@ -291,7 +293,23 @@ native control, otherwise a `<div>` + explicitly associated label.
 
 - `.fdy-field` (+ `--full` inside `.fdy-form-grid`; widths `--w-sm` `--w-lg` `--w-xl` `--w-2xl`
   `--w-grow` inside `.fdy-filterbar`)
-- `.fdy-label` · `.fdy-input` (+`--error`) · `.fdy-textarea` · `.fdy-help` (+`--error`)
+- `.fdy-label` (+`--required`) · `.fdy-input` (+`--error`) · `.fdy-textarea` · `.fdy-help` (+`--error`)
+
+**Grouped controls are a `<fieldset>`, not a new block.** Put `.fdy-field` on the fieldset and
+`.fdy-label` on the legend — the kit already resets the UA border/padding and supplies the spacing:
+
+```html
+<fieldset class="fdy-field">
+  <legend class="fdy-label">Working week</legend>
+  <label class="fdy-check"><input type="checkbox"> Monday</label>
+  <label class="fdy-check"><input type="checkbox"> Tuesday</label>
+</fieldset>
+```
+
+**`--required` marks the label, not the accessibility tree.** The control already carries
+`required`; the asterisk is painted through `::after` with CSS alt text, so a screen reader never
+reads "star" after the label — something a `<span>` you have to remember to mark `aria-hidden`
+cannot guarantee.
 - `[readonly]` is styled on input/textarea: full contrast, focusable, copyable.
 
 ```html
@@ -472,6 +490,13 @@ the field. The value is always **chosen, never typed**. Needs `freeday-cfl.js`.
 </dialog>
 ```
 
+**`clearable` makes the value removable.** Without it a choose-from-list can be set but never unset,
+which breaks every *optional* foreign key — the value type already allows null, only the component
+could not produce it. With it, a clear button appears beside the trigger whenever a row is picked
+and the field is editable; it emits `null` (Vue `update:modelValue`/`change`, React `onChange`,
+Blazor `ValueChanged`) and returns focus to the trigger. It is a second `.fdy-input-group__btn`, not
+a new class.
+
 ## Date picker — `data-fdy-datepicker`
 > **Typed wrapper: `<FdyDatepicker>`** — Vue (`v-model`) · React (`value`/`onChange`) · Blazor (`@bind-Value`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
 
@@ -660,10 +685,19 @@ pagination. Needs `freeday-table.js`. Wrap the whole thing in `.fdy-datatable` +
 - Footer: `.fdy-table-footer` · `__info` (`data-fdy-table-info`) + `<nav class="fdy-pagination"
   data-fdy-table-pagination>`
 - Sort values: put the raw value in `data-sort-value` when the cell text is formatted.
-- **Language caveat:** the vanilla enhancer writes the footer and bulk-count strings in Indonesian
-  (`Menampilkan 1–5 dari 7`, `N dipilih`) and has no override hook. The Vue/React/Blazor `FdyTable`
-  components are English. For an English static page, render those two nodes yourself from the
-  `fdy-table-change` event instead of using `data-fdy-table-info` / `data-fdy-table-bulk-count`.
+- **Language caveat:** every user-visible string the **vanilla enhancers** write is Indonesian —
+  the table's footer and bulk count (`Menampilkan 1–5 dari 7`, `N dipilih`), its pager and filter
+  UI (`Sebelumnya`, `Berikutnya`, `Filter kolom`, `Berisi teks`, `Reset`, `Tutup`), and the same
+  applies elsewhere (`Bulan berikutnya`, `Format tidak valid.`). There is no override hook. The
+  Vue/React/Blazor components are English throughout, so **an English app should use the typed
+  wrapper**, not the enhancer. For an English static page, render the footer/bulk nodes yourself
+  from the `fdy-table-change` event instead of using `data-fdy-table-info` /
+  `data-fdy-table-bulk-count`; the filter button's `aria-label` has no such escape today.
+
+**Testing note:** a column's filter button and the dialog it opens deliberately share one
+accessible name (`Filter <column>`) — a dialog named after its trigger is the normal pattern. In a
+Playwright/Testing-Library suite that means `getByLabel('Filter Name')` resolves to two elements;
+reach for `getByRole('button', { name: 'Filter Name' })` instead.
 
 ## Pagination — `.fdy-pagination`
 The block class on the `<nav>` is a **structural hook only** — it carries no rule of its own; the
@@ -885,7 +919,11 @@ is `role="group" aria-roledescription="slide"`.
 Parts `__body` `__title` `__desc` `__footer`. Modifiers:
 
 - `--elevated` — raise it (use sparingly; most surfaces are flat)
-- `--interactive` — cursor + hover-lift for a card that *has* a click handler
+- `--interactive` — cursor + hover-lift for a card that *has* a click handler. **Presentational
+  only:** it is the one affordance in the kit whose correctness lives outside it — the CSS cannot
+  know whether a handler exists, so the modifier without a control (a card that looks clickable and
+  swallows every click) and a control without the modifier both fail silently. Pair it with a real
+  control — normally the stretched target below.
 - `--button` — for a card that **is** the control: render it as `<button>` and add this to reset
   the UA button box **without** losing the card surface/border
 - `.fdy-card--button` never replaces keyboard semantics — a clickable card must be a real
@@ -895,6 +933,44 @@ Parts `__body` `__title` `__desc` `__footer`. Modifiers:
 - The card is `position:relative`, so a badge or ribbon you absolutely position inside it anchors
   to the card. That is also what keeps hidden labels inside it from escaping — see *Containment*.
 
+### One card, one primary action, one escape hatch
+
+A card with **two** actions cannot be `--button`: interactive content nested in a `<button>` is
+invalid HTML. Give the primary control `.fdy-btn--stretch` — its hit area covers the whole card,
+while it stays a real `<button>`/`<a>` with real keyboard semantics.
+
+```html
+<article class="fdy-card fdy-card--interactive">
+  <div class="fdy-card__body">
+    <h3 class="fdy-card__title">Workspace Alpha</h3>
+    <p class="fdy-card__desc">12 members · 4 boards</p>
+  </div>
+  <div class="fdy-card__footer">
+    <button class="fdy-btn fdy-btn--text" type="button">Details</button>   <!-- escape hatch -->
+    <button class="fdy-btn fdy-btn--stretch" type="button">Open workspace Alpha</button>
+  </div>
+</article>
+```
+
+- **The escape hatch needs nothing.** Every focusable element in a card that holds a stretched
+  target is raised above the overlay automatically — forgetting a `z-index` here fails silently, and
+  a silent failure is what this pattern exists to remove. The `position` that raising needs is only a
+  **default** (zero-specificity), so a control you pin yourself — a corner dismiss, a favourite star —
+  keeps its own `position:absolute` and is raised anyway.
+- **Name the stretched button for what the whole card does** ("Open workspace Alpha", not "Open").
+  Its label is the accessible name of the entire hit area.
+- **Do not add `.fdy-btn--stretch` to more than one control per card** — the last one wins the
+  overlap, and which one that is depends on source order.
+- Text under the overlay is no longer selectable; that is the cost of the pattern, not a bug.
+- **Cards only.** The overlay anchors to the nearest *positioned* ancestor, and in the kit that is
+  `.fdy-card`. A `.fdy-list__row` is **not** positioned (`.fdy-list` is), so a stretched target in a
+  list row would cover the **whole list** — for clickable rows use `.fdy-list__row--button`.
+- `.fdy-btn` nudges itself on `:hover`/`:active`, and a transformed element becomes the containing
+  block for its own absolutely positioned descendants — so a hand-rolled `::after{inset:0}` overlay
+  **re-anchors to the button mid-gesture** and the click never lands. `--stretch` neutralises those
+  transforms and moves the press feedback to the card. This is why the pattern is shipped rather
+  than documented.
+
 ## Badge — `.fdy-badge`
 Inline status pill: `--success` `--warning` `--danger` `--info` `--outline`. Never colour-only —
 the text carries the meaning.

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.27.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.27.0)
+[![Release](https://img.shields.io/badge/release-v1.29.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.29.0)
 
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.27.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.27.0)
+[![Release](https://img.shields.io/badge/release-v1.29.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.29.0)
 
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/adapters/blazor/FdyCfl.razor

@@ -11,6 +11,15 @@
     <input class="fdy-input" type="text" readonly value="@DisplayValue"
            placeholder="@Placeholder" aria-labelledby="@AriaLabelledby"
            aria-invalid="@(Invalid ? "true" : null)" aria-readonly="@(Readonly ? "true" : null)" />
+    @if (Clearable && Value is not null && !Disabled && !Readonly)
+    {
+        <button class="fdy-input-group__btn" type="button" @onclick="ClearAsync" aria-label="@ClearLabel">
+            <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+                 stroke-width="2" stroke-linecap="round" aria-hidden="true">
+                <path d="M6 6l12 12M18 6L6 18"></path>
+            </svg>
+        </button>
+    }
     <button class="fdy-input-group__btn" type="button" @onclick="OpenAsync"
             disabled="@(Disabled || Readonly)" aria-label="@SearchPlaceholder">
         <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"

package/adapters/blazor/FdyCfl.razor.cs

@@ -37,6 +37,11 @@ public partial class FdyCfl<TRow>
     /// <summary>Locked/view mode: shows the value but the search dialog can't be opened.</summary>
     [Parameter] public bool Readonly { get; set; }
     [Parameter] public bool Invalid { get; set; }
+    /// <summary>Render a clear button when a row is picked, so an OPTIONAL foreign key can be unset.
+    /// <c>Value</c> is already <c>TRow?</c>; without this the component can never produce null.</summary>
+    [Parameter] public bool Clearable { get; set; }
+    /// <summary>aria-label for the clear button (when <see cref="Clearable"/>).</summary>
+    [Parameter] public string ClearLabel { get; set; } = "Clear selection";
     [Parameter] public string? AriaLabelledby { get; set; }
 
     /// <summary>Debounce (ms) between a keystroke and the search request.</summary>
@@ -129,6 +134,14 @@ public partial class FdyCfl<TRow>
 
     private Task RetryAsync() => LoadAsync(reset: true);
 
+    /// <summary>Unset the value. Not "choosing nothing": the dialog is not involved, so this neither
+    /// opens nor closes it.</summary>
+    private async Task ClearAsync()
+    {
+        Value = default;
+        await ValueChanged.InvokeAsync(default);
+    }
+
     private async Task ChooseAsync(TRow row)
     {
         Value = row;

package/adapters/react/components/FdyCfl.tsx

@@ -22,7 +22,7 @@ export interface CflPage<Row> {
 
 export interface FdyCflProps<Row extends Record<string, unknown>> {
   value: Row | null;
-  onChange: (value: Row) => void;
+  onChange: (value: Row | null) => void;
   fetchPage: (query: string, page: number) => Promise<CflPage<Row>>;
   columns: ReadonlyArray<CflColumn<Row>>;
   display: (row: Row) => string;
@@ -34,6 +34,11 @@ export interface FdyCflProps<Row extends Record<string, unknown>> {
   /** Locked/view mode: shows the picked value (focusable, copyable), but the search dialog can't be opened. Unlike `disabled`, it keeps tab order and isn't greyed. */
   readonly?: boolean;
   invalid?: boolean;
+  /** Render a clear button when a row is picked, so an OPTIONAL foreign key can be unset. Without it
+   *  `value` accepts `Row | null` but the component can only ever produce a `Row`. */
+  clearable?: boolean;
+  /** aria-label for the clear button (when `clearable`). Default 'Clear selection'. */
+  clearLabel?: string;
   describedby?: string;
   id?: string;
   ariaLabelledby?: string;
@@ -46,6 +51,14 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
   const resultsId: string = `${baseId}-results`;
   const rowId = (index: number): string => `${baseId}-row-${index}`;
 
+  /* Unsetting is not "picking nothing": it must not touch the dialog, and focus must land on a
+     control that still exists — the trigger beside it, since this button disappears with the value. */
+  const clearLabelText: string = props.clearLabel ?? 'Clear selection';
+  const clearValue = (): void => {
+    props.onChange(null);
+    triggerRef.current?.focus();
+  };
+
   const dialogRef = useRef<HTMLDialogElement>(null);
   const triggerRef = useRef<HTMLButtonElement>(null);
   const searchRef = useRef<HTMLInputElement>(null);
@@ -71,6 +84,8 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
 
   const isDisabled: boolean = props.disabled === true;
   const isReadonly: boolean = props.readonly === true;
+  const showClear: boolean =
+    props.clearable === true && props.value !== null && isDisabled === false && isReadonly === false;
   const isInvalid: boolean = props.invalid === true;
   const displayValue: string = props.value !== null ? props.display(props.value) : '';
   // The results <table> (owner of `resultsId`) only renders in the rows branch, so gate the
@@ -253,6 +268,18 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
         aria-describedby={props.describedby}
         disabled={isDisabled}
       />
+      {showClear ? (
+        <button
+          type="button"
+          className="fdy-input-group__btn"
+          aria-label={clearLabelText}
+          onClick={clearValue}
+        >
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true">
+            <path d="M6 6l12 12M18 6L6 18" />
+          </svg>
+        </button>
+      ) : null}
       <button
         ref={triggerRef}
         type="button"

package/adapters/vue/components/FdyCfl.vue

@@ -35,14 +35,19 @@ const props = defineProps<{
   /** Locked/view mode: shows the picked value (focusable, copyable), but the search dialog can't be opened. Unlike `disabled`, it keeps tab order and isn't greyed. */
   readonly?: boolean;
   invalid?: boolean;
+  /** Render a clear button when a row is picked, so an OPTIONAL foreign key can be unset. Without it
+   *  `modelValue` accepts `Row | null` but the component can only ever produce a `Row`. */
+  clearable?: boolean;
+  /** aria-label for the clear button (when `clearable`). Default 'Clear selection'. */
+  clearLabel?: string;
   describedby?: string;
   id?: string;
   ariaLabelledby?: string;
 }>();
 
 const emit = defineEmits<{
-  'update:modelValue': [value: Row];
-  change: [value: Row];
+  'update:modelValue': [value: Row | null];
+  change: [value: Row | null];
 }>();
 
 const baseId: string = useId();
@@ -67,6 +72,12 @@ const activeIndex: Ref<number> = ref(-1);
 
 const isDisabled: ComputedRef<boolean> = computed((): boolean => props.disabled === true);
 const isReadonly: ComputedRef<boolean> = computed((): boolean => props.readonly === true);
+
+const showClear: ComputedRef<boolean> = computed(
+  (): boolean =>
+    props.clearable === true && props.modelValue != null && isDisabled.value === false && isReadonly.value === false,
+);
+const clearLabelText: ComputedRef<string> = computed((): string => props.clearLabel ?? 'Clear selection');
 const isInvalid: ComputedRef<boolean> = computed((): boolean => props.invalid === true);
 const displayValue: ComputedRef<string> = computed((): string =>
   props.modelValue !== null ? props.display(props.modelValue) : '',
@@ -154,12 +165,20 @@ function setActive(index: number): void {
   });
 }
 
-function commit(row: Row): void {
+function commit(row: Row | null): void {
   emit('update:modelValue', row);
   emit('change', row);
   closeDialog();
 }
 
+/* Unsetting is not "picking nothing" — it must not open or close the dialog, and it must leave focus
+   on a control that still exists, so focus returns to the trigger beside it. */
+function clearValue(): void {
+  emit('update:modelValue', null);
+  emit('change', null);
+  triggerEl.value?.focus();
+}
+
 function onKeydown(e: KeyboardEvent): void {
   switch (e.key) {
     case 'ArrowDown':
@@ -256,6 +275,17 @@ onBeforeUnmount((): void => {
       :aria-describedby="describedby"
       :disabled="isDisabled"
     />
+    <button
+      v-if="showClear"
+      type="button"
+      class="fdy-input-group__btn"
+      :aria-label="clearLabelText"
+      @click="clearValue"
+    >
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+        <path d="M6 6l12 12M18 6L6 18"></path>
+      </svg>
+    </button>
     <button
       ref="triggerEl"
       type="button"

package/dist/freeday.bundle.css

@@ -711,6 +711,22 @@ a { color: var(--color-primary); }
 .fdy-btn--ghost[aria-pressed="true"],.fdy-btn--text[aria-pressed="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);border-color:var(--color-primary-border);box-shadow:none;}
 .fdy-btn--ghost[aria-pressed="true"]:hover,.fdy-btn--text[aria-pressed="true"]:hover{background:var(--color-primary-soft);transform:none;box-shadow:none;}
 
+/* Stretched hit area (#007) — spread this button's click target over its nearest positioned
+ * ancestor, so "one card, one primary action, one escape hatch" needs no click handler on the
+ * <article>: the real control stays a real <button>/<a> and keeps its keyboard semantics.
+ * `.fdy-card` is already position:relative, so it is the anchor.
+ *
+ * The transforms MUST go, and this is the whole reason the modifier exists rather than a docs line:
+ * a transformed element becomes the containing block for its own absolutely-positioned descendants,
+ * so `inset:0` re-anchors from the card to the button's own box the moment the button is hovered or
+ * pressed. Measured: mousedown lands on the button, the overlay collapses under the pointer, mouseup
+ * lands on some other element, and the browser fires `click` on their common ancestor — the button
+ * never gets one. It demos fine on hover for --text/--ghost (their hover is already transform:none)
+ * and only a real press reveals it; the default and --danger fills break one step earlier, on hover.
+ * Press feedback moves to the card, which is the object actually being pressed (see card.css). */
+.fdy-btn--stretch::after{content:'';position:absolute;inset:0;}
+.fdy-btn--stretch:hover,.fdy-btn--stretch:active{transform:none;}
+
 /* Icon-only — square; combine with --ghost/--text/--sm/--lg. Requires aria-label. */
 .fdy-btn--icon{width:var(--control-h);padding:0;}
 .fdy-btn--icon.fdy-btn--sm{width:calc(var(--control-h) - var(--space-2));}
@@ -744,9 +760,13 @@ a { color: var(--color-primary); }
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* Pressing a stretched target (see .fdy-btn--stretch) is pressing the CARD — the button's own
+   nudge had to go, and the object under the pointer is the card. Ordered before the reduced-motion
+   block and the disabled rules so both still win at equal specificity. */
+.fdy-card--interactive:has(.fdy-btn--stretch:active){transform:translateY(-1px);}
 /* The global reduced-motion reset kills the ANIMATION; drop the -3px shift too so the card
  * doesn't jump. The shadow still communicates the affordance. */
-@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover{transform:none;}}
+@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover,.fdy-card--interactive:has(.fdy-btn--stretch:active){transform:none;}}
 /* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
  * announced — reset the UA button box. Note: it does NOT reset background/border, because
  * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
@@ -755,6 +775,17 @@ a { color: var(--color-primary); }
    --interactive lift is withdrawn so a refusing control stops answering the pointer. */
 .fdy-card--button:disabled,.fdy-card--button[aria-disabled="true"],.fdy-card--interactive[aria-disabled="true"]{opacity:.5;cursor:not-allowed;}
 .fdy-card--interactive:disabled:hover,.fdy-card--interactive[aria-disabled="true"]:hover{box-shadow:var(--shadow-lift);transform:none;}
+/* Escape hatches stay clickable above a stretched target — automatic, not a documented convention,
+   because forgetting it fails SILENTLY: the secondary control looks and hovers exactly as before and
+   simply never receives the click, which is the very symptom the pattern exists to cure. Matched by
+   shape (anything focusable) so a control the kit does not ship yet is covered too. */
+.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
+/* The position is a DEFAULT, not an override: z-index needs a positioned box (or a flex/grid item),
+   but an app that deliberately pins a control inside the card — a corner dismiss, a favourite star —
+   must keep its own `position:absolute`. Wrapped in :where() so this whole selector weighs nothing
+   and ANY app rule wins it; measured, because at normal specificity the kit silently dragged an
+   absolutely positioned dismiss button back into the flow. Do not merge these two rules. */
+:where(.fdy-card: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);}
 .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);}
@@ -1020,6 +1051,22 @@ a { color: var(--color-primary); }
 .fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
 .fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
 
+/* Icon box (#001 §4). The kit ships no icons on purpose, but every icon slot it DOES ship
+   (.fdy-btn__icon, .fdy-nav__icon, .fdy-state__icon) assumes something sensible inside, so a
+   standalone icon had no contract and every app invented one. 1em keeps the glyph matched to the
+   text beside it at every scale — bring your own paths, use our box. Works on the <svg> itself or
+   on a wrapper around it. */
+.fdy-icon{display:inline-block;width:1em;height:1em;flex:none;vertical-align:-0.125em;}
+.fdy-icon>svg{display:block;width:100%;height:100%;}
+
+/* Inline text that carries STATE (#001 §5). The three roles above all de-emphasise; a sentence like
+   "Amount changed from X to Y" or "No approver assigned" needs the opposite, and is neither a badge
+   (those are statuses, not sentences) nor an .fdy-alert (those are blocks, not one line inside a
+   row). Same -strong inks the badges use, gated by contrast.test.mjs on plain surfaces too. */
+.fdy-text-success{color:var(--color-success-strong);}
+.fdy-text-warning{color:var(--color-warning-strong);}
+.fdy-text-danger{color:var(--color-danger-strong);}
+
 /* Freeday — Date picker (input-styled trigger + calendar popover).
  * Built by freeday-datepicker.js from an empty [data-fdy-datepicker] wrapper. */
 .fdy-datepicker{position:relative;display:inline-block;width:100%;max-width:14rem;}
@@ -1246,7 +1293,10 @@ a { color: var(--color-primary); }
    Neutralise the UA groove border / padding / min-inline-size so it lays out identically to the
    <div> form (min-inline-size:min-content would otherwise block the filterbar column widths). */
 fieldset.fdy-field{border:0;margin:0;padding:0;min-inline-size:0;}
-fieldset.fdy-field>legend{padding:0;float:none;}
+/* The rendered legend is laid out outside the fieldset's flex flow, so `gap` never reaches it —
+   measured 0px between legend and first control. This is the spacing contract a grouped field
+   needs; it matches .fdy-field's own gap so the group reads as one rhythm. */
+fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 .fdy-label{font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-input,.fdy-textarea{width:100%;height:var(--control-h);padding:0 var(--space-3);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);background:var(--color-surface);border:1.5px solid var(--color-control-border);border-radius:var(--radius-md);box-shadow:inset 0 1px 2px rgba(16,14,30,.06);transition:border-color var(--dur-fast) var(--ease-standard),box-shadow var(--dur-fast) var(--ease-standard);}
 .fdy-input::placeholder,.fdy-textarea::placeholder{color:var(--color-text-subtle);}
@@ -1270,6 +1320,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
+/* Required marker. The control already carries `required`, so the asterisk is decoration: the
+   `/ ""` is CSS alt text — the glyph is painted but exposes NOTHING to the accessibility tree, so a
+   screen reader does not read "star" after every label. That is stricter than a <span> an app has to
+   remember to mark aria-hidden, and it cannot be forgotten. */
+.fdy-label--required::after{content:"*" / "";margin-left:var(--space-1);color:var(--color-danger);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}
 .fdy-help--error{color:var(--color-danger);}
 
@@ -1320,7 +1375,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-menu--end{left:auto;right:0;}
 .fdy-menu__item{display:flex;align-items:center;gap:var(--space-2);width:100%;padding:var(--space-2) var(--space-3);border:0;background:transparent;border-radius:var(--radius-sm);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);text-align:left;cursor:pointer;white-space:nowrap;}
 .fdy-menu__item:hover,.fdy-menu__item.is-highlighted{background:var(--color-surface-3);}
-.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);}
+/* Focus is not hover. The enhancer moves real DOM focus (freeday-menu.js `.focus()`), so this is
+   the only thing a keyboard user has to go on — with the hover fill alone, arrowing through the
+   menu is invisible. Same ring as .fdy-nav__item, which got this right. Reported twice. */
+.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
 .fdy-menu__item:disabled{opacity:.5;cursor:not-allowed;background:transparent;}
 .fdy-menu__item--danger{color:var(--color-danger-strong);}
 .fdy-menu__item svg{display:block;width:1rem;height:1rem;flex:none;}

package/dist/freeday.css

@@ -341,6 +341,22 @@ a { color: var(--color-primary); }
 .fdy-btn--ghost[aria-pressed="true"],.fdy-btn--text[aria-pressed="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);border-color:var(--color-primary-border);box-shadow:none;}
 .fdy-btn--ghost[aria-pressed="true"]:hover,.fdy-btn--text[aria-pressed="true"]:hover{background:var(--color-primary-soft);transform:none;box-shadow:none;}
 
+/* Stretched hit area (#007) — spread this button's click target over its nearest positioned
+ * ancestor, so "one card, one primary action, one escape hatch" needs no click handler on the
+ * <article>: the real control stays a real <button>/<a> and keeps its keyboard semantics.
+ * `.fdy-card` is already position:relative, so it is the anchor.
+ *
+ * The transforms MUST go, and this is the whole reason the modifier exists rather than a docs line:
+ * a transformed element becomes the containing block for its own absolutely-positioned descendants,
+ * so `inset:0` re-anchors from the card to the button's own box the moment the button is hovered or
+ * pressed. Measured: mousedown lands on the button, the overlay collapses under the pointer, mouseup
+ * lands on some other element, and the browser fires `click` on their common ancestor — the button
+ * never gets one. It demos fine on hover for --text/--ghost (their hover is already transform:none)
+ * and only a real press reveals it; the default and --danger fills break one step earlier, on hover.
+ * Press feedback moves to the card, which is the object actually being pressed (see card.css). */
+.fdy-btn--stretch::after{content:'';position:absolute;inset:0;}
+.fdy-btn--stretch:hover,.fdy-btn--stretch:active{transform:none;}
+
 /* Icon-only — square; combine with --ghost/--text/--sm/--lg. Requires aria-label. */
 .fdy-btn--icon{width:var(--control-h);padding:0;}
 .fdy-btn--icon.fdy-btn--sm{width:calc(var(--control-h) - var(--space-2));}
@@ -374,9 +390,13 @@ a { color: var(--color-primary); }
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* Pressing a stretched target (see .fdy-btn--stretch) is pressing the CARD — the button's own
+   nudge had to go, and the object under the pointer is the card. Ordered before the reduced-motion
+   block and the disabled rules so both still win at equal specificity. */
+.fdy-card--interactive:has(.fdy-btn--stretch:active){transform:translateY(-1px);}
 /* The global reduced-motion reset kills the ANIMATION; drop the -3px shift too so the card
  * doesn't jump. The shadow still communicates the affordance. */
-@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover{transform:none;}}
+@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover,.fdy-card--interactive:has(.fdy-btn--stretch:active){transform:none;}}
 /* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
  * announced — reset the UA button box. Note: it does NOT reset background/border, because
  * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
@@ -385,6 +405,17 @@ a { color: var(--color-primary); }
    --interactive lift is withdrawn so a refusing control stops answering the pointer. */
 .fdy-card--button:disabled,.fdy-card--button[aria-disabled="true"],.fdy-card--interactive[aria-disabled="true"]{opacity:.5;cursor:not-allowed;}
 .fdy-card--interactive:disabled:hover,.fdy-card--interactive[aria-disabled="true"]:hover{box-shadow:var(--shadow-lift);transform:none;}
+/* Escape hatches stay clickable above a stretched target — automatic, not a documented convention,
+   because forgetting it fails SILENTLY: the secondary control looks and hovers exactly as before and
+   simply never receives the click, which is the very symptom the pattern exists to cure. Matched by
+   shape (anything focusable) so a control the kit does not ship yet is covered too. */
+.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
+/* The position is a DEFAULT, not an override: z-index needs a positioned box (or a flex/grid item),
+   but an app that deliberately pins a control inside the card — a corner dismiss, a favourite star —
+   must keep its own `position:absolute`. Wrapped in :where() so this whole selector weighs nothing
+   and ANY app rule wins it; measured, because at normal specificity the kit silently dragged an
+   absolutely positioned dismiss button back into the flow. Do not merge these two rules. */
+:where(.fdy-card: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);}
 .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);}
@@ -650,6 +681,22 @@ a { color: var(--color-primary); }
 .fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
 .fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
 
+/* Icon box (#001 §4). The kit ships no icons on purpose, but every icon slot it DOES ship
+   (.fdy-btn__icon, .fdy-nav__icon, .fdy-state__icon) assumes something sensible inside, so a
+   standalone icon had no contract and every app invented one. 1em keeps the glyph matched to the
+   text beside it at every scale — bring your own paths, use our box. Works on the <svg> itself or
+   on a wrapper around it. */
+.fdy-icon{display:inline-block;width:1em;height:1em;flex:none;vertical-align:-0.125em;}
+.fdy-icon>svg{display:block;width:100%;height:100%;}
+
+/* Inline text that carries STATE (#001 §5). The three roles above all de-emphasise; a sentence like
+   "Amount changed from X to Y" or "No approver assigned" needs the opposite, and is neither a badge
+   (those are statuses, not sentences) nor an .fdy-alert (those are blocks, not one line inside a
+   row). Same -strong inks the badges use, gated by contrast.test.mjs on plain surfaces too. */
+.fdy-text-success{color:var(--color-success-strong);}
+.fdy-text-warning{color:var(--color-warning-strong);}
+.fdy-text-danger{color:var(--color-danger-strong);}
+
 /* Freeday — Date picker (input-styled trigger + calendar popover).
  * Built by freeday-datepicker.js from an empty [data-fdy-datepicker] wrapper. */
 .fdy-datepicker{position:relative;display:inline-block;width:100%;max-width:14rem;}
@@ -876,7 +923,10 @@ a { color: var(--color-primary); }
    Neutralise the UA groove border / padding / min-inline-size so it lays out identically to the
    <div> form (min-inline-size:min-content would otherwise block the filterbar column widths). */
 fieldset.fdy-field{border:0;margin:0;padding:0;min-inline-size:0;}
-fieldset.fdy-field>legend{padding:0;float:none;}
+/* The rendered legend is laid out outside the fieldset's flex flow, so `gap` never reaches it —
+   measured 0px between legend and first control. This is the spacing contract a grouped field
+   needs; it matches .fdy-field's own gap so the group reads as one rhythm. */
+fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 .fdy-label{font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-input,.fdy-textarea{width:100%;height:var(--control-h);padding:0 var(--space-3);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);background:var(--color-surface);border:1.5px solid var(--color-control-border);border-radius:var(--radius-md);box-shadow:inset 0 1px 2px rgba(16,14,30,.06);transition:border-color var(--dur-fast) var(--ease-standard),box-shadow var(--dur-fast) var(--ease-standard);}
 .fdy-input::placeholder,.fdy-textarea::placeholder{color:var(--color-text-subtle);}
@@ -900,6 +950,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
+/* Required marker. The control already carries `required`, so the asterisk is decoration: the
+   `/ ""` is CSS alt text — the glyph is painted but exposes NOTHING to the accessibility tree, so a
+   screen reader does not read "star" after every label. That is stricter than a <span> an app has to
+   remember to mark aria-hidden, and it cannot be forgotten. */
+.fdy-label--required::after{content:"*" / "";margin-left:var(--space-1);color:var(--color-danger);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}
 .fdy-help--error{color:var(--color-danger);}
 
@@ -950,7 +1005,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-menu--end{left:auto;right:0;}
 .fdy-menu__item{display:flex;align-items:center;gap:var(--space-2);width:100%;padding:var(--space-2) var(--space-3);border:0;background:transparent;border-radius:var(--radius-sm);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);text-align:left;cursor:pointer;white-space:nowrap;}
 .fdy-menu__item:hover,.fdy-menu__item.is-highlighted{background:var(--color-surface-3);}
-.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);}
+/* Focus is not hover. The enhancer moves real DOM focus (freeday-menu.js `.focus()`), so this is
+   the only thing a keyboard user has to go on — with the hover fill alone, arrowing through the
+   menu is invisible. Same ring as .fdy-nav__item, which got this right. Reported twice. */
+.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
 .fdy-menu__item:disabled{opacity:.5;cursor:not-allowed;background:transparent;}
 .fdy-menu__item--danger{color:var(--color-danger-strong);}
 .fdy-menu__item svg{display:block;width:1rem;height:1rem;flex:none;}

package/docs/getting-started.md

@@ -184,7 +184,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.27.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.29.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": "1.27.0",
+  "version": "1.29.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -71,7 +71,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test 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",
+    "test:browser": "node --test 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",
     "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/button.css

@@ -45,6 +45,22 @@
 .fdy-btn--ghost[aria-pressed="true"],.fdy-btn--text[aria-pressed="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);border-color:var(--color-primary-border);box-shadow:none;}
 .fdy-btn--ghost[aria-pressed="true"]:hover,.fdy-btn--text[aria-pressed="true"]:hover{background:var(--color-primary-soft);transform:none;box-shadow:none;}
 
+/* Stretched hit area (#007) — spread this button's click target over its nearest positioned
+ * ancestor, so "one card, one primary action, one escape hatch" needs no click handler on the
+ * <article>: the real control stays a real <button>/<a> and keeps its keyboard semantics.
+ * `.fdy-card` is already position:relative, so it is the anchor.
+ *
+ * The transforms MUST go, and this is the whole reason the modifier exists rather than a docs line:
+ * a transformed element becomes the containing block for its own absolutely-positioned descendants,
+ * so `inset:0` re-anchors from the card to the button's own box the moment the button is hovered or
+ * pressed. Measured: mousedown lands on the button, the overlay collapses under the pointer, mouseup
+ * lands on some other element, and the browser fires `click` on their common ancestor — the button
+ * never gets one. It demos fine on hover for --text/--ghost (their hover is already transform:none)
+ * and only a real press reveals it; the default and --danger fills break one step earlier, on hover.
+ * Press feedback moves to the card, which is the object actually being pressed (see card.css). */
+.fdy-btn--stretch::after{content:'';position:absolute;inset:0;}
+.fdy-btn--stretch:hover,.fdy-btn--stretch:active{transform:none;}
+
 /* Icon-only — square; combine with --ghost/--text/--sm/--lg. Requires aria-label. */
 .fdy-btn--icon{width:var(--control-h);padding:0;}
 .fdy-btn--icon.fdy-btn--sm{width:calc(var(--control-h) - var(--space-2));}

package/src/components/card.css

@@ -5,9 +5,13 @@
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* Pressing a stretched target (see .fdy-btn--stretch) is pressing the CARD — the button's own
+   nudge had to go, and the object under the pointer is the card. Ordered before the reduced-motion
+   block and the disabled rules so both still win at equal specificity. */
+.fdy-card--interactive:has(.fdy-btn--stretch:active){transform:translateY(-1px);}
 /* The global reduced-motion reset kills the ANIMATION; drop the -3px shift too so the card
  * doesn't jump. The shadow still communicates the affordance. */
-@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover{transform:none;}}
+@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover,.fdy-card--interactive:has(.fdy-btn--stretch:active){transform:none;}}
 /* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
  * announced — reset the UA button box. Note: it does NOT reset background/border, because
  * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
@@ -16,6 +20,17 @@
    --interactive lift is withdrawn so a refusing control stops answering the pointer. */
 .fdy-card--button:disabled,.fdy-card--button[aria-disabled="true"],.fdy-card--interactive[aria-disabled="true"]{opacity:.5;cursor:not-allowed;}
 .fdy-card--interactive:disabled:hover,.fdy-card--interactive[aria-disabled="true"]:hover{box-shadow:var(--shadow-lift);transform:none;}
+/* Escape hatches stay clickable above a stretched target — automatic, not a documented convention,
+   because forgetting it fails SILENTLY: the secondary control looks and hovers exactly as before and
+   simply never receives the click, which is the very symptom the pattern exists to cure. Matched by
+   shape (anything focusable) so a control the kit does not ship yet is covered too. */
+.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
+/* The position is a DEFAULT, not an override: z-index needs a positioned box (or a flex/grid item),
+   but an app that deliberately pins a control inside the card — a corner dismiss, a favourite star —
+   must keep its own `position:absolute`. Wrapped in :where() so this whole selector weighs nothing
+   and ANY app rule wins it; measured, because at normal specificity the kit silently dragged an
+   absolutely positioned dismiss button back into the flow. Do not merge these two rules. */
+:where(.fdy-card: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);}
 .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);}

package/src/components/composition.css

@@ -47,3 +47,19 @@
 .fdy-stats--boxed{background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);gap:0;}
 .fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
 .fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
+
+/* Icon box (#001 §4). The kit ships no icons on purpose, but every icon slot it DOES ship
+   (.fdy-btn__icon, .fdy-nav__icon, .fdy-state__icon) assumes something sensible inside, so a
+   standalone icon had no contract and every app invented one. 1em keeps the glyph matched to the
+   text beside it at every scale — bring your own paths, use our box. Works on the <svg> itself or
+   on a wrapper around it. */
+.fdy-icon{display:inline-block;width:1em;height:1em;flex:none;vertical-align:-0.125em;}
+.fdy-icon>svg{display:block;width:100%;height:100%;}
+
+/* Inline text that carries STATE (#001 §5). The three roles above all de-emphasise; a sentence like
+   "Amount changed from X to Y" or "No approver assigned" needs the opposite, and is neither a badge
+   (those are statuses, not sentences) nor an .fdy-alert (those are blocks, not one line inside a
+   row). Same -strong inks the badges use, gated by contrast.test.mjs on plain surfaces too. */
+.fdy-text-success{color:var(--color-success-strong);}
+.fdy-text-warning{color:var(--color-warning-strong);}
+.fdy-text-danger{color:var(--color-danger-strong);}

package/src/components/input.css

@@ -4,7 +4,10 @@
    Neutralise the UA groove border / padding / min-inline-size so it lays out identically to the
    <div> form (min-inline-size:min-content would otherwise block the filterbar column widths). */
 fieldset.fdy-field{border:0;margin:0;padding:0;min-inline-size:0;}
-fieldset.fdy-field>legend{padding:0;float:none;}
+/* The rendered legend is laid out outside the fieldset's flex flow, so `gap` never reaches it —
+   measured 0px between legend and first control. This is the spacing contract a grouped field
+   needs; it matches .fdy-field's own gap so the group reads as one rhythm. */
+fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 .fdy-label{font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-input,.fdy-textarea{width:100%;height:var(--control-h);padding:0 var(--space-3);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);background:var(--color-surface);border:1.5px solid var(--color-control-border);border-radius:var(--radius-md);box-shadow:inset 0 1px 2px rgba(16,14,30,.06);transition:border-color var(--dur-fast) var(--ease-standard),box-shadow var(--dur-fast) var(--ease-standard);}
 .fdy-input::placeholder,.fdy-textarea::placeholder{color:var(--color-text-subtle);}
@@ -28,5 +31,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
+/* Required marker. The control already carries `required`, so the asterisk is decoration: the
+   `/ ""` is CSS alt text — the glyph is painted but exposes NOTHING to the accessibility tree, so a
+   screen reader does not read "star" after every label. That is stricter than a <span> an app has to
+   remember to mark aria-hidden, and it cannot be forgotten. */
+.fdy-label--required::after{content:"*" / "";margin-left:var(--space-1);color:var(--color-danger);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}
 .fdy-help--error{color:var(--color-danger);}

package/src/components/menu.css

@@ -5,7 +5,10 @@
 .fdy-menu--end{left:auto;right:0;}
 .fdy-menu__item{display:flex;align-items:center;gap:var(--space-2);width:100%;padding:var(--space-2) var(--space-3);border:0;background:transparent;border-radius:var(--radius-sm);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);text-align:left;cursor:pointer;white-space:nowrap;}
 .fdy-menu__item:hover,.fdy-menu__item.is-highlighted{background:var(--color-surface-3);}
-.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);}
+/* Focus is not hover. The enhancer moves real DOM focus (freeday-menu.js `.focus()`), so this is
+   the only thing a keyboard user has to go on — with the hover fill alone, arrowing through the
+   menu is invisible. Same ring as .fdy-nav__item, which got this right. Reported twice. */
+.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
 .fdy-menu__item:disabled{opacity:.5;cursor:not-allowed;background:transparent;}
 .fdy-menu__item--danger{color:var(--color-danger-strong);}
 .fdy-menu__item svg{display:block;width:1rem;height:1rem;flex:none;}