@cahyo-dimas/freeday 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.33.0] — 2026-08-18
+Three notes from the back-office app, four findings, all four executed.
+### Added
+- **`pager={false}` on `FdyTable`** (Vue · React · Blazor). Server mode rendered its own footer
+  unconditionally: `hasPager` was `pageSize > 0 && totalPages > 1` with no way in, so a responsive
+  list — a table at `lg`, `.fdy-list` below it, one pager serving both so the views cannot disagree —
+  showed the kit's footer *and* the app's, stacked, on every list with more than one page. The only
+  workaround was `display:none` on `.fdy-table-footer`, an app reaching into a component's internals.
+  Client mode already had its hatch (`pageIndex`); this gives server mode one, and in server mode it
+  is the honest shape — the app owns the page there anyway, it was simply being handed a second
+  control.
+- **`usePopover` is exported from the Vue adapter.** Every kit dropdown uses it to escape an
+  ancestor's overflow clip (`.fdy-card` is `overflow:hidden`, so a panel inside one is cut at the
+  card's edge), and a consuming app that had to build a control the kit does not ship had to
+  re-implement it — ~70 lines, from the kit's own description, that will not improve when the kit's
+  positioning does. *Correction to the report: React has exported it all along; only Vue was missing
+  it. Blazor has no composable layer — its panels go through the JS bridge.*
+- **Quiet destructive buttons.** `--danger` was the solid treatment and nothing else, so
+  `fdy-btn--ghost fdy-btn--danger` — which every reader parses as "quiet destructive" — rendered a
+  second SOLID button. That is a hierarchy defect: the base class is already the one primary per
+  screen, and a solid Delete beside Save is a second primary in all but name.
+  `.fdy-menu__item--danger` has always modelled the quiet form; it now reaches `.fdy-btn`.
+### Fixed
+- **`.fdy-eyebrow` and `.fdy-nav__grouplabel` spend a text ink.** Both set type in
+  `--color-text-subtle`, which is gated at 3.0 *by design* (placeholders, separators, decorative
+  glyphs) and measures 4.41:1 — axe reports it as a serious `color-contrast` failure. Identical to
+  `.fdy-stat__label` in 1.30.0, one release earlier: same ink, same 4.41, same argument.
+  The nav group label is the one the report did not know about — the sweep it asked for found it,
+  and that rule was *already* brightening to `--color-text-muted` on hover, which is the CSS
+  admitting its resting state was too faint.
+### Notes on the shape of the fix
+- The report proposed scoping the solid danger with `:not(.fdy-btn--ghost):not(.fdy-btn--text)`.
+  Shipped without it: the pairing rules are more specific and come later, so they already win —
+  the `:not()` would be a second mechanism expressing the same intent, and the mutation run proved
+  it changed nothing.
+- **A regression written and caught inside this change:** Vue casts an omitted Boolean prop to
+  `false`, not `undefined`, so `props.pager !== false` withheld the footer from every table that
+  never mentions `pager`. The existing controlled-`pageIndex` guard failed within seconds. `pager`
+  now goes through `withDefaults`, the same trap `FdyModal`'s `dismissible` hit in v1.18.0.
+### Added — guards
+- **The prose-ink invariant** note 007 asked for: any rule that sets a `font-size` *and* spends
+  `--color-text-subtle` is typesetting prose in an ink gated for decoration, and fails. Matched by
+  shape, not by a list of names, so the third instance cannot arrive the way the second did. Two
+  documented exemptions carry their reason.
+- `pager={false}` is measured in a real browser with two tables sharing one server page state: the
+  footer must be **absent from the DOM**, not hidden (a visually hidden pager is still a tab stop
+  and still announced), and the other table's pager must still work.
+- Quiet destructive is measured as a rendered `background-image`, the same reason the `aria-pressed`
+  fills are: a gradient is a background-*image*, so the CSS reads fine either way and only the engine
+  shows which treatment won.
+
+## [1.32.1] — 2026-08-18
+Docs only. Asked by a consumer: *"if I upgrade, will the agent in my project know what it gained?"*
+The answer was no, and two reasons why.
+### Fixed
+- **`docs/agent-onboarding.md` never mentioned the changelog.** It is the file a consuming agent
+  reads first, and it listed everything in the package except the one file that says what changed
+  between the version the project had and the one it now has. It now points at
+  `node_modules/@cahyo-dimas/freeday/CHANGELOG.md` explicitly, plus a short *reach for this instead
+  of hand-rolling that* table covering the last nine releases — the additions most likely to replace
+  something an app already worked around.
+- **Three classes existed only in shorthand** in `COMPONENTS.md` — `.fdy-label--required`,
+  `.fdy-cal__month` and `.fdy-cal__grid--months` were written as `(+--required)` and `__month`, so
+  the full name appeared **zero** times and a grep for the class found nothing. The drift guard
+  cannot see this either: it verifies fully-written names and skips shorthand by design, so a class
+  introduced only in shorthand is invisible to both the reader and the test.
+
 ## [1.32.0] — 2026-08-18
 Improvement note 004, both halves: a calendar you could not steer, and a check mark that talked.
 ### Added

package/COMPONENTS.md

@@ -259,6 +259,11 @@ a compact root with one region opted back out (shared chrome that must match a s
 </button>
 ```
 
+**Quiet destructive:** combine `--danger` with `--ghost` or `--text`. The ground stays quiet and only
+the ink turns red — `.fdy-menu__item--danger` has always worked this way. Use it whenever Delete
+shares a screen with the one primary action; a solid Delete beside Save is a second primary in all
+but name.
+
 ## FAB — `.fdy-fab`
 Floating circular action. Modifiers: `--sm` `--accent` `--danger` `--extended` (pill with a label).
 Always `aria-label` unless `--extended` carries visible text.
@@ -307,7 +312,7 @@ native control, otherwise a `<div>` + explicitly associated label.
 </fieldset>
 ```
 
-**`--required` marks the label, not the accessibility tree.** The control already carries
+**`.fdy-label--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.
@@ -517,7 +522,8 @@ Input-styled trigger + calendar popover. Needs `freeday-datepicker.js`. **Author
   get `data-role="from"` / `"to"`; separator `.fdy-daterange__sep`. The end can't precede the start.
   **Typed wrapper: `<FdyDateRange>`** (Vue/React/Blazor) — use it in those stacks.
 **Getting to a distant month.** The title is a **button**: press it and the day grid becomes a
-12-cell month grid for the current year, where the arrows step **years** instead of months. Pick a
+12-cell month grid (`.fdy-cal__grid--months` of `.fdy-cal__month`) for the current year, where the
+arrows step **years** instead of months. Pick a
 month and you are back on days — choosing a month is navigation, so nothing is committed until a day
 is selected. From August 2026 to March 2022 that is 7 clicks; walking month by month is 53.
 
@@ -716,6 +722,18 @@ accessible name (`Filter <column>`) — a dialog named after its trigger is the
 Playwright/Testing-Library suite that means `getByLabel('Filter Name')` resolves to two elements;
 reach for `getByRole('button', { name: 'Filter Name' })` instead.
 
+**Who draws the pager.** The table renders its own footer (range + pager) whenever there is more
+than one page. Two ways to take it over:
+
+- **client mode** — pass `pageIndex` (with `pageSize`, without `page`) and drive it yourself;
+- **either mode** — pass `pager={false}` (Vue `:pager="false"`, Blazor `Pager="false"`) and render
+  your own control. In server mode this is the only way: the app already owns the page there, and
+  was still being handed a second control. The typical shape is a responsive list — a table at `lg`,
+  `.fdy-list` below it — where one pager has to serve both views so they cannot disagree.
+
+Do not hide the footer with CSS. `display:none` works, but it reaches into a component's internals
+and breaks the moment the class changes.
+
 ## Pagination — `.fdy-pagination`
 The block class on the `<nav>` is a **structural hook only** — it carries no rule of its own; the
 `__list` / `__link` / `__ellipsis` elements do all the styling, and the data table targets

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.32.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.32.0)
+[![Release](https://img.shields.io/badge/release-v1.33.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.33.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.32.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.32.0)
+[![Release](https://img.shields.io/badge/release-v1.33.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.33.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/FdyTable.razor.cs

@@ -36,6 +36,11 @@ public partial class FdyTable<TRow>
     /// the <c>md</c> breakpoint and renders a card list from <see cref="Process"/> can render one pager
     /// for both breakpoints and bind it here. Leave null for the internal index (unchanged default).
     /// </summary>
+    /// <summary>Withhold the table's own footer (pager + range) so the screen can render one.
+    /// Server mode had no way to do this: the app owns the page there anyway, and was still handed a
+    /// second control. Client mode's counterpart is <see cref="PageIndex"/>. Default true.</summary>
+    [Parameter] public bool Pager { get; set; } = true;
+
     [Parameter] public int? PageIndex { get; set; }
 
     /// <summary>Raised in client mode with <see cref="PageIndex"/> set: the table asks for a new
@@ -97,7 +102,7 @@ public partial class FdyTable<TRow>
     private int CurrentPage1 => (ServerPaged ? Page!.Index : ClientPageIndex) + 1;
     private int TotalCount => _totalCount;
     private int TotalPages => PageSizeEff > 0 ? Math.Max(1, (int)Math.Ceiling((double)TotalCount / PageSizeEff)) : 1;
-    private bool HasPager => PageSizeEff > 0 && TotalPages > 1;
+    private bool HasPager => Pager && PageSizeEff > 0 && TotalPages > 1;
     private List<int?> Pages => TableModel.PageWindow(CurrentPage1, TotalPages);
     private int RangeFrom => TotalCount == 0 ? 0 : (CurrentPage1 - 1) * PageSizeEff + 1;
     private int RangeTo => TotalCount == 0 ? 0 : RangeFrom - 1 + _displayRows.Count;

package/adapters/react/components/FdyTable.tsx

@@ -51,6 +51,11 @@ export interface FdyTableProps<Row extends object> {
    * card list from `onProcess` can render one pager for both breakpoints and point it here.
    * Omit for the internal index (unchanged default).
    */
+  /** Withhold the table's own footer (pager + range) so the screen can render one. Server mode had
+   *  no way to do this: the app owns the page there ANYWAY, and was still handed a second control —
+   *  a responsive list that shows a table at one breakpoint and cards at another ended up with the
+   *  kit's pager stacked under its own. Client mode's counterpart is `pageIndex`. Default true. */
+  pager?: boolean;
   pageIndex?: number;
   /** Client mode with `pageIndex` provided: the table asks for a new 0-based index (pager click, a
    *  reset to 0 after sort/filter, or a clamp when filtering shrank the set). */
@@ -127,7 +132,7 @@ export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Ele
   const pageSizeEff: number = serverPaged ? (props.page as FdyPageState).size : (props.pageSize ?? 0);
   const currentPage1: number = (serverPaged ? (props.page as FdyPageState).index : clientPageIndex) + 1;
   const totalPages: number = pageSizeEff > 0 ? Math.max(1, Math.ceil(totalCount / pageSizeEff)) : 1;
-  const hasPager: boolean = pageSizeEff > 0 && totalPages > 1;
+  const hasPager: boolean = props.pager !== false && pageSizeEff > 0 && totalPages > 1;
   const pages: Array<number | 'ellipsis'> = pageWindow(currentPage1, totalPages);
   const rangeFrom: number = totalCount === 0 ? 0 : (currentPage1 - 1) * pageSizeEff + 1;
   const rangeTo: number = totalCount === 0 ? 0 : rangeFrom - 1 + displayRows.length;

package/adapters/vue/components/FdyTable.vue

@@ -29,7 +29,10 @@ import FdyTableFilter from './FdyTableFilter.vue';
 //     (`update:sort` / `update:filters` / `update:page`) for the caller to feed back into its query.
 // Column filters (text/enum/number/date) apply live; in server mode, debounce the emit if needed.
 
-const props = defineProps<{
+/* `pager` MUST go through withDefaults: Vue's boolean-cast gives an omitted Boolean prop `false`,
+   not `undefined`, so a plain `props.pager !== false` would withhold the footer from every table that
+   never mentions it. Same trap as FdyModal's `dismissible`. */
+const props = withDefaults(defineProps<{
   columns: ReadonlyArray<FdyTableColumn<Row>>;
   rows: ReadonlyArray<Row>;
   rowKey: (row: Row) => string | number;
@@ -48,6 +51,11 @@ const props = defineProps<{
    * card list from the `process` event can render one pager for both breakpoints and point it here.
    * Omit for the internal index (unchanged default).
    */
+  /** Withhold the table's own footer (pager + range) so the screen can render one. Server mode had
+   *  no way to do this: the app owns the page there ANYWAY, and was still handed a second control —
+   *  a responsive list that shows a table at one breakpoint and cards at another ended up with the
+   *  kit's pager stacked under its own. Client mode's counterpart is `pageIndex`. Default true. */
+  pager?: boolean;
   pageIndex?: number;
   loading?: boolean;
   emptyText?: string;
@@ -58,7 +66,7 @@ const props = defineProps<{
   rowClass?: (row: Row) => string | undefined;
   /** Controlled: row keys whose `row-detail` slot is shown as a full-width row beneath them. */
   expandedKeys?: ReadonlyArray<string | number>;
-}>();
+}>(), { pager: true });
 
 const emit = defineEmits<{
   'update:sort': [sort: FdySortState | null];
@@ -137,7 +145,7 @@ const currentPage1: ComputedRef<number> = computed((): number =>
 const totalPages: ComputedRef<number> = computed((): number =>
   pageSizeEff.value > 0 ? Math.max(1, Math.ceil(totalCount.value / pageSizeEff.value)) : 1,
 );
-const hasPager: ComputedRef<boolean> = computed((): boolean => pageSizeEff.value > 0 && totalPages.value > 1);
+const hasPager: ComputedRef<boolean> = computed((): boolean => props.pager !== false && pageSizeEff.value > 0 && totalPages.value > 1);
 const pages: ComputedRef<Array<number | 'ellipsis'>> = computed((): Array<number | 'ellipsis'> =>
   pageWindow(currentPage1.value, totalPages.value),
 );

package/adapters/vue/index.d.ts

@@ -12,6 +12,19 @@ export interface UseFreedayReturn {
  */
 export declare function useFreeday(rootRef?: Ref<HTMLElement | null>): UseFreedayReturn;
 
+/**
+ * Anchor a dropdown panel to its trigger in the top layer, so it escapes any ancestor overflow clip
+ * — `.fdy-card` is `overflow:hidden`, so a panel positioned inside one is otherwise cut at the card's
+ * edge. The panel element must carry `popover="manual"`. This is the plumbing every kit dropdown
+ * uses; it is exported so a control the kit does not ship can behave like one that it does, instead
+ * of each app re-implementing it from the description.
+ */
+export declare function usePopover(
+  panelRef: Ref<HTMLElement | null>,
+  triggerRef: Ref<HTMLElement | null>,
+  open: Ref<boolean>,
+): void;
+
 export { default as FdyCombo } from './components/FdyCombo.vue';
 export { default as FdyDatepicker } from './components/FdyDatepicker.vue';
 export { default as FdyDateRange } from './components/FdyDateRange.vue';

package/adapters/vue/index.js

@@ -1,4 +1,5 @@
 export { useFreeday } from './useFreeday.js';
+export { usePopover } from './usePopover.ts';
 export { default as FdyCombo } from './components/FdyCombo.vue';
 export { default as FdyDatepicker } from './components/FdyDatepicker.vue';
 export { default as FdyDateRange } from './components/FdyDateRange.vue';

package/dist/freeday.bundle.css

@@ -510,7 +510,11 @@ a { color: var(--color-primary); }
 /* Collapsible section: <details class="fdy-nav__group"><summary class="fdy-nav__grouplabel"> */
 .fdy-nav__group{margin:0;}
 .fdy-nav__group + .fdy-nav__group,.fdy-nav__item + .fdy-nav__group{border-top:var(--bw) solid var(--color-border-muted);margin-top:var(--space-1);padding-top:var(--space-1);}
-.fdy-nav__grouplabel{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);padding:var(--space-3) var(--space-3) var(--space-1);font-size:var(--text-xs);text-transform:uppercase;letter-spacing:var(--tracking-wide);font-weight:var(--weight-semibold);color:var(--color-text-subtle);}
+/* Prose, and a control name: this is the <summary> of a nav group, at --text-xs uppercase. It is
+   the second class found spending the decorative ink on type (after .fdy-eyebrow) — and it was
+   already brightening to --color-text-muted on hover, which is the rule admitting its resting
+   state was too faint to read. */
+.fdy-nav__grouplabel{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);padding:var(--space-3) var(--space-3) var(--space-1);font-size:var(--text-xs);text-transform:uppercase;letter-spacing:var(--tracking-wide);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
 .fdy-nav__grouplabel::-webkit-details-marker{display:none;}
 .fdy-nav__grouplabel:hover{color:var(--color-text-muted);}
 .fdy-nav__grouplabel:focus-visible{outline:none;border-radius:var(--radius-sm);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
@@ -702,9 +706,20 @@ a { color: var(--color-primary); }
 .fdy-btn--ghost:hover{transform:none;background:var(--color-primary-soft);border-color:var(--color-primary-border);box-shadow:var(--shadow-1);}
 .fdy-btn--ghost:active{transform:translateY(1px);}
 
+/* --danger used to be the SOLID treatment and nothing else, so `fdy-btn--ghost fdy-btn--danger` —
+   which every reader parses as "quiet destructive" — rendered a second SOLID button beside Save.
+   That is a hierarchy defect, not a cosmetic one: the base class is already the one primary per
+   screen. `.fdy-menu__item--danger` has always modelled the quiet form (red text, not a red block);
+   the pairing rules below bring it to the button. They are more specific than this one and come
+   after it, so this rule needs no :not() guard of its own — one mechanism, not two. */
 .fdy-btn--danger{background:linear-gradient(180deg,var(--color-danger-btn),color-mix(in srgb,#000 12%,var(--color-danger-btn)));color:var(--color-on-danger);box-shadow:0 2px 9px -1px color-mix(in srgb,var(--color-danger-btn) 46%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-danger-btn) 54%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:active{transform:translateY(1px);}
+/* Quiet destructive: the variant keeps its own ground and only the ink turns. */
+.fdy-btn--ghost.fdy-btn--danger{background:transparent;color:var(--color-danger-strong);border-color:color-mix(in srgb,var(--color-danger) 40%,transparent);box-shadow:none;}
+.fdy-btn--ghost.fdy-btn--danger:hover{background:var(--color-danger-soft);border-color:var(--color-danger);color:var(--color-danger-strong);}
+.fdy-btn--text.fdy-btn--danger{background:none;color:var(--color-danger-strong);border-color:transparent;box-shadow:none;}
+.fdy-btn--text.fdy-btn--danger:hover{background:var(--color-danger-soft);color:var(--color-danger-strong);}
 .fdy-btn--danger[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 14%,var(--color-danger-btn)),var(--color-danger-btn));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 24%,transparent);}
 
 .fdy-btn--sm{height:calc(var(--control-h) - var(--space-2));padding:0 var(--space-3);font-size:var(--text-xs);border-radius:var(--radius-sm);}
@@ -1032,7 +1047,11 @@ a { color: var(--color-primary); }
 /* ---- Type roles (three title levels + supporting text) -------------------------------------
  * One role per level of hierarchy. Reach for these instead of re-using .fdy-card__title for a
  * page title (the mistake that collapses three levels into one grey mush). */
-.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+/* --color-text-muted, not -subtle: an eyebrow is a small label naming the thing below it, i.e.
+   prose. -subtle is gated at 3.0 on purpose (placeholders, separators, decorative glyphs) and
+   measures 4.41 on the page ground — axe reports it as a serious color-contrast failure. Same
+   argument, same ink, same 4.41 as .fdy-stat__label in 1.30.0. */
+.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-muted);}
 .fdy-title-page{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:var(--leading-tight);color:var(--color-text);margin:0;text-wrap:balance;}
 .fdy-title-section{font-family:var(--font-display);font-size:var(--text-xl);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);line-height:var(--leading-snug);color:var(--color-text);margin:0;text-wrap:balance;}
 .fdy-title-card{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;}

package/dist/freeday.css

@@ -127,7 +127,11 @@ a { color: var(--color-primary); }
 /* Collapsible section: <details class="fdy-nav__group"><summary class="fdy-nav__grouplabel"> */
 .fdy-nav__group{margin:0;}
 .fdy-nav__group + .fdy-nav__group,.fdy-nav__item + .fdy-nav__group{border-top:var(--bw) solid var(--color-border-muted);margin-top:var(--space-1);padding-top:var(--space-1);}
-.fdy-nav__grouplabel{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);padding:var(--space-3) var(--space-3) var(--space-1);font-size:var(--text-xs);text-transform:uppercase;letter-spacing:var(--tracking-wide);font-weight:var(--weight-semibold);color:var(--color-text-subtle);}
+/* Prose, and a control name: this is the <summary> of a nav group, at --text-xs uppercase. It is
+   the second class found spending the decorative ink on type (after .fdy-eyebrow) — and it was
+   already brightening to --color-text-muted on hover, which is the rule admitting its resting
+   state was too faint to read. */
+.fdy-nav__grouplabel{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);padding:var(--space-3) var(--space-3) var(--space-1);font-size:var(--text-xs);text-transform:uppercase;letter-spacing:var(--tracking-wide);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
 .fdy-nav__grouplabel::-webkit-details-marker{display:none;}
 .fdy-nav__grouplabel:hover{color:var(--color-text-muted);}
 .fdy-nav__grouplabel:focus-visible{outline:none;border-radius:var(--radius-sm);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
@@ -319,9 +323,20 @@ a { color: var(--color-primary); }
 .fdy-btn--ghost:hover{transform:none;background:var(--color-primary-soft);border-color:var(--color-primary-border);box-shadow:var(--shadow-1);}
 .fdy-btn--ghost:active{transform:translateY(1px);}
 
+/* --danger used to be the SOLID treatment and nothing else, so `fdy-btn--ghost fdy-btn--danger` —
+   which every reader parses as "quiet destructive" — rendered a second SOLID button beside Save.
+   That is a hierarchy defect, not a cosmetic one: the base class is already the one primary per
+   screen. `.fdy-menu__item--danger` has always modelled the quiet form (red text, not a red block);
+   the pairing rules below bring it to the button. They are more specific than this one and come
+   after it, so this rule needs no :not() guard of its own — one mechanism, not two. */
 .fdy-btn--danger{background:linear-gradient(180deg,var(--color-danger-btn),color-mix(in srgb,#000 12%,var(--color-danger-btn)));color:var(--color-on-danger);box-shadow:0 2px 9px -1px color-mix(in srgb,var(--color-danger-btn) 46%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-danger-btn) 54%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:active{transform:translateY(1px);}
+/* Quiet destructive: the variant keeps its own ground and only the ink turns. */
+.fdy-btn--ghost.fdy-btn--danger{background:transparent;color:var(--color-danger-strong);border-color:color-mix(in srgb,var(--color-danger) 40%,transparent);box-shadow:none;}
+.fdy-btn--ghost.fdy-btn--danger:hover{background:var(--color-danger-soft);border-color:var(--color-danger);color:var(--color-danger-strong);}
+.fdy-btn--text.fdy-btn--danger{background:none;color:var(--color-danger-strong);border-color:transparent;box-shadow:none;}
+.fdy-btn--text.fdy-btn--danger:hover{background:var(--color-danger-soft);color:var(--color-danger-strong);}
 .fdy-btn--danger[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 14%,var(--color-danger-btn)),var(--color-danger-btn));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 24%,transparent);}
 
 .fdy-btn--sm{height:calc(var(--control-h) - var(--space-2));padding:0 var(--space-3);font-size:var(--text-xs);border-radius:var(--radius-sm);}
@@ -649,7 +664,11 @@ a { color: var(--color-primary); }
 /* ---- Type roles (three title levels + supporting text) -------------------------------------
  * One role per level of hierarchy. Reach for these instead of re-using .fdy-card__title for a
  * page title (the mistake that collapses three levels into one grey mush). */
-.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+/* --color-text-muted, not -subtle: an eyebrow is a small label naming the thing below it, i.e.
+   prose. -subtle is gated at 3.0 on purpose (placeholders, separators, decorative glyphs) and
+   measures 4.41 on the page ground — axe reports it as a serious color-contrast failure. Same
+   argument, same ink, same 4.41 as .fdy-stat__label in 1.30.0. */
+.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-muted);}
 .fdy-title-page{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:var(--leading-tight);color:var(--color-text);margin:0;text-wrap:balance;}
 .fdy-title-section{font-family:var(--font-display);font-size:var(--text-xl);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);line-height:var(--leading-snug);color:var(--color-text);margin:0;text-wrap:balance;}
 .fdy-title-card{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;}

package/docs/agent-onboarding.md

@@ -91,6 +91,7 @@ Blazor). Then verify the agent can actually read those files — an agent that c
 | `docs/integrations.md` | How to bridge third-party libraries (validation, charts, dates, i18n…). |
 | `docs/reference-screen.html` | A full screen assembled from the shell down. Open it in a browser. |
 | `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 — linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
 | `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. |
@@ -101,6 +102,28 @@ The live docs (with an interactive playground) are at
 apps under `examples/` (Vue, React, Blazor) that are **not** in the npm tarball — is at
 <https://github.com/cahyo-dimas/freeday-ui-kit>.
 
+### After an upgrade, read the changelog first
+
+`npm i @cahyo-dimas/freeday@latest` does not tell you what you gained. Read
+`node_modules/@cahyo-dimas/freeday/CHANGELOG.md` down to the version this project was on before —
+it is written for exactly this moment, and it is the difference between adopting a new affordance
+and re-implementing it locally.
+
+Recent additions most likely to replace something an app hand-rolled (all detailed in
+`COMPONENTS.md`):
+
+| Reach for | Instead of |
+|---|---|
+| `.fdy-btn--stretch` | a hand-rolled overlay to make a card or list row clickable |
+| `[data-fdy-number]` | a bare `<input type="number">` with the browser's own spin buttons |
+| `clearable` on `FdyCfl` / `FdyDatepicker` | a value that can be set but never unset |
+| `row.waiting(label)` on an upload row | a second status line saying the server is still working |
+| `.fdy-label--required` | a `<span>` asterisk you have to remember to `aria-hidden` |
+| `.fdy-text-warning` / `-danger` / `-success` | a caption class on a line that should stand out |
+| `.fdy-icon` | your own `width:1em;height:1em` rule, once per project |
+| `data-density="comfortable"` | restating the default spacing tokens on a wrapper |
+| the calendar's month grid (press the title) | clicking "previous month" thirty times |
+
 ## 3. Starting a new screen
 
 The order matters; skipping to components is what produces flat, identical-card screens.

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.32.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.33.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/docs/integrations.md

@@ -319,3 +319,17 @@ web-based add-ons (Service Layer + .NET), Freeday + enhancers over JS interop wo
 *Library recommendations reflect what's common and stable as of 2026; choose based on your
 project's license and bundle-size budget. Freeday locks you into none of them — everything is
 optional and replaceable.*
+
+## Building a control the kit does not ship
+
+Use the `app-` prefix for its classes, and reuse the kit's plumbing rather than re-deriving it:
+
+```ts
+import { usePopover } from '@cahyo-dimas/freeday/vue';   // or '/react'
+usePopover(panelRef, triggerRef, open);                  // panel needs popover="manual"
+```
+
+This is what every kit dropdown uses to escape an ancestor's overflow clip — `.fdy-card` is
+`overflow:hidden`, so a panel positioned inside one is otherwise cut at the card's edge. It is
+exported so a control you build behaves like one the kit ships, and improves when the kit's
+positioning does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",

package/src/components/app-shell.css

@@ -48,7 +48,11 @@
 /* Collapsible section: <details class="fdy-nav__group"><summary class="fdy-nav__grouplabel"> */
 .fdy-nav__group{margin:0;}
 .fdy-nav__group + .fdy-nav__group,.fdy-nav__item + .fdy-nav__group{border-top:var(--bw) solid var(--color-border-muted);margin-top:var(--space-1);padding-top:var(--space-1);}
-.fdy-nav__grouplabel{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);padding:var(--space-3) var(--space-3) var(--space-1);font-size:var(--text-xs);text-transform:uppercase;letter-spacing:var(--tracking-wide);font-weight:var(--weight-semibold);color:var(--color-text-subtle);}
+/* Prose, and a control name: this is the <summary> of a nav group, at --text-xs uppercase. It is
+   the second class found spending the decorative ink on type (after .fdy-eyebrow) — and it was
+   already brightening to --color-text-muted on hover, which is the rule admitting its resting
+   state was too faint to read. */
+.fdy-nav__grouplabel{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);padding:var(--space-3) var(--space-3) var(--space-1);font-size:var(--text-xs);text-transform:uppercase;letter-spacing:var(--tracking-wide);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
 .fdy-nav__grouplabel::-webkit-details-marker{display:none;}
 .fdy-nav__grouplabel:hover{color:var(--color-text-muted);}
 .fdy-nav__grouplabel:focus-visible{outline:none;border-radius:var(--radius-sm);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}

package/src/components/button.css

@@ -23,9 +23,20 @@
 .fdy-btn--ghost:hover{transform:none;background:var(--color-primary-soft);border-color:var(--color-primary-border);box-shadow:var(--shadow-1);}
 .fdy-btn--ghost:active{transform:translateY(1px);}
 
+/* --danger used to be the SOLID treatment and nothing else, so `fdy-btn--ghost fdy-btn--danger` —
+   which every reader parses as "quiet destructive" — rendered a second SOLID button beside Save.
+   That is a hierarchy defect, not a cosmetic one: the base class is already the one primary per
+   screen. `.fdy-menu__item--danger` has always modelled the quiet form (red text, not a red block);
+   the pairing rules below bring it to the button. They are more specific than this one and come
+   after it, so this rule needs no :not() guard of its own — one mechanism, not two. */
 .fdy-btn--danger{background:linear-gradient(180deg,var(--color-danger-btn),color-mix(in srgb,#000 12%,var(--color-danger-btn)));color:var(--color-on-danger);box-shadow:0 2px 9px -1px color-mix(in srgb,var(--color-danger-btn) 46%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-danger-btn) 54%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:active{transform:translateY(1px);}
+/* Quiet destructive: the variant keeps its own ground and only the ink turns. */
+.fdy-btn--ghost.fdy-btn--danger{background:transparent;color:var(--color-danger-strong);border-color:color-mix(in srgb,var(--color-danger) 40%,transparent);box-shadow:none;}
+.fdy-btn--ghost.fdy-btn--danger:hover{background:var(--color-danger-soft);border-color:var(--color-danger);color:var(--color-danger-strong);}
+.fdy-btn--text.fdy-btn--danger{background:none;color:var(--color-danger-strong);border-color:transparent;box-shadow:none;}
+.fdy-btn--text.fdy-btn--danger:hover{background:var(--color-danger-soft);color:var(--color-danger-strong);}
 .fdy-btn--danger[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 14%,var(--color-danger-btn)),var(--color-danger-btn));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 24%,transparent);}
 
 .fdy-btn--sm{height:calc(var(--control-h) - var(--space-2));padding:0 var(--space-3);font-size:var(--text-xs);border-radius:var(--radius-sm);}

package/src/components/composition.css

@@ -9,7 +9,11 @@
 /* ---- Type roles (three title levels + supporting text) -------------------------------------
  * One role per level of hierarchy. Reach for these instead of re-using .fdy-card__title for a
  * page title (the mistake that collapses three levels into one grey mush). */
-.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+/* --color-text-muted, not -subtle: an eyebrow is a small label naming the thing below it, i.e.
+   prose. -subtle is gated at 3.0 on purpose (placeholders, separators, decorative glyphs) and
+   measures 4.41 on the page ground — axe reports it as a serious color-contrast failure. Same
+   argument, same ink, same 4.41 as .fdy-stat__label in 1.30.0. */
+.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-muted);}
 .fdy-title-page{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:var(--leading-tight);color:var(--color-text);margin:0;text-wrap:balance;}
 .fdy-title-section{font-family:var(--font-display);font-size:var(--text-xl);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);line-height:var(--leading-snug);color:var(--color-text);margin:0;text-wrap:balance;}
 .fdy-title-card{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;}