@cahyo-dimas/freeday 1.53.0 → 2.0.0

package/adapters/blazor/TableTypes.cs

@@ -5,7 +5,7 @@ namespace Freeday.Blazor;
 /// <summary>Sort direction for a column.</summary>
 public enum FdySortDir { Asc, Desc }
 
-/// <summary>A column's comparator type — how its values are ordered when sorting.</summary>
+/// <summary>A column's comparator type, how its values are ordered when sorting.</summary>
 public enum FdyColumnType { Text, Number, Date }
 
 /// <summary>Cell alignment. Maps to <c>text-align</c> on the header and body cells.</summary>
@@ -23,7 +23,7 @@ public sealed record FdyPageState(int Index, int Size, int Total);
 
 /// <summary>The processed page of rows (after filter/sort/paginate) plus the total row count, as
 /// raised by <see cref="FdyTable{TRow}.Process"/>. Lets a consumer render the same processed set
-/// somewhere else — a card list below the <c>md</c> breakpoint, a summary, an export — without
+/// somewhere else, a card list below the <c>md</c> breakpoint, a summary, an export, without
 /// re-deriving the pipeline. Mirrors the <c>process</c> event in the Vue/React adapters.</summary>
 public sealed record FdyTableProcess<TRow>(IReadOnlyList<TRow> Rows, int Total);
 
@@ -47,7 +47,7 @@ public sealed class FdyTableColumn<TRow>
     /// <summary>Header label.</summary>
     public required string Label { get; init; }
 
-    /// <summary>Render the label for assistive tech only — the header cell looks empty.
+    /// <summary>Render the label for assistive tech only, the header cell looks empty.
     /// For a column of row CONTROLS (an edit button, a row menu), where a visible heading is noise
     /// above a column of icons but the column still has to be named: a <c>th</c> with no text is
     /// announced as nothing, and a reader tabbing the header row cannot tell what it is. The label

package/adapters/blazor/freeday-blazor.js

@@ -1,4 +1,4 @@
-/* Freeday — Blazor JS interop (classic IIFE; registers window.FreedayBlazor).
+/* Freeday. Blazor JS interop (classic IIFE; registers window.FreedayBlazor).
  * Consistent with the other Freeday enhancers (plain <script>, no ES module),
  * so it serves from any static host without module-MIME strictness.
  *
@@ -56,7 +56,7 @@
   }
 
   // Subscribe to a daterange's child datepicker changes, forwarding {value, role} so a Blazor
-  // wrapper can bind From/To separately — both children emit the same fdy-datepicker-change, so
+  // wrapper can bind From/To separately, both children emit the same fdy-datepicker-change, so
   // the originating child's data-role is what tells them apart.
   function dateRangeOn(element, dotNetRef, methodName) {
     var handler = function (e) {
@@ -72,7 +72,7 @@
     return token;
   }
 
-  // Fire a .NET callback when a pointerdown lands outside `element`, or Escape is pressed —
+  // Fire a .NET callback when a pointerdown lands outside `element`, or Escape is pressed,
   // the light-dismiss primitive for Blazor-owned popovers (e.g. FdyTable's column filter, which
   // is position:fixed in the top layer and so escapes the table's overflow). Returns an off() token.
   function onOutside(element, dotNetRef, methodName) {
@@ -99,7 +99,7 @@
 
   // Passthrough to the Freeday toast API.
   function toast(options) {
-    /* The enhancer's own default is Indonesian — deliberate for the raw path, wrong for a Blazor
+    /* The enhancer's own default is Indonesian, deliberate for the raw path, wrong for a Blazor
      * app, which COMPONENTS.md promises is English throughout. Defaulted here so the promise is
      * kept without changing what a hand-written page gets. */
     options = options || {};
@@ -140,7 +140,7 @@
       if (dismissible) dotNetRef.invokeMethodAsync(dismissMethod);
     };
     var onClick = function (e) {
-      // The ::backdrop is not a separate element — a click whose target is the dialog box
+      // The ::backdrop is not a separate element, a click whose target is the dialog box
       // itself (not its content) is a backdrop click.
       if (dismissible && e.target === dialog) dotNetRef.invokeMethodAsync(dismissMethod);
     };

package/adapters/core/app-shell.d.ts

@@ -0,0 +1,30 @@
+// Types for the framework-agnostic app-shell behaviour (adapters/core/app-shell.js).
+// Shared by FdyAppShell in the Vue, React and Blazor adapters.
+
+/** The parts the shell's behaviour touches. Any of them may be absent from a partial shell. */
+export interface FdyShellParts {
+  sidebar: HTMLElement | null;
+  content: HTMLElement | null;
+  toggle: HTMLElement | null;
+  backdrop: HTMLElement | null;
+}
+
+/**
+ * What the DOM should reflect right now.
+ * `navVisible` is the single idea the app owns: is the nav showing? `overlay` is whether the
+ * viewport is currently below the nav breakpoint, where a visible nav covers the page.
+ */
+export interface FdyShellState {
+  navVisible: boolean;
+  overlay: boolean;
+}
+
+/** The media query the shell switches at, built from tokens/breakpoints.mjs (`nav`). */
+export declare const NAV_QUERY: string;
+
+export declare function shellParts(root: HTMLElement): FdyShellParts;
+export declare function focusablesIn(el: HTMLElement): HTMLElement[];
+export declare function applyShellState(root: HTMLElement, state: FdyShellState): void;
+export declare function focusPanel(root: HTMLElement): Element | null;
+export declare function restoreFocus(root: HTMLElement, previous: Element | null): void;
+export declare function trapTab(root: HTMLElement, event: KeyboardEvent): boolean;

package/adapters/core/app-shell.js

@@ -0,0 +1,134 @@
+// Freeday app-shell behaviour, framework-agnostic (DOM helpers, zero dependencies).
+//
+// The focus trap, `inert` bookkeeping and focus restore shared by FdyAppShell in the Vue, React and
+// Blazor adapters. Kept here, plain ESM with a .d.ts sidecar, for the same reason as
+// table-model.js: three copies of a focus trap is three chances to write it differently, and the
+// one that gets it wrong strands a keyboard user with no way out of a nav panel.
+//
+// The vanilla enhancer (src/freeday-app-shell.js) deliberately does NOT import this: dist/freeday.js
+// is a plain IIFE concatenation with no module system. That leaves exactly two implementations, and
+// browser/adapter.mjs holds them to the same observable behaviour.
+//
+// State stays with the caller. These functions read and write the DOM and nothing else, so a
+// controlled wrapper can own `navOpen` as a prop and still get the parts that are easy to forget.
+
+import { breakpoints } from '../../tokens/breakpoints.mjs';
+
+/** The media query the shell switches at, the same 721px app-shell.css uses. */
+export const NAV_QUERY = `(min-width: ${breakpoints.nav}px)`;
+
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]),'
+  + ' textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * The shell's parts, or nulls. Callers pass the root element they rendered.
+ * @param {HTMLElement} root
+ */
+export function shellParts(root) {
+  return {
+    sidebar: root.querySelector('.fdy-app__sidebar'),
+    content: root.querySelector('.fdy-app__content'),
+    toggle: root.querySelector('.fdy-app__navtoggle'),
+    backdrop: root.querySelector('.fdy-app__backdrop'),
+  };
+}
+
+/**
+ * Focusable descendants, in tab order, that are actually rendered.
+ * getClientRects() rather than offsetParent: an overlay sidebar is position:fixed, and a fixed
+ * element reports no offsetParent at all, filtering on that calls every nav item invisible.
+ * @param {HTMLElement} el
+ * @returns {HTMLElement[]}
+ */
+export function focusablesIn(el) {
+  return Array.prototype.filter.call(el.querySelectorAll(FOCUSABLE), (node) => node.getClientRects().length > 0);
+}
+
+/**
+ * Reconcile the parts of the shell that are not classes: `inert` and `aria-expanded`.
+ *
+ * One rule for both modes: the sidebar is inert whenever the nav is not visible. `width:0` (collapsed)
+ * and `translateX(-100%)` (off-canvas) hide a panel from the eye and neither hides it from the
+ * keyboard, so without this a nav nobody can see still swallows Tab on the way into the page.
+ * The content is inert only while the nav is an open overlay.
+ *
+ * @param {HTMLElement} root
+ * @param {{navVisible: boolean, overlay: boolean}} state
+ */
+export function applyShellState(root, state) {
+  const { sidebar, content, toggle } = shellParts(root);
+  if (toggle) toggle.setAttribute('aria-expanded', String(state.navVisible));
+  setInert(sidebar, !state.navVisible);
+  setInert(content, state.overlay && state.navVisible);
+}
+
+/**
+ * Move focus into the panel, and hand back whatever had it. The caller keeps that until close.
+ * @param {HTMLElement} root
+ * @returns {Element|null} the element that was focused before
+ */
+export function focusPanel(root) {
+  const previous = document.activeElement;
+  const { sidebar } = shellParts(root);
+  if (sidebar === null) return previous;
+  const first = focusablesIn(sidebar)[0];
+  if (first !== undefined) {
+    first.focus();
+  } else {
+    sidebar.setAttribute('tabindex', '-1');
+    sidebar.focus();
+  }
+  return previous;
+}
+
+/**
+ * Put focus back where it came from. Anything gone, detached, or the body itself falls back to the
+ * toggle: document.body is where a keyboard user gets stranded with nothing to press.
+ * @param {HTMLElement} root
+ * @param {Element|null} previous
+ */
+export function restoreFocus(root, previous) {
+  const { toggle } = shellParts(root);
+  const usable = previous !== null && previous !== document.body && document.contains(previous)
+    && typeof previous.focus === 'function';
+  const target = usable ? previous : toggle;
+  if (target !== null && typeof target.focus === 'function') target.focus();
+}
+
+/**
+ * Cycle Tab inside the panel. Call from a keydown handler while the overlay is open.
+ * `inert` on the content stops Tab reaching the page; without this the focus would still walk out
+ * of the document into the browser's own chrome.
+ * @param {HTMLElement} root
+ * @param {KeyboardEvent} event
+ * @returns {boolean} true when focus was moved
+ */
+export function trapTab(root, event) {
+  if (event.key !== 'Tab') return false;
+  const { sidebar } = shellParts(root);
+  if (sidebar === null) return false;
+  const items = focusablesIn(sidebar);
+  if (items.length === 0) {
+    event.preventDefault();
+    return false;
+  }
+  const first = items[0];
+  const last = items[items.length - 1];
+  if (event.shiftKey && document.activeElement === first) {
+    event.preventDefault();
+    last.focus();
+    return true;
+  }
+  if (!event.shiftKey && document.activeElement === last) {
+    event.preventDefault();
+    first.focus();
+    return true;
+  }
+  return false;
+}
+
+function setInert(el, on) {
+  if (el === null) return;
+  if (on) el.setAttribute('inert', '');
+  else el.removeAttribute('inert');
+}

package/adapters/core/table-model.d.ts

@@ -9,7 +9,7 @@ export interface FdySortState {
   dir: FdySortDir;
 }
 
-/** A column's comparator type — how its values are ordered when sorting. */
+/** A column's comparator type, how its values are ordered when sorting. */
 export type FdyColumnType = 'text' | 'number' | 'date';
 
 /** Cell alignment. Maps to `text-align` on the header and body cells. */
@@ -25,7 +25,7 @@ export interface FdyTableColumn<T> {
   /** Header label. */
   label: string;
   /**
-   * Render the label for assistive tech only — the header cell looks empty.
+   * Render the label for assistive tech only, the header cell looks empty.
    *
    * For a column of row CONTROLS (an edit button, a row menu), where a visible
    * heading is noise above a column of icons but the column still has to be

package/adapters/core/table-model.js

@@ -1,7 +1,7 @@
-// Freeday — framework-agnostic table model (pure functions, zero dependencies).
+// Freeday, framework-agnostic table model (pure functions, zero dependencies).
 //
 // The sort / filter / paginate logic shared by adapters/vue/components/FdyTable.vue and
-// adapters/react/components/FdyTable.tsx. Kept here — plain ESM with a .d.ts sidecar — so the
+// adapters/react/components/FdyTable.tsx. Kept here, plain ESM with a .d.ts sidecar, so the
 // two adapters can't drift and so the logic is unit-testable under `node --test`
 // (test/table-model.test.mjs) without a framework runtime. Every function is pure: inputs are
 // never mutated (rows are sliced before sorting), so it is safe to call on each render.
@@ -34,15 +34,15 @@ function localDay(d) {
 }
 
 /**
- * @param {unknown} v @returns {string} ISO calendar day (yyyy-mm-dd) — lexicographically comparable
+ * @param {unknown} v @returns {string} ISO calendar day (yyyy-mm-dd), lexicographically comparable
  *
  * Two bugs lived here, both of which let a column SORT by date correctly and
- * FILTER by date wrongly — the worst pairing, because a working sort is what
+ * FILTER by date wrongly, the worst pairing, because a working sort is what
  * persuades you the header understands dates.
  *
  * 1. It sliced instead of parsing, while `toTime` (which the date SORT uses)
- *    parses. A column whose `value` returns a formatted date — the normal way
- *    to render one — gave `"18 Mar 2024"`, sliced to `"18 Mar 202"`, and
+ *    parses. A column whose `value` returns a formatted date, the normal way
+ *    to render one, gave `"18 Mar 2024"`, sliced to `"18 Mar 202"`, and
  *    compared as text against `"2024-03-18"`: every row failed, silently.
  * 2. A `Date` went through `toISOString`, which is UTC. At UTC+7 a date picked
  *    as the 18th is `2024-03-17T17:00Z`, so filtering from the 18th dropped it.
@@ -155,7 +155,7 @@ export function paginate(rows, pageIndex, pageSize) {
   return rows.slice(start, start + pageSize);
 }
 
-/** Distinct non-empty cell texts for a column, naturally sorted — the source for an enum filter. */
+/** Distinct non-empty cell texts for a column, naturally sorted, the source for an enum filter. */
 export function distinctValues(rows, column) {
   const seen = new Set();
   const out = [];
@@ -173,7 +173,7 @@ export function distinctValues(rows, column) {
  * The page to land on when the page SIZE changes: whichever page still holds the first row you were
  * already looking at.
  *
- * The two obvious answers are both wrong. Jumping to page 1 throws away your place on a long list —
+ * The two obvious answers are both wrong. Jumping to page 1 throws away your place on a long list,
  * you asked to see more rows, not to start over. Keeping the same INDEX can land past the end: page
  * 5 of 5 at twenty rows is page 2 of 2 at fifty, and index 4 is nowhere. Anchoring on the first
  * visible row is the only one that always resolves, and it is what the reader expects: the row they

package/adapters/react/components/FdyAppShell.tsx

@@ -0,0 +1,159 @@
+import type { JSX, ReactNode } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  NAV_QUERY,
+  applyShellState,
+  focusPanel,
+  restoreFocus,
+  trapTab,
+} from '../../core/app-shell.js';
+
+// A React wrapper over freeday's `.fdy-app` shell (src/components/app-shell.css). React port of
+// adapters/vue/components/FdyAppShell.vue, sharing adapters/core/app-shell.js so the two cannot
+// drift into two different focus traps.
+//
+// ONE model: `navOpen` means "the nav is visible to the reader". Above the nav breakpoint a hidden
+// nav is `--nav-collapsed`, below it a visible nav is `--nav-open`, the kit owns that mapping so an
+// app never reasons about the viewport to answer a question about its own UI.
+//
+// Omit `navOpen` and the component keeps its own, defaulting BY VIEWPORT: a column on a wide screen,
+// hidden on a narrow one. That default is why the prop is optional, a parent cannot express it as a
+// single initial value before it knows the viewport.
+
+export interface FdyAppShellProps {
+  navOpen?: boolean;
+  onNavOpenChange?: (open: boolean) => void;
+  title?: ReactNode;
+  toggleLabel?: string;
+  toggleIcon?: ReactNode;
+  skip?: ReactNode;
+  brand?: ReactNode;
+  nav?: ReactNode;
+  topbar?: ReactNode;
+  children?: ReactNode;
+}
+
+export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const restoreToRef = useRef<Element | null>(null);
+  /* Set while a viewport change is driving the state, so the effect below reconciles `inert` and
+     the classes but leaves FOCUS alone: a resize is not a reader asking to go somewhere. */
+  const fromResizeRef = useRef<boolean>(false);
+  const [overlay, setOverlay] = useState<boolean>(false);
+  const [uncontrolled, setUncontrolled] = useState<boolean>(true);
+
+  const controlled: boolean = props.navOpen !== undefined;
+  const navVisible: boolean = controlled ? props.navOpen === true : uncontrolled;
+
+  const setVisible = useCallback((next: boolean): void => {
+    if (!controlled) setUncontrolled(next);
+    if (props.onNavOpenChange !== undefined) props.onNavOpenChange(next);
+  }, [controlled, props.onNavOpenChange]);
+
+  /* The media listener reads these through refs and subscribes ONCE. Depending on navVisible would
+     resubscribe on every toggle and re-run the handler, and its "narrowing with the nav visible
+     hides it" rule would then fire on an ordinary open, closing the panel in the same tick the
+     reader opened it. */
+  const navVisibleRef = useRef<boolean>(navVisible);
+  navVisibleRef.current = navVisible;
+  const setVisibleRef = useRef<(next: boolean) => void>(setVisible);
+  setVisibleRef.current = setVisible;
+
+  // The media query owns `overlay`, and the two directions are not symmetrical. Narrowing with the
+  // nav visible would drop an overlay panel over a page nobody asked to leave, so it is hidden;
+  // widening is harmless, since a visible nav simply becomes the column again.
+  useEffect((): (() => void) => {
+    const media: MediaQueryList = window.matchMedia(NAV_QUERY);
+    const onChange = (): void => {
+      const nowOverlay: boolean = !media.matches;
+      setOverlay((was: boolean): boolean => {
+        if (was !== nowOverlay) fromResizeRef.current = true;
+        return nowOverlay;
+      });
+      if (nowOverlay && navVisibleRef.current) setVisibleRef.current(false);
+    };
+    // Mount: adopt the viewport without the hide-on-narrow side effect, nothing is open yet.
+    setOverlay(!media.matches);
+    if (!controlled) setUncontrolled(media.matches);
+    media.addEventListener('change', onChange);
+    return (): void => media.removeEventListener('change', onChange);
+  }, [controlled]);
+
+  // Focus moves only after the class change has been painted, or the panel is still off-canvas and
+  // the browser refuses to focus what it cannot lay out.
+  useEffect((): void => {
+    const el: HTMLDivElement | null = rootRef.current;
+    if (el === null) return;
+    applyShellState(el, { navVisible, overlay });
+    if (fromResizeRef.current) {
+      fromResizeRef.current = false;
+      return;
+    }
+    if (!overlay) return;
+    if (navVisible) restoreToRef.current = focusPanel(el);
+    else restoreFocus(el, restoreToRef.current);
+  }, [navVisible, overlay]);
+
+  useEffect((): (() => void) => {
+    const onKeydown = (e: KeyboardEvent): void => {
+      const el: HTMLDivElement | null = rootRef.current;
+      if (el === null || !overlay || !navVisible) return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        setVisible(false);
+        return;
+      }
+      trapTab(el, e);
+    };
+    document.addEventListener('keydown', onKeydown);
+    return (): void => document.removeEventListener('keydown', onKeydown);
+  }, [overlay, navVisible, setVisible]);
+
+  const shellClass: string = overlay
+    ? (navVisible ? 'fdy-app fdy-app--nav-open' : 'fdy-app')
+    : (navVisible ? 'fdy-app' : 'fdy-app fdy-app--nav-collapsed');
+
+  return (
+    <div ref={rootRef} className={shellClass}>
+      {props.skip}
+
+      <aside
+        className="fdy-app__sidebar"
+        onClick={(e): void => {
+          // Following a link in an overlay nav means "take me there", the panel must not stay over
+          // the page it was just asked for. On a wide viewport the nav is a column: nothing to close.
+          if (!overlay || !navVisible) return;
+          const target: HTMLElement | null = e.target as HTMLElement | null;
+          if (target !== null && target.closest('.fdy-nav__item') !== null) setVisible(false);
+        }}
+      >
+        {props.brand}
+        {props.nav}
+      </aside>
+
+      <div className="fdy-app__content">
+        <header className="fdy-app__topbar">
+          <button
+            className="fdy-app__navtoggle"
+            type="button"
+            aria-label={props.toggleLabel ?? 'Toggle navigation'}
+            onClick={(): void => setVisible(!navVisible)}
+          >{props.toggleIcon ?? '☰'}</button>
+
+          <h1 className="fdy-app__title">{props.title}</h1>
+
+          {props.topbar}
+        </header>
+
+        <main className="fdy-app__main">{props.children}</main>
+      </div>
+
+      <div
+        className="fdy-app__backdrop"
+        onClick={(): void => {
+          if (overlay && navVisible) setVisible(false);
+        }}
+      />
+    </div>
+  );
+}

package/adapters/react/components/FdyAutocomplete.tsx

@@ -3,7 +3,7 @@ import { useEffect, useId, useMemo, useRef, useState } from 'react';
 import { usePopover } from '../usePopover';
 
 // A controlled React port of freeday's autocomplete (src/freeday-autocomplete.js +
-// autocomplete.css): a WAI-ARIA APG *editable* combobox — a text input filters a listbox of
+// autocomplete.css): a WAI-ARIA APG *editable* combobox, a text input filters a listbox of
 // options as you type; picking one fills the input. `value` + `onChange` in place of the
 // enhancer's DOM mutation, so React owns the input. Filtering mirrors the enhancer exactly
 // (case-insensitive substring on the trimmed query); pass server-filtered `options` and it

package/adapters/react/components/FdyCascade.tsx

@@ -3,7 +3,7 @@ import { useEffect, useId, useMemo, useRef, useState } from 'react';
 import { usePopover } from '../usePopover';
 
 // A controlled React port of freeday's cascade select (src/freeday-cascade.js + cascade.css):
-// a hierarchical drill-down picker showing one level at a time — branches drill in, a back
+// a hierarchical drill-down picker showing one level at a time, branches drill in, a back
 // control ascends, a leaf selects and the value is the leaf's value (the display is the full
 // path). The enhancer's data model is a hidden nested <ul>; here it is a typed tree, which is
 // what a framework app actually has. `value` + `onChange` in place of the DOM mutation.

package/adapters/react/components/FdyCfl.tsx

@@ -21,7 +21,7 @@ export interface CflPage<Row> {
 }
 
 export interface FdyCflProps<Row extends Record<string, unknown>> {
-  /** Single: `Row | null`. With `multiple`, an array — `Row[] | null`, where null and [] both mean
+  /** Single: `Row | null`. With `multiple`, an array, `Row[] | null`, where null and [] both mean
    *  nothing picked. The enhancer has had `data-fdy-cfl-multiple` all along; this is the typed
    *  wrappers catching up (#019). */
   value: Row | Row[] | null;
@@ -30,7 +30,7 @@ export interface FdyCflProps<Row extends Record<string, unknown>> {
   columns: ReadonlyArray<CflColumn<Row>>;
   display: (row: Row) => string;
   rowKey: (row: Row) => string;
-  /** Advisory only — the caller's `fetchPage` owns paging; kept for API documentation. */
+  /** Advisory only, the caller's `fetchPage` owns paging; kept for API documentation. */
   pageSize?: number;
   /** The dialog's heading. Default 'Choose data', matching the Blazor adapter's `Title`. */
   title?: string;
@@ -81,7 +81,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
   const rowId = (index: number): string => `${baseId}-row-${index}`;
 
   /* Unsetting is not "picking nothing": it must not touch the dialog, and focus must land on a
-     control that still exists — the trigger beside it, since this button disappears with the value. */
+     control that still exists, the trigger beside it, since this button disappears with the value. */
   const clearLabelText: string = props.clearLabel ?? 'Clear selection';
   const clearValue = (): void => {
     setPicked([]);
@@ -106,7 +106,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
 
   // Out-of-order guard: every fetch takes a monotonically increasing token; a resolved or
   // rejected page is applied only if it still owns the latest token. A newer search, a
-  // load-more, a dialog close, or an unmount all bump it — this keeps a slow stale response
+  // load-more, a dialog close, or an unmount all bump it, this keeps a slow stale response
   // from overwriting fresh results (or a closed/unmounted component's state).
   const reqIdRef = useRef<number>(0);
   // In-memory cache keyed by `${query}::${page}`, cleared on open and on close.
@@ -117,7 +117,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
 
   const isDisabled: boolean = props.disabled === true;
   const isReadonly: boolean = props.readonly === true;
-  /* `display()` takes one row, so in multi the field states HOW MANY — naming one of six would be a
+  /* `display()` takes one row, so in multi the field states HOW MANY, naming one of six would be a
      lie, and naming all six does not fit a control that is 22rem wide. */
   const currentRows: Row[] = Array.isArray(props.value)
     ? props.value
@@ -137,7 +137,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
       ? props.display(props.value as Row)
       : '';
   // The results <table> (owner of `resultsId`) only renders in the rows branch, so gate the
-  // search input's aria refs on rows existing — otherwise they'd dangle during loading/empty/error.
+  // search input's aria refs on rows existing, otherwise they'd dangle during loading/empty/error.
   const hasRows: boolean = rows.length > 0;
   const controlsId: string | undefined = hasRows ? resultsId : undefined;
   const activeDescendant: string | undefined = hasRows && activeIndex >= 0 ? rowId(activeIndex) : undefined;
@@ -156,7 +156,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
     try {
       const cached: CflPage<Row> | undefined = cacheRef.current.get(key);
       const res: CflPage<Row> = cached ?? (await props.fetchPage(targetQuery, targetPage));
-      if (token !== reqIdRef.current) return; // stale — a newer request has started
+      if (token !== reqIdRef.current) return; // stale, a newer request has started
       if (cached === undefined) cacheRef.current.set(key, res);
       const copy: Row[] = res.rows.slice(); // never mutate the caller's array
       setRows((prev: Row[]): Row[] => (append ? prev.concat(copy) : copy));
@@ -171,7 +171,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
     }
   }
 
-  // Mirrors Vue's `retry()`: only `lastPage`/`lastAppend` are frozen from the failed request —
+  // Mirrors Vue's `retry()`: only `lastPage`/`lastAppend` are frozen from the failed request,
   // the query is re-read live so a retry after editing the search box (within the debounce
   // window) uses what's currently typed, not a stale snapshot.
   function retry(): void {
@@ -203,7 +203,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
     setActiveIndex(clamped);
   }
 
-  // Scroll the active row into view once it (re)renders — React's analogue of Vue's
+  // Scroll the active row into view once it (re)renders. React's analogue of Vue's
   // `nextTick(() => scrollIntoView(...))`; fires for both keyboard nav and row hover, same as
   // the Vue source's `setActive`.
   useEffect((): void => {
@@ -225,7 +225,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
     );
   }
 
-  /* A click means "tick this" in multi and "this is my answer" in single — the whole difference. */
+  /* A click means "tick this" in multi and "this is my answer" in single, the whole difference. */
   function onRowClick(row: Row): void {
     if (isMultiple) togglePick(row);
     else commit(row);
@@ -321,7 +321,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
   }
 
   // Unmount safety: bump the token so any in-flight fetch's setState is dropped, and cancel a
-  // pending debounce — mirrors Vue's onBeforeUnmount plus the same token trick onClose uses.
+  // pending debounce, mirrors Vue's onBeforeUnmount plus the same token trick onClose uses.
   useEffect((): (() => void) => {
     return (): void => {
       reqIdRef.current++;

package/adapters/react/components/FdyDateRange.tsx

@@ -5,7 +5,7 @@ import { FdyDatepicker } from './FdyDatepicker';
 // two linked FdyDatepickers where the end can't precede the start (start.max = end, end.min = start).
 // `value` + `onChange` in place of Vue's `v-model`; this composes the single-date picker rather than
 // re-implementing the calendar. Note: the vanilla enhancer's cross-calendar `.in-range` day shading
-// is not reproduced (each picker is independent) — the min/max linkage is what keeps the range valid.
+// is not reproduced (each picker is independent), the min/max linkage is what keeps the range valid.
 
 export interface DateRangeValue {
   start: string | null;
@@ -19,7 +19,7 @@ export interface FdyDateRangeProps {
   max?: string;
   locale?: string;
   disabled?: boolean;
-  /** Locked/view mode for both pickers — focusable, values shown, but can't be opened or changed. */
+  /** Locked/view mode for both pickers, focusable, values shown, but can't be opened or changed. */
   readonly?: boolean;
   invalid?: boolean;
   describedby?: string;

package/adapters/react/components/FdyDatepicker.tsx

@@ -55,7 +55,7 @@ export interface FdyDatepickerProps {
   ariaLabelledby?: string;
   /** Show a clear (×) button in the trigger when a date is set, so an optional date can be unset. Calls onChange('') to reset. Off by default. */
   clearable?: boolean;
-  /** aria-label for the previous-month nav button. Default 'Previous month' — override for non-English UIs (month/weekday names already follow `locale`). */
+  /** aria-label for the previous-month nav button. Default 'Previous month', override for non-English UIs (month/weekday names already follow `locale`). */
   /** aria-label for the title button that drills to the month grid. Default 'Choose month'. */
   chooseMonthLabel?: string;
   /** aria-labels for the year arrows shown in the month grid. Defaults 'Previous year' / 'Next year'. */
@@ -132,7 +132,7 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
   const pendingFocusRef = useRef<string | null>(null);
 
   const [open, setOpen] = useState<boolean>(false);
-  /* 'days' | 'months' — the calendar drills one level up instead of growing furniture beside the
+  /* 'days' | 'months', the calendar drills one level up instead of growing furniture beside the
      title. Before this the only pointer route to another month was one click per month. */
   const [mode, setMode] = useState<'days' | 'months' | 'years'>('days');
   const [focusMonth, setFocusMonth] = useState<number>(0);
@@ -224,7 +224,7 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
     return false;
   }
 
-  /** A month is only unreachable when the WHOLE month falls outside min/max — a range that sits
+  /** A month is only unreachable when the WHOLE month falls outside min/max, a range that sits
    *  inside one month disables both ends while the middle is perfectly selectable. */
   function isMonthDisabled(year: number, month: number): boolean {
     const first: Date = new Date(year, month, 1);
@@ -429,7 +429,7 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
     closePanel(true);
   }
 
-  // Clear (reset to empty). Calls onChange('') — parseISO('') is null, so the placeholder shows again.
+  // Clear (reset to empty). Calls onChange(''), parseISO('') is null, so the placeholder shows again.
   function clearValue(): void {
     props.onChange('');
     setOpen(false);
@@ -506,7 +506,7 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
   }
 
   // Close when focus leaves the control entirely (e.g. Shift+Tab off the trigger).
-  /* A null relatedTarget means focus fell to <body> — which is what happens when the element the
+  /* A null relatedTarget means focus fell to <body>, which is what happens when the element the
      user just pressed is REMOVED by the click it triggered (drilling into the month grid replaces
      the grid, and with it the cell that had focus). That is not focus leaving the control, and
      closing on it made the panel vanish mid-navigation. A pointer that really lands outside is

package/adapters/react/components/FdyDrawer.tsx

@@ -2,7 +2,7 @@ import type { JSX, ReactNode } from 'react';
 import { useEffect, useId, useRef } from 'react';
 
 // A controlled React wrapper over freeday's `.fdy-drawer` native <dialog> side panel
-// (src/components/drawer.css). React port of adapters/vue/components/FdyDrawer.vue — the same
+// (src/components/drawer.css). React port of adapters/vue/components/FdyDrawer.vue, the same
 // controlled glue as FdyModal (guarded showModal()/close(), onCancel + preventDefault so Esc routes
 // through app state, backdrop-click via `event.target === dialogEl`) applied to a drawer that anchors
 // left (default) or right. Native <dialog> supplies the focus trap, focus restore, top-layer stacking