@cahyo-dimas/freeday 3.8.0 → 3.9.0

package/adapters/blazor/FdyTable.razor.cs

@@ -116,6 +116,39 @@ public partial class FdyTable<TRow>
     /// <summary>Bulk-bar actions (Blazor equivalent of Vue's <c>bulk-actions</c> slot).</summary>
     [Parameter] public RenderFragment? BulkContent { get; set; }
 
+    // The footer's six strings, forwarded to the FdyTableFooter this table draws itself. 3.8.0 gave
+    // the footer those parameters and this table passed none of them on, so the hatch reached every
+    // footer except the one almost every page uses, and the documented way out was to switch the
+    // footer off and render it yourself: a door that opens only if you stop using the table. Flat
+    // parameters carrying the footer's own names, so moving between the two routes moves a
+    // parameter rather than reshaping it.
+    //
+    // Nullable, unlike SelectedText and its four neighbours above, which this component renders
+    // itself and therefore defaults itself. These six are rendered by FdyTableFooter, which already
+    // holds their English; a default repeated here would be a second copy to keep in step, and the
+    // two copies would disagree the first time one of them was edited.
+
+    /// <summary>Footer range line, <c>{from}</c> <c>{to}</c> <c>{total}</c> substituted.
+    /// Null leaves <c>FdyTableFooter</c>'s default, <c>Showing {from}–{to} of {total}</c>.</summary>
+    [Parameter] public string? InfoText { get; set; }
+
+    /// <summary>Footer: the visible word beside the rows-per-page control, which also names it.
+    /// Null leaves the default, <c>Rows</c>.</summary>
+    [Parameter] public string? PageSizeLabel { get; set; }
+
+    /// <summary>Footer: accessible name of the pager landmark. Null leaves <c>Pagination</c>.</summary>
+    [Parameter] public string? PaginationLabel { get; set; }
+
+    /// <summary>Footer: accessible name of the previous-page arrow. Null leaves <c>Previous page</c>.</summary>
+    [Parameter] public string? PrevLabel { get; set; }
+
+    /// <summary>Footer: accessible name of the next-page arrow. Null leaves <c>Next page</c>.</summary>
+    [Parameter] public string? NextLabel { get; set; }
+
+    /// <summary>Footer: accessible name of a numbered page button, <c>{n}</c> substituted. Null
+    /// leaves <c>Go to page {n}</c>.</summary>
+    [Parameter] public string? PageLabel { get; set; }
+
     private FdySortState? _internalSort;
     private Dictionary<string, FdyColumnFilter> _internalFilters = new();
     private int _internalPageIndex;

package/adapters/core/month-grid.d.ts

@@ -0,0 +1,116 @@
+// Types for the framework-agnostic month and year grid logic (adapters/core/month-grid.js).
+// Shared by FdyDatepicker and FdyMonthpicker in the Vue and React adapters.
+
+/** A whole month as ISO `YYYY-MM`, e.g. `'2026-10'`. The format a month picker answers with. */
+export type FdyMonth = string;
+
+/** One cell of the twelve-cell month grid, ready to render. */
+export interface FdyMonthCell {
+  /** 0-11, the month's index in its year. */
+  index: number;
+  /** What the cell shows, a short month name in the active locale. */
+  label: string;
+  /** The cell's accessible name: the month and its year, spelled out in the active locale. */
+  ariaLabel: string;
+  selected: boolean;
+  today: boolean;
+  /** The whole month falls outside min/max, so it cannot be picked or navigated into. */
+  disabled: boolean;
+  /** Holds the grid's single `tabindex="0"`. */
+  focusable: boolean;
+}
+
+/** One cell of the twelve-cell year grid. */
+export interface FdyYearCell {
+  year: number;
+  selected: boolean;
+  today: boolean;
+  disabled: boolean;
+  focusable: boolean;
+}
+
+/** The two Intl formatters a month grid renders through. */
+export interface FdyMonthFormatters {
+  /** Short month name, for the cell's text. */
+  cell: Intl.DateTimeFormat;
+  /** Month and year spelled out, for the cell's accessible name and the trigger's value. */
+  name: Intl.DateTimeFormat;
+}
+
+export interface FdyMonthGridView {
+  year: number;
+  selected: Date | null;
+  min: Date | null;
+  max: Date | null;
+  /** Which month index holds the roving tabindex. */
+  focusMonth: number;
+  formatters: FdyMonthFormatters;
+  /** Overridable only so a test can pin "today"; defaults to now. */
+  today?: Date;
+}
+
+export interface FdyYearGridView {
+  pageStart: number;
+  selected: Date | null;
+  min: Date | null;
+  max: Date | null;
+  focusYear: number;
+  today?: Date;
+}
+
+/**
+ * What a key press in a grid means. `choose` is the one the two components answer differently:
+ * `FdyMonthpicker` commits the month, `FdyDatepicker` walks down into its days.
+ */
+export type FdyGridAction = 'focus' | 'choose' | 'close' | 'none';
+
+export interface FdyMonthKeyIntent {
+  action: FdyGridAction;
+  /** 0-11, already wrapped inside the year on screen. */
+  index: number;
+  /** Years to step the view by, which only PageUp and PageDown set. */
+  yearDelta: number;
+}
+
+export interface FdyYearKeyIntent {
+  action: FdyGridAction;
+  year: number;
+}
+
+/** A year page holds twelve years, so the grid matches the month grid's shape. */
+export declare const YEARS_PER_PAGE: number;
+
+/** A Date as `YYYY-MM`. The day is dropped. */
+export declare function toISOMonth(d: Date): FdyMonth;
+
+/** Read `YYYY-MM` or `YYYY-MM-DD` as the first day of the month named; null when unparseable. */
+export declare function parseISOMonth(s: string | null | undefined): Date | null;
+
+/** The `lang` the page declares, then `en`. Never the browser's language, which is the whole point. */
+export declare function pageLocale(): string;
+
+export declare function startOfDay(d: Date): Date;
+export declare function startOfMonth(d: Date): Date;
+export declare function addMonths(d: Date, n: number): Date;
+
+/** True only when the WHOLE month falls outside the bounds. */
+export declare function monthDisabled(year: number, month: number, min: Date | null, max: Date | null): boolean;
+
+/** True only when every month in the year falls outside the bounds. */
+export declare function yearDisabled(year: number, min: Date | null, max: Date | null): boolean;
+
+/** Where the aligned page holding this year starts (2016 for 2026). */
+export declare function yearPageStart(year: number): number;
+
+/** The year grid's title, naming the page it shows. */
+export declare function yearRangeLabel(pageStart: number): string;
+
+export declare function monthFormatters(locale: string): FdyMonthFormatters;
+
+export declare function monthCells(view: FdyMonthGridView): FdyMonthCell[];
+
+export declare function yearCells(view: FdyYearGridView): FdyYearCell[];
+
+export declare function monthKeyIntent(key: string, focusMonth: number): FdyMonthKeyIntent;
+
+export declare function yearKeyIntent(key: string, focusYear: number): FdyYearKeyIntent;

package/adapters/core/month-grid.js

@@ -0,0 +1,234 @@
+// Freeday, month and year grid logic, framework-agnostic (pure, zero dependencies).
+//
+// The twelve-cell month grid and the twelve-cell year grid behind it: which cell is selected, which
+// is out of bounds, how a year page is numbered, and what a key press means. Shared by
+// `FdyDatepicker` (where both grids are navigation on the way to a day) and `FdyMonthpicker` (where
+// the month grid is the answer), in Vue and in React, so four components read one copy.
+//
+// It is here rather than in each component because of what this release cost. The panel-position
+// logic existed in four copies; #079 was found in one, fixed in one, and shipped broken in the
+// other three, and three items of 3.9.0 went on cleaning that up. `FdyMonthpicker` needs the month
+// grid, which would have made the fifth copy of it, so the rule moved out first.
+//
+// The vanilla enhancer (src/freeday-datepicker.js) deliberately does NOT import this, for the
+// reason adapters/core/app-shell.js records: dist/freeday.js is a plain IIFE concatenation with no
+// module system. That leaves two implementations, and browser/month-mode.mjs and
+// browser/monthpicker.mjs hold both to the same observable behaviour.
+//
+// Everything here is a pure function over its arguments. State, refs, focus scheduling and markup
+// stay with the caller, because those are the parts Vue and React genuinely do differently.
+
+/** A year page holds twelve years, so the grid is the same shape as the month grid above it. */
+export const YEARS_PER_PAGE = 12;
+
+function pad(n) {
+  return n < 10 ? `0${n}` : `${n}`;
+}
+
+/** A Date as the `YYYY-MM` a month picker reports. The day is dropped, which is the point. */
+export function toISOMonth(d) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}`;
+}
+
+/**
+ * Read `YYYY-MM` or `YYYY-MM-DD` as the first day of the month named.
+ *
+ * Both shapes on purpose, and the dropped day is why: a bound of `2026-03` lands on March 1st,
+ * which `monthDisabled` then compares a whole month against correctly at either end, so an app can
+ * pass the strings it already stores. A full date still works for a form that keeps one format
+ * across all of its bounds.
+ *
+ * @param {string | null | undefined} s
+ * @returns {Date | null} null for an empty, short or unparseable value
+ */
+export function parseISOMonth(s) {
+  if (s === null || s === undefined || s === '') return null;
+  const parts = s.split('-');
+  if (parts.length < 2) return null;
+  const d = new Date(Number(parts[0]), Number(parts[1]) - 1, parts.length > 2 ? Number(parts[2]) : 1);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * The language the page declares, which is what COMPONENTS.md has always promised and what the
+ * vanilla enhancer has always done.
+ *
+ * Handing `undefined` to Intl instead falls back to the BROWSER's language, so an Indonesian reader
+ * saw Indonesian month names inside a kit that is English on every other path, and an Indonesian
+ * page read by an English browser got English ones. That second case is the symptom the month
+ * picker was asked for, so the fallback has to be the page.
+ */
+export function pageLocale() {
+  if (typeof document === 'undefined') return 'en';
+  // `||`, not `??`: an empty `lang=""` is not null and Intl throws RangeError on it.
+  return document.documentElement.getAttribute('lang') || 'en';
+}
+
+export function startOfDay(d) {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+
+export function startOfMonth(d) {
+  return new Date(d.getFullYear(), d.getMonth(), 1);
+}
+
+export function addMonths(d, n) {
+  const x = new Date(d);
+  x.setMonth(x.getMonth() + n);
+  return x;
+}
+
+/**
+ * Is this whole month outside the bounds?
+ *
+ * Only when the WHOLE month is, which is why it reads the bounds directly instead of asking whether
+ * both ends of the month are disabled days: a range that sits INSIDE one month disables both of its
+ * ends while the middle stays perfectly selectable.
+ *
+ * @param {number} year
+ * @param {number} month 0-11
+ * @param {Date | null} min
+ * @param {Date | null} max
+ */
+export function monthDisabled(year, month, min, max) {
+  const first = new Date(year, month, 1);
+  const last = new Date(year, month + 1, 0);
+  if (min !== null && startOfDay(last).getTime() < startOfDay(min).getTime()) return true;
+  if (max !== null && startOfDay(first).getTime() > startOfDay(max).getTime()) return true;
+  return false;
+}
+
+/** Unreachable only when EVERY month in the year is, the same rule one level up. */
+export function yearDisabled(year, min, max) {
+  if (min !== null && startOfDay(new Date(year, 11, 31)).getTime() < startOfDay(min).getTime()) return true;
+  if (max !== null && startOfDay(new Date(year, 0, 1)).getTime() > startOfDay(max).getTime()) return true;
+  return false;
+}
+
+/**
+ * Where the page holding this year starts: 2016 for 2026, so pages tile as 2016-2027, 2028-2039.
+ * Anchoring the page on the year in view would make the arrows land on overlapping windows, and the
+ * same year would sit somewhere different every step.
+ */
+export function yearPageStart(year) {
+  return Math.floor(year / YEARS_PER_PAGE) * YEARS_PER_PAGE;
+}
+
+/** The year grid's title, naming the page it shows. */
+export function yearRangeLabel(pageStart) {
+  return `${pageStart} – ${pageStart + YEARS_PER_PAGE - 1}`;
+}
+
+/**
+ * The two Intl formatters a month grid needs: `cell` writes what a reader sees in the cell, `name`
+ * writes its accessible name and the value in the trigger. Built once per locale by the caller,
+ * because both frameworks memoize and `new Intl.DateTimeFormat` is not cheap.
+ */
+export function monthFormatters(locale) {
+  return {
+    cell: new Intl.DateTimeFormat(locale, { month: 'short' }),
+    name: new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }),
+  };
+}
+
+/**
+ * The twelve cells of one year's month grid.
+ *
+ * @param {{ year: number, selected: Date | null, min: Date | null, max: Date | null,
+ *           focusMonth: number, formatters: { cell: Intl.DateTimeFormat, name: Intl.DateTimeFormat },
+ *           today?: Date }} view
+ */
+export function monthCells(view) {
+  const today = view.today ?? new Date();
+  return Array.from({ length: 12 }, (_unused, index) => {
+    const cellDate = new Date(view.year, index, 1);
+    return {
+      index,
+      label: view.formatters.cell.format(cellDate),
+      ariaLabel: view.formatters.name.format(cellDate),
+      selected: view.selected !== null && view.selected.getFullYear() === view.year && view.selected.getMonth() === index,
+      today: today.getFullYear() === view.year && today.getMonth() === index,
+      disabled: monthDisabled(view.year, index, view.min, view.max),
+      focusable: index === view.focusMonth,
+    };
+  });
+}
+
+/**
+ * The twelve cells of one year page.
+ *
+ * @param {{ pageStart: number, selected: Date | null, min: Date | null, max: Date | null,
+ *           focusYear: number, today?: Date }} view
+ */
+export function yearCells(view) {
+  const thisYear = (view.today ?? new Date()).getFullYear();
+  return Array.from({ length: YEARS_PER_PAGE }, (_unused, index) => {
+    const year = view.pageStart + index;
+    return {
+      year,
+      selected: view.selected !== null && view.selected.getFullYear() === year,
+      today: thisYear === year,
+      disabled: yearDisabled(year, view.min, view.max),
+      focusable: year === view.focusYear,
+    };
+  });
+}
+
+/**
+ * What a key press in the month grid means, with the wrap already applied.
+ *
+ * `choose` is deliberately not called `select`: whether choosing a month commits a value or walks
+ * down into its days is the one thing the two components disagree about, and that decision belongs
+ * to them. `none` means the key was not ours, so the caller leaves the event alone.
+ *
+ * Arrows move one or three months and WRAP inside the year on screen, which is why `index` can come
+ * back on the far side without `yearDelta` moving. PageUp and PageDown are the keys that change the
+ * year, holding the month still (WAI-ARIA APG).
+ *
+ * @param {string} key a KeyboardEvent.key
+ * @param {number} focusMonth 0-11
+ * @returns {{ action: 'focus' | 'choose' | 'close' | 'none', index: number, yearDelta: number }}
+ */
+export function monthKeyIntent(key, focusMonth) {
+  const focus = (raw, yearDelta) => ({ action: 'focus', index: (raw + 12) % 12, yearDelta });
+  switch (key) {
+    case 'ArrowLeft': return focus(focusMonth - 1, 0);
+    case 'ArrowRight': return focus(focusMonth + 1, 0);
+    case 'ArrowUp': return focus(focusMonth - 3, 0);
+    case 'ArrowDown': return focus(focusMonth + 3, 0);
+    case 'Home': return focus(0, 0);
+    case 'End': return focus(11, 0);
+    case 'PageUp': return focus(focusMonth, -1);
+    case 'PageDown': return focus(focusMonth, 1);
+    case 'Enter':
+    case ' ': return { action: 'choose', index: focusMonth, yearDelta: 0 };
+    case 'Escape': return { action: 'close', index: focusMonth, yearDelta: 0 };
+    default: return { action: 'none', index: focusMonth, yearDelta: 0 };
+  }
+}
+
+/**
+ * What a key press in the year grid means. `choose` here is always navigation, in both components:
+ * a year is never an answer, so nothing is committed from this grid.
+ *
+ * @param {string} key a KeyboardEvent.key
+ * @param {number} focusYear
+ * @returns {{ action: 'focus' | 'choose' | 'close' | 'none', year: number }}
+ */
+export function yearKeyIntent(key, focusYear) {
+  const focus = (year) => ({ action: 'focus', year });
+  switch (key) {
+    case 'ArrowLeft': return focus(focusYear - 1);
+    case 'ArrowRight': return focus(focusYear + 1);
+    case 'ArrowUp': return focus(focusYear - 3);
+    case 'ArrowDown': return focus(focusYear + 3);
+    case 'Home': return focus(yearPageStart(focusYear));
+    case 'End': return focus(yearPageStart(focusYear) + YEARS_PER_PAGE - 1);
+    case 'PageUp': return focus(focusYear - YEARS_PER_PAGE);
+    case 'PageDown': return focus(focusYear + YEARS_PER_PAGE);
+    case 'Enter':
+    case ' ': return { action: 'choose', year: focusYear };
+    case 'Escape': return { action: 'close', year: focusYear };
+    default: return { action: 'none', year: focusYear };
+  }
+}