@cahyo-dimas/freeday 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -3,6 +3,94 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+**Kebijakan tipe (sejak 2.1.0).** Tipe publik yang **melebar** dihitung breaking meski runtime tak
+berubah, karena yang gagal adalah build konsumen: `vue-tsc`/`tsc` menolak handler yang kemarin
+benar. Perubahan seperti itu ditulis di bawah `### Changed: BREAKING (types)` — nama prop, tipe
+lama → tipe baru, dan cara menyempitkannya — bukan di bawah `### Added`, betapapun aditifnya dari
+sisi kit.
+
+## [2.1.0] - 2026-08-25
+### Added
+- **`singleRow()`, exported from `@cahyo-dimas/freeday/vue` and `/react`** (#045). `FdyCfl` emits
+  `Row | Row[] | null` whatever its props are: the array is reachable only under `multiple`, the
+  null only under `clearable`, and the type cannot say which. So every single-select screen wrote
+  its own narrowing, and each one differently — a cast (which hides the day somebody adds
+  `clearable`), a silent ignore, or a throw. One implementation now lives in
+  `adapters/core/cfl-value.js` and both adapters re-export it: it returns `Row | null`, and
+  **throws** a `TypeError` on an array instead of keeping its first row, because quietly dropping
+  the rest is how a `multiple` added later goes unnoticed. Blazor never needed it — multi-select
+  there is a separate `Values` / `ValuesChanged` pair.
+  ```ts
+  import { singleRow } from '@cahyo-dimas/freeday/vue'; // or '@cahyo-dimas/freeday/react'
+  // (value: CflRow | CflRow[] | null) => CflRow | null
+  const onUpdate = (value: CflRow | CflRow[] | null): void => { picked.value = singleRow(value); };
+  ```
+### Changed: BREAKING (types)
+- **A retroactive entry for 1.29.0 and 1.42.0** (#045) — nothing changed in this release; this is
+  the record those two are missing. Both widened `FdyCfl`'s emitted type — `Row` → `Row | null`
+  (1.29.0, with `clearable`) → `Row | Row[] | null` (1.42.0, with `multiple`) — and both shipped
+  under **Added**, which is honest from the kit's side and useless from the consumer's: the
+  combined effect is `vue-tsc` failing in a handler nobody touched. An app upgrading from before
+  1.29.0 meets both at once, which is exactly how it was reported. Migration is `singleRow()`
+  above. The policy that should stop a third instance is at the top of this file.
+### Added: guards
+- **The typed column contract is now pinned in both directions** (#040): `test/docs.test.mjs`
+  asserts the field list documented in `COMPONENTS.md` matches `FdyTableColumn` in
+  `adapters/core/table-model.d.ts` — a field in the type but not the docs fails, and so does a
+  field in the docs that the type does not have. Verified by mutation (drop `labelHidden` from the
+  table → red; invent a `sticky` row → red), since a guard nobody has watched fail is only a
+  green tick.
+- `test/cfl-value.test.mjs`: three tests for `singleRow` (row passes through, `null`/`undefined`
+  become null, an array throws).
+- **Every typed wrapper's props are pinned to their documentation** (`NEXT-UP.md` #11). One guard
+  reads all twelve `### Props — <FdyX>` tables and compares them with the Vue and React
+  declarations: a prop missing from a table fails, a documented prop neither adapter declares
+  fails, and a wrapper exported with no table at all fails. Mutation-verified in all three
+  directions, including the case that found a bug in the guard itself — a hyphenated prop name
+  (`aria-label`) was invisible to the first version of its parser.
+### Docs
+- **`COMPONENTS.md` finally states the typed column contract** (#040). §Data table gained
+  "Columns — the typed `FdyTableColumn<T>`": all ten fields with their types, the Blazor spelling
+  (`PascalCase`, `required` Key/Label, the extra `Cell` slot), and the row-controls example.
+  `agent-onboarding.md` tells every consuming agent this file is closed — "if a class is not in
+  that file, it does not exist" — while three of the four stacks build a table only through
+  `columns`, whose shape appeared nowhere in it. One reporting app shipped `label: ''` on its
+  actions column as a result: a `<th>` announced as nothing.
+- **Nine enhancers still claimed to be Indonesian.** The comment above every `TEXT` table read
+  "User-facing strings. Indonesian by default" — written before 2.0.0 flipped them all to English,
+  and shipped in `dist/`, where it is the first thing a consumer reading the source sees. It now
+  says English, names `data-fdy-text-<key>` as the override, and gives an Indonesian app on the
+  raw path as the example of who overrides.
+- **The two docs a consumer actually reads on upgrade now mention the language.** 2.0.0's breaking
+  change was documented in `COMPONENTS.md` and this file, but neither `docs/getting-started.md` nor
+  the block projects paste into their agent instructions
+  (`docs/agent-onboarding.md`) said a word about it. Both now do, with `data-fdy-text-<key>` as the
+  whole migration and `<html lang>` for date names.
+- **`HANDOFF.md` described a release that had already happened.** It stated npm was on 1.53.0 with
+  1.54.0 and 2.0.0 sitting unpushed; npm had been on 2.0.0 since the morning, with the tag, the
+  branch and `origin/main` all on the same commit. The file that warns about stale snapshots was
+  the stale snapshot. Corrected, with the three commands that check it.
+- **`CLAUDE.md` claimed 44 components**, a number matching nothing countable. Now 48 stylesheets in
+  `src/components/` and 26 enhancers in `src/freeday-*.js`, both of which anyone can re-count.
+- **The typed props of all twelve wrappers are now in `COMPONENTS.md`** (`NEXT-UP.md` #11, the
+  general form of #040). A `### Props` table per wrapper: Vue and React names together, what each
+  does, and the Blazor differences stated rather than implied. Writing them measured something
+  nobody had: **four Blazor pickers are far thinner than their JS twins** — `FdyDatepicker` takes 6
+  parameters against 21 Vue props, `FdyAutocomplete` 6 against 11, `FdyCascade` 8 against 12, and
+  `FdyCombo` has no `Describedby`. Those wrappers render a seed element and do not splat unmatched
+  attributes, so `disabled`, `readonly`, `invalid`, the a11y ids, `clearable` and the datepicker's
+  ten navigation labels cannot be reached from a Blazor page at all. It runs the other way too:
+  `CloseLabel` exists only in Blazor, so the modal and drawer × is fixed at `Close` in Vue and
+  React. Filed as `NEXT-UP.md` #12 with its trigger; documented here as fact in the meantime,
+  because a consumer meeting it should find it written down rather than discover it.
+- **`FdyAppShell` was missing from every list of the typed wrappers but the two READMEs.** It
+  shipped as the eleventh in 1.54.0 and `COMPONENTS.md`, `getting-started.md`, `agent-onboarding.md`
+  and `integrations.md` went on naming ten for a whole major version — `agent-onboarding.md`
+  saying both "ten" and "eleven" about the same set, in the same file, and `getting-started.md`
+  carrying a section heading that still listed the seven of some earlier release. All corrected,
+  and a guard now reads any run of six or more wrapper names as an enumeration and fails if it is
+  incomplete. It found two of these itself, one of them a list this release had already touched.
+
 ## [2.0.0] - 2026-08-25
 ### Changed: BREAKING
 - **The vanilla enhancers now write English by default** (`NEXT-UP.md` #6, owner's decision). Every

package/COMPONENTS.md

@@ -36,7 +36,7 @@ live docs.
    alert, breadcrumb, timeline, accordion, tree-without-cascade…) are CSS-only.
 7. **On Vue, React or Blazor, eleven components have a typed wrapper. Use it.** `FdyCombo` ·
    `FdyDatepicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart` ·
-   `FdyTable` · `FdyModal` · `FdyDrawer`, from `@cahyo-dimas/freeday/vue`, `/react`, or the
+   `FdyTable` · `FdyModal` · `FdyDrawer` · `FdyAppShell`, from `@cahyo-dimas/freeday/vue`, `/react`, or the
    `Freeday.Blazor` RCL. Each is flagged at its own section below. Hand-writing their raw markup in
    those stacks *looks* right at first, because the enhancer initialises once and the first render is
     correct. Then
@@ -117,6 +117,25 @@ is a no-op.
 ## App shell — `.fdy-app`
 > **Typed wrapper: `<FdyAppShell>`**. Vue (`v-model:navOpen`) · React (`navOpen`/`onNavOpenChange`) · Blazor (`@bind-NavOpen`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
 
+### Props — `<FdyAppShell>`
+
+Vue and React names, `?` marking optional. Vue takes the regions as **slots** of the same names,
+which is why React's list is longer while offering the same thing.
+
+| Prop | Type | What it does |
+|---|---|---|
+| `navOpen?` | `boolean` | Whether the nav is visible. Optional because the default is the **viewport's**, and a caller cannot state that in one initial value. Vue binds `v-model:navOpen`. |
+| `onNavOpenChange?` | `(open: boolean) => void` | React. Visibility changed: the toggle, Escape, the backdrop, or a followed nav item. Vue emits `update:navOpen`. |
+| `title?` | `string` (Vue) · `ReactNode` | Topbar title. |
+| `toggleLabel?` | `string` | Accessible name for the nav toggle button. |
+| `toggleIcon?` | `ReactNode` | React. Replaces the default hamburger; Vue uses the slot of that name. |
+| `skip?` | `ReactNode` | React. Skip link, rendered first in the tab order. |
+| `brand?` · `nav?` · `topbar?` | `ReactNode` | React. Sidebar brand, sidebar nav, topbar contents. |
+| `children?` | `ReactNode` | React. The page itself; Vue's default slot. |
+
+Blazor takes the regions as `RenderFragment`s — `BrandContent`, `NavContent`, `TopbarContent`,
+`SkipContent`, `TitleContent`, `ChildContent` — and binds with `@bind-NavOpen`.
+
 The frame every application lives in. Do not hand-roll one from flexbox: the responsive sidebar,
 off-canvas drawer and backdrop are built in.
 
@@ -422,6 +441,24 @@ Native inputs, styled. `.fdy-check` · `.fdy-radio` · `.fdy-switch` on the wrap
 ## Select / combobox — `.fdy-combo`
 > **Typed wrapper: `<FdyCombo>`**. 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).
 
+### Props — `<FdyCombo>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `modelValue` · `value` | `T extends string` | The selected value: `v-model` in Vue, `value` in React. |
+| `onChange` | `(value: T) => void` | React. A selection was committed. Vue emits `update:modelValue` and `change`. |
+| `options` | `ReadonlyArray<{ value: T; label: string }>` | The list. React exports the row type as `FdyComboOption<T>`. |
+| `id?` | `string` | Explicit id for the combobox button; otherwise one is generated. |
+| `ariaLabelledby?` | `string` | Id of the element that labels the combobox. |
+| `placeholder?` | `string` | Shown when no option matches the current value. |
+| `disabled?` | `boolean` | Greyed and out of the tab order, the native `disabled` semantics. |
+| `readonly?` | `boolean` | Locked/view mode: keeps focus and tab order and shows its value, but cannot be opened or changed. Unlike `disabled` it is not greyed. |
+| `invalid?` | `boolean` | Sets `aria-invalid`; pair it with `describedby` pointing at the error text. |
+| `describedby?` | `string` | Id of the help or error text (`aria-describedby`). |
+
+Blazor: the same names in `PascalCase`, bound with `@bind-Value` (`Value` / `ValueChanged`),
+with one absence — there is no `Describedby`, so a Blazor combo cannot point at its own error text.
+
 Fully styleable dropdown, APG combobox+listbox. Needs `freeday-select.js`.
 
 - `.fdy-combo` (+`--error`, `--no-icon`) · `__button` `__value` (+`--placeholder`) `__listbox`
@@ -452,6 +489,22 @@ keeps matching after selection. Do not put a glyph in that span.
 ## Autocomplete — `.fdy-autocomplete`
 > **Typed wrapper: `<FdyAutocomplete>`**. 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).
 
+### Props — `<FdyAutocomplete>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `modelValue` · `value` | `string` | The typed text. Free text: the list suggests, it does not constrain. |
+| `onChange` · `onSelect` | `(value: string) => void` | React. `onChange` on every keystroke, `onSelect` only when a suggestion is taken. Vue emits `update:modelValue` and `select`. |
+| `options` | `ReadonlyArray<string>` | The suggestions to filter. |
+| `emptyText?` | `string` | Shown when nothing matches. |
+| `placeholder?` | `string` | |
+| `id?` · `ariaLabel?` · `ariaLabelledby?` · `describedby?` | `string` | Input id; its accessible name as text or as a reference; the help/error text it points at. |
+| `disabled?` · `readonly?` · `invalid?` | `boolean` | `readonly` keeps focus and tab order and shows its value, but the input is not editable and the list will not open. Unlike `disabled` it is not greyed. |
+
+Blazor takes six of these — `Value` / `ValueChanged`, `Options`, `Placeholder`, `AriaLabel`,
+`EmptyText` — and no state flags or ids. Its wrapper renders a fixed seed element and does not
+splat unmatched attributes, so those are not reachable from a Blazor page at all.
+
 Editable combobox that filters as you type. Needs `freeday-autocomplete.js`.
 
 - `.fdy-autocomplete` · `__listbox` `__option` `__empty`
@@ -461,6 +514,22 @@ Editable combobox that filters as you type. Needs `freeday-autocomplete.js`.
 ## Cascade select — `.fdy-cascade`
 > **Typed wrapper: `<FdyCascade>`**. 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).
 
+### Props — `<FdyCascade>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `modelValue` · `value` | `string` | The selected **leaf** value; `''` means nothing selected. |
+| `onChange` | `(value: string, labels: string[]) => void` | React. Vue emits `update:modelValue` and `change`. `labels` is the whole path, root → leaf. |
+| `options` | `ReadonlyArray<CascadeNode>` | The tree. `CascadeNode` = `{ label, value, children? }`; a node **with** children is a branch, one without is selectable. |
+| `separator?` | `string` | What joins the path in the display. Default `" / "`, matching the enhancer. |
+| `backLabel?` | `string` | Accessible name for the up-one-level button. Default `Back one level`. |
+| `label?` | `string` | Accessible name for the trigger and its listbox. |
+| `placeholder?` | `string` | |
+| `id?` · `ariaLabelledby?` · `describedby?` | `string` | Trigger id; the element that labels it; the help/error text it points at. |
+| `disabled?` · `readonly?` · `invalid?` | `boolean` | As on `<FdyCombo>`. |
+
+Blazor calls the tree `Nodes`, adds `SubmenuLabel`, and takes neither the state flags nor the ids.
+
 Hierarchical drill-down. The data model is a **nested `<ul>`** inside the wrapper: an `<li>` with a
 child `<ul>` is a branch, one without is a leaf. Needs `freeday-cascade.js`.
 
@@ -482,6 +551,37 @@ child `<ul>` is a branch, one without is a leaf. Needs `freeday-cascade.js`.
 ## Choose-from-list (CFL) — `data-fdy-cfl`
 > **Typed wrapper: `<FdyCfl>`**. 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).
 
+### Props — `<FdyCfl>`
+
+Four of these are required and carry the whole component: `fetchPage`, `columns`, `display`,
+`rowKey`. The rest are copy and state.
+
+| Prop | Type | What it does |
+|---|---|---|
+| `modelValue` · `value` | `Row \| Row[] \| null` | The picked row. An array is reachable only under `multiple`, `null` only under `clearable`; narrow it with `singleRow()` (see the bullet below the raw-path hooks). |
+| `onChange` | `(value: Row \| Row[] \| null) => void` | React. Vue emits `update:modelValue` and `change`. |
+| `fetchPage` | `(query: string, page: number) => Promise<CflPage<Row>>` | The only data source — `{ rows, hasMore }`. Called on open, on search, and on Load more. Server state, never a global store. |
+| `columns` | `ReadonlyArray<CflColumn<Row>>` | `{ key, label }` per dialog column. |
+| `display` | `(row: Row) => string` | What the closed field shows once a row is picked. |
+| `rowKey` | `(row: Row) => string` | Row identity: ticks in multi mode, and seeding them when the dialog re-opens. |
+| `pageSize?` | `number` | Advisory only. Your `fetchPage` owns paging; this documents the intent. |
+| `title?` | `string` | The dialog's heading. Default `Choose data`. |
+| `searchPlaceholder?` | `string` | Placeholder **and** accessible name of the search box. Default `Search…`. |
+| `loadingText?` · `emptyText?` · `retryText?` · `moreText?` | `string` | Dialog states. Defaults `Loading…`, `No results.`, `Try again`, `Load more`. |
+| `closeLabel?` · `openLabel?` | `string` | Accessible names for the dialog's × and the field's open button. Defaults `Close`, `Open search`. |
+| `multiple?` | `boolean` | Tick rows and commit them together on Confirm instead of committing the clicked row, and widen the value to an array. |
+| `selectedText?` · `confirmText?` · `hintText?` | `string` | Footer copy. Defaults `{n} selected` (with `{n}` substituted), `Confirm`, `Click a row to choose it`. |
+| `placeholder?` | `string` | Field placeholder while nothing is picked. |
+| `clearable?` | `boolean` | A clear button, so an **optional** foreign key can be unset. Without it the value type admits a `null` the component can never produce. |
+| `clearLabel?` | `string` | Accessible name for that button. Default `Clear selection`. |
+| `disabled?` · `readonly?` · `invalid?` | `boolean` | `readonly` keeps the picked value visible, focusable and copyable, but the dialog cannot be opened. |
+| `id?` · `ariaLabelledby?` · `describedby?` | `string` | Field id; the element that labels it; the help/error text it points at. |
+
+Blazor carries the same surface in `PascalCase` with three differences: multi-select is a second
+pair (`Values` / `ValuesChanged`) rather than a widened single binding, the fetch delegate is
+called `LoadPage`, and it has two parameters the JS adapters do not — `ErrorText` and
+`SearchDebounceMs`.
+
 A read-only field backed by master data: the button opens a searchable dialog, the picked row fills
 the field. The value is always **chosen, never typed**. Needs `freeday-cfl.js`.
 
@@ -498,6 +598,13 @@ the field. The value is always **chosen, never typed**. Needs `freeday-cfl.js`.
   `ValuesChanged`, because a nullable union is not a C# shape. Closing without Confirm leaves the
   bound value untouched, and re-opening seeds the ticks from it. The field states `{n} selected`
   rather than one row's `display()`. Strings: `selectedText`, `confirmText`, `hintText`.
+- **A single-select in Vue or React needs one narrowing, and the kit ships it.** The emitted value
+  is typed `Row | Row[] | null` whatever the props are, so a single-select handler cannot take it
+  as `Row`: the array is reachable only under `multiple`, the null only under `clearable`, and the
+  type cannot say which. Import the guard instead of writing one per app:
+  `import { singleRow } from '@cahyo-dimas/freeday/vue'` (or `/react`). It returns `Row | null`,
+  and throws if a `multiple` field's array ever reaches it, rather than silently keeping the first
+  row. Blazor is unaffected: multi-select there is a separate `Values` / `ValuesChanged` pair.
 
 ```html
 <div class="fdy-field">
@@ -547,6 +654,46 @@ 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).
 
+### Props — `<FdyDatepicker>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `modelValue` · `value` | `string \| null` | ISO `YYYY-MM-DD`, or `''`/`null` for empty. |
+| `onChange` | `(value: string) => void` | React. Vue emits `update:modelValue` and `change`. Clearing sends `''`. |
+| `min?` · `max?` | `string` | ISO bounds; days outside them cannot be picked. |
+| `locale?` | `string` | BCP-47 tag deciding month and weekday names. Defaults to the page's `<html lang>`, then `en`. |
+| `placeholder?` | `string` | |
+| `id?` · `ariaLabelledby?` · `describedby?` | `string` | Trigger id; the element that labels it; the help/error text it points at. |
+| `disabled?` · `readonly?` · `invalid?` | `boolean` | `readonly` keeps focus and tab order and shows its date, but it cannot be opened, cleared or changed. |
+| `clearable?` | `boolean` | Show a × in the trigger once a date is set, so an optional date can be unset. Sends `''`. Off by default. |
+| `clearLabel?` | `string` | Accessible name for that ×. Default `Clear date`. |
+| `prevMonthLabel?` · `nextMonthLabel?` | `string` | The month arrows. Defaults `Previous month` / `Next month`. |
+| `chooseMonthLabel?` · `chooseYearLabel?` | `string` | The title buttons that drill into the month and year grids. Defaults `Choose month` / `Choose year`. |
+| `prevYearLabel?` · `nextYearLabel?` | `string` | Year arrows, shown in the month grid. Defaults `Previous year` / `Next year`. |
+| `prevYearsLabel?` · `nextYearsLabel?` | `string` | Page arrows, shown in the year grid. Defaults `Previous years` / `Next years`. |
+
+The ten label props exist because month and weekday names follow `locale` while the buttons around
+them do not: without these, a Spanish calendar would be navigated by English arrows.
+
+Blazor's picker is much thinner — `Value` / `ValueChanged`, `Label`, `Placeholder`, `Min`, `Max`
+— and its seed element takes no unmatched attributes, so state flags, ids, `clearable` and every
+label above are unreachable there.
+
+### Props — `<FdyDateRange>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `modelValue` · `value` | `DateRangeValue` = `{ start, end }`, each `string \| null` | Both ends at once, so the pair can never be half-applied. |
+| `onChange` | `(value: DateRangeValue) => void` | React. Vue emits `update:modelValue` and `change`. |
+| `min?` · `max?` | `string` | ISO bounds for both ends. The end can never precede the start. |
+| `locale?` | `string` | As on the single picker. |
+| `startPlaceholder?` · `endPlaceholder?` | `string` | One per field. |
+| `ariaLabel?` · `ariaLabelledby?` · `describedby?` | `string` | Names the group (`role="group"`), or points at the text that does. |
+| `disabled?` · `readonly?` · `invalid?` | `boolean` | Applied to both pickers together. |
+
+Blazor splits the value into two scalars, `From` / `FromChanged` and `To` / `ToChanged`, because a
+C# binding cannot express one object bound in two places, and it adds `Separator`.
+
 Input-styled trigger + calendar popover. Needs `freeday-datepicker.js`. **Author an empty `<div>`**
 The enhancer builds everything.
 
@@ -772,6 +919,75 @@ sum, so measure them once after render (and on resize) and set the variable.
 ## Data table — `.fdy-datatable`
 > **Typed wrapper: `<FdyTable>`**. controlled: `columns` + `rows`, with sort/filter/page events (`update:pageIndex` · `onPageIndexChange` · `PageIndexChanged`) and `process` for driving a card list off the same processed set. The markup below is the raw enhancer path.
 
+### Columns — the typed `FdyTableColumn<T>`
+
+On Vue, React and Blazor, `columns` **is** the table: it is what those stacks write instead of the
+markup hooks further down. Ten fields, `key` and `label` required. The authored doc comments live on
+the type itself (`adapters/core/table-model.d.ts`, re-declared for Blazor in
+`adapters/blazor/TableTypes.cs`); the list below is the discoverable copy, and `npm test` fails if
+the two ever disagree.
+
+| Field | Type | What it does |
+|---|---|---|
+| `key` | `string` | Row property key; the sort/filter identity and, unless `value` is set, the cell accessor. |
+| `label` | `string` | Header label. |
+| `labelHidden` | `boolean` | Render the label for assistive tech only; the header cell looks empty. |
+| `sortable` | `boolean` | Show a sort toggle in the header. |
+| `filter` | `'text' \| 'enum' \| 'number' \| 'date'` | Offer a column filter of this type (the funnel popover). |
+| `align` | `'left' \| 'right' \| 'center'` | Cell alignment. Default `left`. |
+| `mono` | `boolean` | Render cells in the monospace data font (`.fdy-mono`). |
+| `sortType` | `'text' \| 'number' \| 'date'` | Override the comparator; defaults to one derived from `filter`, else `text`. |
+| `value` | `(row: T) => unknown` | Custom accessor; defaults to `row[key]`. Feeds sort, filter and the default cell text. |
+| `options` | `readonly string[]` | Explicit enum-filter options; they default to the distinct values in the rows on screen, so pass them in server-paged mode, where those are one page. |
+
+Blazor spells the same fields `PascalCase` (`LabelHidden`, `SortType`), makes `Key`/`Label`
+`required`, and adds one field with no TS twin: `Cell`, a `RenderFragment<TRow>` where Vue and React
+use a slot.
+
+A column of row controls is worth stating outright, because the obvious move is the wrong one:
+
+```ts
+const columns: FdyTableColumn<User>[] = [
+  { key: 'email', label: 'Email', sortable: true, filter: 'text' },
+  { key: 'total', label: 'Total', align: 'right', mono: true, sortType: 'number' },
+  // Not `label: ''`. A <th> with no text announces as nothing, and the label also names this
+  // column's sort button and filter popover, so it has to stay meaningful.
+  { key: 'actions', label: 'Actions', labelHidden: true },
+];
+```
+
+### Props — `<FdyTable>`
+
+Controlled by default: hand it `columns` + `rows` and it filters, sorts and paginates internally;
+provide the state prop for a concern and you own that concern instead. React names the callbacks
+`onXChange`, Vue emits `update:x`, Blazor exposes `XChanged`.
+
+| Prop | Type | What it does |
+|---|---|---|
+| `columns` | `ReadonlyArray<FdyTableColumn<Row>>` | The column contract documented above. |
+| `rows` | `ReadonlyArray<Row>` | The current page's rows in server mode, the whole set in client mode. |
+| `rowKey` | `(row: Row) => string \| number` | Row identity: keys, expansion, activation. |
+| `sort?` · `onSortChange?` | `FdySortState \| null` · `(sort) => void` | Pass `sort`, **even as `null`**, to own sorting; omit it for the internal sort. |
+| `filters?` · `onFiltersChange?` | `FdyFilterMap` · `(filters) => void` | The same, for filtering. |
+| `page?` · `onPageChange?` | `FdyPageState` · `(page) => void` | Its **presence switches the table into server mode**: you own paging and get `{ index, size, total }` back. |
+| `pageSize?` | `number` | Client mode: rows per page. Absent or 0 renders every row with no pager. |
+| `pageIndex?` · `onPageIndexChange?` | `number` · `(index) => void` | Client mode: own the 0-based index while the table keeps filtering, sorting and paginating — this is what lets one external pager drive both a table and a card list. |
+| `pageSizes?` · `onPageSizeChange?` | `readonly number[]` · `(size) => void` | Offer a rows-per-page control. Server mode reports the pick through the page event (read its `size`); client mode applies it itself and reports it too, so it works with nothing wired. |
+| `pager?` | `boolean` | Default true. Turn it off to withhold the table's own footer when the screen renders one. |
+| `loading?` | `boolean` | Show the in-table loading state. |
+| `emptyText?` · `empty?` | `string` · `ReactNode` | The empty state as text, or as markup (React `empty`, Vue's `empty` slot). |
+| `ariaLabel?` | `string` | Names the table for assistive tech. |
+| `rowActivatable?` · `onRowActivate?` | `boolean` · `(row) => void` | Rows become focusable and activate on click, Enter or Space. |
+| `rowClass?` | `(row: Row) => string \| undefined` | Per-row class hook, e.g. marking the selected row. |
+| `expandedKeys?` · `renderRowDetail?` | `ReadonlyArray<string \| number>` · `(row) => ReactNode` | Controlled expansion: these keys get a full-width detail row. Vue uses the `row-detail` slot. |
+| `renderCell?` | `(column, row, value) => ReactNode` | React. Custom cell rendering; Vue uses the `cell` slot. |
+| `toolbar?` | `ReactNode` | React. Content above the table; Vue uses the `toolbar` slot. |
+| `onProcess?` | `(result: { rows, total }) => void` | React. The processed page after filter/sort/paginate, in **both** modes. Vue emits `process`, Blazor calls it `Process`. Render the same set elsewhere — a card list, a summary, a CSV export — without re-deriving the pipeline. |
+
+Blazor matches this surface (`LoadingText` and `EmptyContent` in place of `emptyText`/`empty`,
+`Toolbar` and `RowDetail` as `RenderFragment`s) and is the one adapter that also exposes
+`FiltersChanged`.
+
 The interactive table: global search, sort, per-column filters, row selection + bulk bar,
 pagination. Needs `freeday-table.js`. Wrap the whole thing in `.fdy-datatable` + `data-fdy-table`
 (`data-page-size="N"`).
@@ -849,6 +1065,14 @@ ninety-row list would remove the only way back to twenty.
 of one page of rows. A footer inside the table is inside the half a phone hides, so those screens
 render it once, outside both, with `pager={false}` on the table.
 
+### Props — `<FdyTableFooter>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `page` | `FdyPageState` = `{ index, size, total }` | The page being shown. `size` drives both the range text and the rows-per-page control's value. |
+| `onPageChange?` | `(page: FdyPageState) => void` | React. A page click or a size change. Vue emits `update:page`; Blazor `PageChanged`. |
+| `pageSizes?` | `readonly number[]` | Offer a rows-per-page control. Omit it and the footer is range + pager only. Picking a size reports the new `size` together with the index that still holds the row the reader was looking at. |
+
 **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:
 
@@ -879,6 +1103,25 @@ replaces.
 ## Charts — `data-fdy-chart`
 > **Typed wrapper: `<FdyChart>`**. data props in all three (`type` + `values` / `series`); it repaints on data change, so `FreedayChart.update(el)` is only for the raw path below.
 
+### Props — `<FdyChart>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `type` | `'line' \| 'area' \| 'bar' \| 'sparkline' \| 'donut'` | Which chart to draw. |
+| `values?` | `ReadonlyArray<number>` | One series. |
+| `series?` | `ReadonlyArray<FdyChartSeries>` | Several: each `{ label, values }`. Use one or the other, not both. |
+| `labels?` | `ReadonlyArray<string>` | Category labels: the x axis, or the donut's slices. |
+| `format?` | `'number' \| 'percent' \| 'currency'` | How values are written in labels and the donut centre. |
+| `stacked?` | `boolean` | Bar charts: stack the series instead of grouping them side by side. |
+| `legend?` | `'auto' \| 'always' \| 'none'` | `auto` shows one when there is more than one series. |
+| `colors?` | `ReadonlyArray<string>` | Per-series override. Each entry is a semantic token name (`primary`, `accent`, `success`, `warning`, `danger`, `info`) or a categorical slot `chart-1`…`chart-8`. Omit for the default fixed-order palette. |
+| `color?` | `string` | The same, for a single-series chart (sparkline, simple bar or line). |
+| `center?` | `string \| number` | Donut only: what to print in the middle. |
+| `aria-label?` | `string` | React. The chart's accessible name, and in practice the **whole** text alternative: a named chart's painted subtree is `aria-hidden`, see the a11y note in this section. Vue and Blazor set it as a plain attribute (Blazor's parameter is `AriaLabel`). |
+| `children?` | `ReactNode` | React. Content inside the element before the chart paints. The renderer replaces it, so it is a pre-paint placeholder, not a text alternative. |
+
+Blazor adds `ChildContent` for the same placeholder role.
+
 Pure SVG/CSS, no dependency, re-colours with the theme. Needs `freeday-chart.js`; call
 `FreedayChart.update(el)` after changing data (or use `FdyChart` in Vue/React/Blazor).
 
@@ -1076,6 +1319,22 @@ so the same look serves routed sub-navigation built from plain links. See the no
 ## Modal — `.fdy-modal`
 > **Typed wrapper: `<FdyModal>`**. Vue (`:open` + `@close`) · React (`open` + `onClose`) · Blazor (`@bind-Open`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
 
+### Props — `<FdyModal>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `open` | `boolean` | Controlled: your state decides. The wrapper cancels the native `cancel` event so the DOM can never disagree with it. |
+| `title` | `string` (Vue) · `ReactNode` | Names the dialog through `aria-labelledby`. Vue also offers a `title` slot when the heading needs markup. |
+| `onClose` | `() => void` | React. Vue emits `close`. Fires from Escape, a backdrop click and the ×, all three of which exist only under `dismissible`. |
+| `size?` | `'sm' \| 'md' \| 'lg' \| 'wide'` | Dialog width. |
+| `dismissible?` | `boolean` | Whether Escape, the backdrop and the × can close it. Off means the reader has to take a footer action, which is the point of a blocking confirm. |
+| `footer?` | `ReactNode` | React. Vue: the `footer` slot. |
+| `children?` | `ReactNode` | React. The body. Vue: the default slot. |
+
+Blazor binds `@bind-Open` and takes `TitleContent` / `ChildContent` / `FooterContent`, plus two
+things Vue and React do not have: `OnClose` and **`CloseLabel`**. The × in Vue and React is labelled
+`Close` and cannot be renamed.
+
 Native `<dialog>`: focus trap, Esc and backdrop come from the browser. Sizes `--sm` `--md` `--lg`
 `--wide`; `--cfl` for the choose-from-list dialog.
 
@@ -1111,6 +1370,22 @@ that is not the kit. Both rules measured on Chromium 133 and 151, and pinned as
 ## Drawer — `.fdy-drawer`
 > **Typed wrapper: `<FdyDrawer>`**. Vue (`:open` + `@close`) · React (`open` + `onClose`) · Blazor (`@bind-Open`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
 
+### Props — `<FdyDrawer>`
+
+The modal's props with `side` in place of `size`; the behaviour notes there apply here too.
+
+| Prop | Type | What it does |
+|---|---|---|
+| `open` | `boolean` | Controlled, as with the modal. |
+| `title` | `string` (Vue) · `ReactNode` | Names the drawer (`aria-labelledby`). |
+| `onClose` | `() => void` | React. Vue emits `close`. |
+| `side?` | `'left' \| 'right'` | Which edge it slides from. |
+| `dismissible?` | `boolean` | Escape, backdrop and × on or off. |
+| `footer?` | `ReactNode` | React. Vue: the `footer` slot. |
+| `children?` | `ReactNode` | React. The body. Vue: the default slot. |
+
+Blazor: `@bind-Open`, `TitleContent` / `ChildContent` / `FooterContent`, `OnClose`, `CloseLabel`.
+
 Temporary side panel on native `<dialog>`, left by default, `--right` to flip. Parts `__header`
 `__title` `__body` `__footer` `__close`. Open it from any
 `<button data-fdy-drawer="<dialog id>">`. Needs `freeday-drawer.js`.

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-v2.0.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v2.0.0)
+[![Release](https://img.shields.io/badge/release-v2.1.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v2.1.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-v2.0.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v2.0.0)
+[![Release](https://img.shields.io/badge/release-v2.1.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v2.1.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/core/cfl-value.d.ts

@@ -0,0 +1,11 @@
+// Types for the choose-from-list value helper (adapters/core/cfl-value.js).
+
+/**
+ * Narrow an `FdyCfl` value to the row a single-select can actually produce.
+ *
+ * `Row[]` is reachable only under `multiple` and `null` only under `clearable`, but the emitted
+ * type cannot say which of those props a given field sets, so every single-select handler has to
+ * prove it. Throws on an array rather than taking its first row: quietly picking one is how a
+ * `multiple` added later goes unnoticed.
+ */
+export declare function singleRow<Row>(value: Row | Row[] | null): Row | null;

package/adapters/core/cfl-value.js

@@ -0,0 +1,31 @@
+// Freeday, choose-from-list value narrowing (pure, zero dependencies).
+//
+// `FdyCfl` in Vue and React declares one model type, `Row | Row[] | null`, covering three prop
+// combinations at once: the array is reachable only under `multiple`, the null only under
+// `clearable`. A single-select screen therefore has to narrow a union that its own props make
+// impossible, and the widening arrived across two releases that were additive from the kit's side
+// (1.29.0 `clearable`, 1.42.0 `multiple`) and a broken build from the consumer's. Apps were each
+// inventing the guard differently: a cast that hides the day `clearable` is added, a silent
+// ignore, or a throw. The kit is what knows the invariant, so the guard is written once, here.
+//
+// Blazor needs none of this: multi-select there is a separate `Values` / `ValuesChanged` pair,
+// because a nullable union is not a C# binding shape.
+
+/**
+ * Narrow an `FdyCfl` value to the row a single-select can actually produce.
+ *
+ * @template Row
+ * @param {Row | Row[] | null} value the value the component emitted
+ * @returns {Row | null} the picked row, or null when nothing is picked
+ * @throws {TypeError} when handed an array, which only a `multiple` CFL emits
+ */
+export function singleRow(value) {
+  if (Array.isArray(value)) {
+    throw new TypeError(
+      `singleRow() got an array of ${value.length} row(s). Only an FdyCfl with \`multiple\` emits ` +
+        'one, and a set of rows is not a single selection: read the array directly on that field, ' +
+        'or drop `multiple`.',
+    );
+  }
+  return value == null ? null : value;
+}

package/adapters/react/index.d.ts

@@ -34,6 +34,9 @@ export { FdyDateRange, type FdyDateRangeProps, type DateRangeValue } from './com
 export { FdyAutocomplete, type FdyAutocompleteProps } from './components/FdyAutocomplete';
 export { FdyCascade, type FdyCascadeProps, type CascadeNode } from './components/FdyCascade';
 export { FdyCfl, type FdyCflProps, type CflColumn, type CflPage } from './components/FdyCfl';
+/** Narrow `FdyCfl`'s `Row | Row[] | null` to the `Row | null` a single-select can produce; throws
+ *  on the array only a `multiple` field emits. */
+export { singleRow } from '../core/cfl-value';
 export { FdyChart, type FdyChartProps, type FdyChartSeries } from './components/FdyChart';
 export { FdyTable, type FdyTableProps } from './components/FdyTable';
 /** The table's own footer, standalone, for a responsive list whose table is hidden at some

package/adapters/react/index.js

@@ -6,6 +6,7 @@ export { FdyDateRange } from './components/FdyDateRange.tsx';
 export { FdyAutocomplete } from './components/FdyAutocomplete.tsx';
 export { FdyCascade } from './components/FdyCascade.tsx';
 export { FdyCfl } from './components/FdyCfl.tsx';
+export { singleRow } from '../core/cfl-value.js';
 export { FdyChart } from './components/FdyChart.tsx';
 export { FdyTable } from './components/FdyTable.tsx';
 export { FdyTableFooter } from './components/FdyTableFooter.tsx';

package/adapters/vue/index.d.ts

@@ -33,6 +33,9 @@ export { default as FdyAutocomplete } from './components/FdyAutocomplete.vue';
 export { default as FdyCascade } from './components/FdyCascade.vue';
 export type { CascadeNode } from './components/FdyCascade.vue';
 export { default as FdyCfl } from './components/FdyCfl.vue';
+/** Narrow `FdyCfl`'s `Row | Row[] | null` to the `Row | null` a single-select can produce; throws
+ *  on the array only a `multiple` field emits. */
+export { singleRow } from '../core/cfl-value';
 export { default as FdyChart } from './components/FdyChart.vue';
 export { default as FdyTable } from './components/FdyTable.vue';
 /** The table's own footer, standalone, for a responsive list whose table is hidden at some

package/adapters/vue/index.js

@@ -6,6 +6,7 @@ export { default as FdyDateRange } from './components/FdyDateRange.vue';
 export { default as FdyAutocomplete } from './components/FdyAutocomplete.vue';
 export { default as FdyCascade } from './components/FdyCascade.vue';
 export { default as FdyCfl } from './components/FdyCfl.vue';
+export { singleRow } from '../core/cfl-value.js';
 export { default as FdyChart } from './components/FdyChart.vue';
 export { default as FdyTable } from './components/FdyTable.vue';
 export { default as FdyTableFooter } from './components/FdyTableFooter.vue';

package/dist/freeday-carousel.js

@@ -18,10 +18,11 @@
   'use strict';
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     position: '{n} of {total}',
     slide: 'Slide {n}'

package/dist/freeday-cascade.js

@@ -54,10 +54,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     back: 'Back one level',
     submenu: '{label}, submenu'

package/dist/freeday-cfl.js

@@ -34,10 +34,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     selected: '{n} selected'
   };

package/dist/freeday-form.js

@@ -38,10 +38,11 @@
     badInput: 'type',
     customError: 'mismatch'
   };
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and overridable at three levels, narrowest first: `data-fdy-msg-<alias>` on the field,
-   * `data-fdy-msg` on the field, then `data-fdy-text-<alias>` on the FORM. The form level is what
-   * a host in another language needs: it sets nine messages once instead of on every input.
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and overridable at three levels, narrowest first: `data-fdy-msg-<alias>` on
+   * the field, `data-fdy-msg` on the field, then `data-fdy-text-<alias>` on the FORM. The form
+   * level is what a host in another language needs: it sets nine messages once instead of on
+   * every input.
    * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
   var TEXT = {
     required: 'Required.',

package/dist/freeday-mask.js

@@ -51,10 +51,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     show: 'Show password',
     hide: 'Hide password'

package/dist/freeday-stepper.js

@@ -19,10 +19,11 @@
   var CHECK = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>';
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     done: 'Done',
     next: 'Next'

package/dist/freeday-table.js

@@ -34,10 +34,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     prev: 'Previous',
     next: 'Next',

package/dist/freeday-toast.js

@@ -77,10 +77,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     close: 'Close'
   };

package/dist/freeday-upload.js

@@ -51,10 +51,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     remove: 'Remove {name}',
     progress: 'Upload progress for {name}',

package/dist/freeday.js

@@ -419,10 +419,11 @@
   'use strict';
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     position: '{n} of {total}',
     slide: 'Slide {n}'
@@ -596,10 +597,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     back: 'Back one level',
     submenu: '{label}, submenu'
@@ -862,10 +864,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     selected: '{n} selected'
   };
@@ -2367,10 +2370,11 @@
     badInput: 'type',
     customError: 'mismatch'
   };
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and overridable at three levels, narrowest first: `data-fdy-msg-<alias>` on the field,
-   * `data-fdy-msg` on the field, then `data-fdy-text-<alias>` on the FORM. The form level is what
-   * a host in another language needs: it sets nine messages once instead of on every input.
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and overridable at three levels, narrowest first: `data-fdy-msg-<alias>` on
+   * the field, `data-fdy-msg` on the field, then `data-fdy-text-<alias>` on the FORM. The form
+   * level is what a host in another language needs: it sets nine messages once instead of on
+   * every input.
    * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
   var TEXT = {
     required: 'Required.',
@@ -2581,10 +2585,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     show: 'Show password',
     hide: 'Hide password'
@@ -3272,10 +3277,11 @@
   var CHECK = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>';
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     done: 'Done',
     next: 'Next'
@@ -3407,10 +3413,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     prev: 'Previous',
     next: 'Next',
@@ -4238,10 +4245,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     close: 'Close'
   };
@@ -4472,10 +4480,11 @@
   }
 
 
-  /* User-facing strings. Indonesian by default, documented and deliberate for the raw enhancer
-   * path, and every one overridable per element, so a host that speaks another language (the
-   * Blazor adapters, an English app on the raw path) supplies its own without forking this file.
-   * Keeping them in ONE table is also what lets a guard prove none is hard-coded further down. */
+  /* User-facing strings. English by default since 2.0.0, documented and deliberate for the raw
+   * enhancer path, and every one overridable per element with `data-fdy-text-<key>`, so a host
+   * that speaks another language (an Indonesian app on the raw path) supplies its own without
+   * forking this file. Keeping them in ONE table is also what lets a guard prove none is
+   * hard-coded further down. */
   var TEXT = {
     remove: 'Remove {name}',
     progress: 'Upload progress for {name}',

package/docs/agent-onboarding.md

@@ -20,21 +20,21 @@ the **root of the consuming project**:
 
 All UI in this project is built from Freeday: a **token-driven CSS kit** (`fdy-*` classes on plain
 markup) with **typed components for Vue, React and Blazor** layered on top. Most of the kit is
-markup + classes; ten interactive components also ship a typed wrapper, and in those three stacks
+markup + classes; eleven interactive components also ship a typed wrapper, and in those three stacks
 the wrapper is the correct way to use them.
 
 **0. First decide which entry point this project uses. This is not an optimisation. Get it wrong
 and the code looks correct and fails later.**
 
-| This project's stack | Import the ten components from | Binding |
+| This project's stack | Import the eleven components from | Binding |
 |---|---|---|
 | Vue 3 | `@cahyo-dimas/freeday/vue` | `v-model` |
 | React 18/19 | `@cahyo-dimas/freeday/react` | `value` + `onChange` |
 | Blazor (net8.0) | `@using Freeday.Blazor` (RCL) | `@bind-Value` |
 | Static HTML, Svelte, server-rendered templates… | no wrapper: raw markup + the enhancer script | `fdy-*` DOM events |
 
-The ten: **FdyCombo · FdyDatepicker · FdyDateRange · FdyAutocomplete · FdyCascade · FdyCfl ·
-FdyChart · FdyTable · FdyModal · FdyDrawer**. In Vue/React/Blazor, **never hand-write the raw
+The eleven: **FdyCombo · FdyDatepicker · FdyDateRange · FdyAutocomplete · FdyCascade · FdyCfl ·
+FdyChart · FdyTable · FdyModal · FdyDrawer · FdyAppShell**. In Vue/React/Blazor, **never hand-write the raw
 markup + enhancer for these eleven.** The raw path *appears* to work: the enhancer auto-initialises
 once on `DOMContentLoaded` and the first render is correct. Then it fails quietly: DOM your framework
 renders later is never hydrated, and the widget's state lives in the DOM instead of in your
@@ -75,6 +75,9 @@ wrapper, use the raw markup and hydrate it:
    components **without** a typed wrapper. For the eleven in step 0, use the wrapper instead.
 8. Freeday owns components + tokens, **not layout**. Grids/stacks/one-off gaps come from our own
    layout layer. Build its theme on `var(--space-N)` so both systems stay in step.
+9. The enhancers render their own English UI strings (pager, filter dialog, validation). Never
+   hand-translate one by rewriting the enhancer's nodes — set `data-fdy-text-<key>` on the
+   component root, and `<html lang>` for date names. Keys are in COMPONENTS.md.
 ```
 
 Adjust the paths if the package lives somewhere else (a workspace, a vendored copy, `wwwroot/` for
@@ -85,7 +88,7 @@ Blazor). Then verify the agent can actually read those files. An agent that can'
 
 | File | What it answers |
 |---|---|
-| `COMPONENTS.md` | The complete class surface: what exists, its modifiers, minimal markup, a11y. |
+| `COMPONENTS.md` | The complete class surface: what exists, its modifiers, minimal markup, a11y. Also the typed wrappers' props — one `### Props — <FdyX>` table each, and the `FdyTableColumn` fields. |
 | `USAGE.md` | The doctrine: which token/role/shadow/emphasis to use when. |
 | `docs/getting-started.md` | Install + import + theme, per stack (Static HTML · Vue · React · Blazor). |
 | `docs/integrations.md` | How to bridge third-party libraries (validation, charts, dates, i18n…). |
@@ -95,7 +98,7 @@ Blazor). Then verify the agent can actually read those files. An agent that can'
 | `dist/` | Built CSS + enhancers. **`freeday.bundle.css` = tokens + components** (what `@cahyo-dimas/freeday/css` resolves to); `freeday.css` is components **only**, `freeday.tokens.css` tokens only, so linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
 | `src/components/*.css` | The authoritative source for every class, when a doc is ambiguous. |
 | `tokens/tokens.json` | Every token in W3C DTCG format, machine-readable. |
-| `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 10 components each. |
+| `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 11 components each (plus `FdyTableFooter`). |
 
 The live docs (with an interactive playground) are at
 <https://cahyo-dimas.github.io/freeday-ui-kit/>, and the repo (including three complete example

package/docs/getting-started.md

@@ -23,7 +23,7 @@ Freeday = **CSS** (semantic tokens + `fdy-*` classes) + **zero-dependency JS enh
    table: [`integrations.md` §Event & API contract](integrations.md).
    **On Vue, React or Blazor this is not the path to take for eleven of the components.** `FdyCombo`,
    `FdyDatepicker`, `FdyDateRange`, `FdyAutocomplete`, `FdyCascade`, `FdyCfl`, `FdyChart`,
-   `FdyTable`, `FdyModal`, `FdyDrawer` ship typed wrappers that own the state properly (Vue and
+   `FdyTable`, `FdyModal`, `FdyDrawer`, `FdyAppShell` ship typed wrappers that own the state properly (Vue and
    React re-implement the interaction natively; Blazor wraps the enhancer over interop). Use them;
    the raw path is for the components without a wrapper, and for stacks without an adapter.
 3. **Hydrate dynamic DOM.** Enhancers auto-init once on `DOMContentLoaded`. DOM an SPA renders
@@ -65,6 +65,13 @@ Freeday = **CSS** (semantic tokens + `fdy-*` classes) + **zero-dependency JS enh
    `.fdy-page-section`, `.fdy-toolbar`, `.fdy-stats`/`.fdy-stat`) and the type roles (`.fdy-title-page`
    / `-section` / `-card`), not by re-using `.fdy-card__title` for everything. **Which token/role/shadow
    to use when lives in [`USAGE.md`](../USAGE.md)**. Read it once; it's what makes screens cohere.
+9. **The enhancers' UI strings are English, and replaceable per element.** Pager labels, column
+   filter dialogs, upload and validation messages come from the enhancer, not from your markup.
+   Override any of them with **`data-fdy-text-<key>`** on the component's root — key list and the
+   `{n}`/`{from}`/`{total}` placeholders are in [`COMPONENTS.md`](../COMPONENTS.md) §Data table.
+   Dates need no attribute: the pickers format through `Intl` from the page's `<html lang>`, so
+   `lang="id"` gives Indonesian month and weekday names. **Coming from 1.x**, where those defaults
+   were Indonesian: 2.0.0 flipped them to English, and this attribute is the whole migration.
 
 ---
 
@@ -184,7 +191,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^2.0.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^2.1.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`)
@@ -300,10 +307,11 @@ export function Panel() {
 value from `event.detail` in state/ref; don't set the DOM `value` back. `StrictMode` mounts twice in
 dev; `useFreeday` is idempotent, so it's safe.
 
-### 5. Alternative: typed controlled components (`FdyCombo` · `FdyDatepicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart`)
+### 5. Alternative: typed controlled components
 For fields you'd normally write as a native `<select>`/`<input type="date">`,
 `@cahyo-dimas/freeday/react` also exports typed **controlled** components with plain `value`/`onChange`,
-no manual event bubbling (parity with the Vue `v-model` components above):
+no manual event bubbling — the same eleven listed in §Core concepts #2, at parity with the Vue
+`v-model` components above:
 ```tsx
 import { FdyCombo } from '@cahyo-dimas/freeday/react';
 import type { FdyComboOption } from '@cahyo-dimas/freeday/react';
@@ -436,11 +444,12 @@ kit's CSS/enhancers), then bind:
 <FdyChart Type="donut" Values="_byCity" Labels="_cityLabels" AriaLabel="Revenue by city" />
 <FdyDrawer @bind-Open="_drawerOpen" Title="Detail" Side="right">…</FdyDrawer>
 ```
-Ten components at parity with the Vue/React adapters: **`FdyModal`** · **`FdyDrawer`** (`@bind-Open`,
+Eleven components at parity with the Vue/React adapters: **`FdyModal`** · **`FdyDrawer`** (`@bind-Open`,
 `Title`, `Size`/`Side`, `Dismissible`) · **`FdyCombo<TValue>`** · **`FdyDatepicker`** ·
 **`FdyAutocomplete`** · **`FdyCascade`** · **`FdyDateRange`** (`@bind-From`/`@bind-To`) ·
 **`FdyCfl<TRow>`** (async `LoadPage`) · **`FdyChart`** · **`FdyTable<TRow>`** (client sort/filter/page,
-or controlled `Sort`/`Filters`/`Page` for a server-paged table; `RowActivatable`, `RowDetail`). Each
+or controlled `Sort`/`Filters`/`Page` for a server-paged table; `RowActivatable`, `RowDetail`) ·
+**`FdyAppShell`** (`@bind-NavOpen`). Each
 `select`-type control also takes `Disabled`/`Readonly`/`Invalid`. The RCL targets **net8.0** and is
 consumed as source (`<ProjectReference>`); `.NET bin/obj` never ships in the npm tarball.
 

package/docs/integrations.md

@@ -154,7 +154,7 @@ function Panel(): JSX.Element {
 ```
 > **Controlled alternative (parity with Vue's `v-model`):** `@cahyo-dimas/freeday/react` also exports
 > the typed components `FdyCombo` / `FdyDatepicker` / `FdyDateRange` / `FdyAutocomplete` /
-> `FdyCascade` / `FdyCfl` / `FdyChart` / `FdyTable` / `FdyModal` / `FdyDrawer`, with plain
+> `FdyCascade` / `FdyCfl` / `FdyChart` / `FdyTable` / `FdyModal` / `FdyDrawer` / `FdyAppShell`, with plain
 > `value`/`onChange` (props in, events out), no `data-fdy-*` + manual event listener:
 > ```tsx
 > import { FdyCombo } from '@cahyo-dimas/freeday/react';
@@ -200,7 +200,7 @@ document.addEventListener('fdy-form-invalid', (e) =>
 > **Native components (parity with Vue's `v-model` / React's `value`/`onChange`):** the
 > **`Freeday.Blazor`** RCL (net8.0, `adapters/blazor/`) ships the typed components `FdyCombo<TValue>` /
 > `FdyDatepicker` / `FdyDateRange` / `FdyAutocomplete` / `FdyCascade` / `FdyCfl<TRow>` / `FdyChart` /
-> `FdyTable<TRow>` / `FdyModal` / `FdyDrawer` with `@bind`, no `@ref` / manual `initAll` / `[JSInvokable]`:
+> `FdyTable<TRow>` / `FdyModal` / `FdyDrawer` / `FdyAppShell` with `@bind`, no `@ref` / manual `initAll` / `[JSInvokable]`:
 > ```razor
 > @using Freeday.Blazor
 > <FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl-status" />

package/package.json

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