@cahyo-dimas/freeday 3.7.0 → 3.9.0

package/adapters/blazor/FdyDatepicker.razor.cs

@@ -5,11 +5,31 @@ namespace Freeday.Blazor;
 
 public partial class FdyDatepicker
 {
-    /// <summary>Selected date as an ISO string (<c>yyyy-MM-dd</c>), or "" when unset.
+    /// <summary>Selected date as an ISO string (<c>yyyy-MM-dd</c>), or <c>yyyy-MM</c> when
+    /// <see cref="Mode"/> is <see cref="FdyDatepickerMode.Month"/>, or "" when unset.
     /// Two-way bindable via <c>@bind-Value</c>.</summary>
     [Parameter] public string? Value { get; set; }
     [Parameter] public EventCallback<string?> ValueChanged { get; set; }
 
+    /// <summary>What the picker answers with. <see cref="FdyDatepickerMode.Day"/> (default) is the
+    /// calendar as it always was. <see cref="FdyDatepickerMode.Month"/> opens on the month grid,
+    /// stops there, and reports <c>yyyy-MM</c>.</summary>
+    [Obsolete("Use FdyMonthpicker for a month. This parameter makes Value, Min and Max carry " +
+              "yyyy-MM-dd or yyyy-MM while a different parameter decides which, so the binding " +
+              "cannot state what to store in it. Still works, unchanged, and removed in 4.0.")]
+    [Parameter] public FdyDatepickerMode Mode { get; set; } = FdyDatepickerMode.Day;
+
+    /* null rather than "day" for the default: an attribute the enhancer does not need is an
+       attribute no reader of the seed has to interpret, and the enhancer's own check is
+       `=== 'month'`, so the day path is the absence of this.
+
+       The pragma is the kit reading its OWN deprecated member, which is the one place that has to
+       keep doing so: the promise is that `Mode` keeps working until 4.0, and it cannot work if the
+       seed stops looking at it. Scoped to these two lines so every other use still warns. */
+#pragma warning disable CS0618
+    private string? ModeAttribute => Mode == FdyDatepickerMode.Month ? "month" : null;
+#pragma warning restore CS0618
+
     /// <summary>Accessible label for the trigger.</summary>
     [Parameter] public string? Label { get; set; }
     [Parameter] public string? Placeholder { get; set; }
@@ -83,3 +103,18 @@ public partial class FdyDatepicker
     /// <summary>The detail shape of the enhancer's <c>fdy-datepicker-change</c> event.</summary>
     public sealed record ChangeDetail(string? Value, string? Date);
 }
+
+/// <summary>What <see cref="FdyDatepicker"/> answers with.</summary>
+/// <remarks>The enum goes with <see cref="FdyDatepicker.Mode"/> in 4.0, so only
+/// <see cref="Day"/> is left unmarked: it names the behaviour a picker with no
+/// <c>Mode</c> already has, and writing it changes nothing.</remarks>
+public enum FdyDatepickerMode
+{
+    /// <summary>A single day, reported as <c>yyyy-MM-dd</c>.</summary>
+    Day,
+
+    /// <summary>A whole month, reported as <c>yyyy-MM</c>.</summary>
+    [Obsolete("Use FdyMonthpicker, whose Value is yyyy-MM and has no Mode to read. " +
+              "Still works, unchanged, and removed in 4.0.")]
+    Month,
+}

package/adapters/blazor/FdyMonthpicker.razor

@@ -0,0 +1,29 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyMonthpicker>
+
+@* Seed-based wrapper over freeday-datepicker.js in its month mode: the enhancer builds the
+   input-styled trigger + calendar popover from this empty div, opens on the month grid, and emits
+   fdy-datepicker-change. The enhancer owns that DOM, so we render the seed once
+   (ShouldRender => false) and read the picked month back through @bind-Value.
+
+   data-mode="month" is written here rather than taken as a parameter. That is the difference
+   between this component and FdyDatepicker: Value has one format, yyyy-MM, because nothing the
+   caller passes can change it. *@
+<div @ref="Root" data-fdy-datepicker
+     data-mode="month"
+     data-value="@Value"
+     data-label="@Label"
+     data-placeholder="@Placeholder"
+     data-min="@Min"
+     data-max="@Max"
+     data-id="@Id"
+     data-describedby="@Describedby"
+     data-disabled="@(Disabled ? "true" : null)"
+     data-readonly="@(Readonly ? "true" : null)"
+     data-invalid="@(Invalid ? "true" : null)"
+     data-fdy-text-prev-year="@PrevYearLabel"
+     data-fdy-text-next-year="@NextYearLabel"
+     data-fdy-text-prev-years="@PrevYearsLabel"
+     data-fdy-text-next-years="@NextYearsLabel"
+     data-fdy-text-choose-year="@ChooseYearLabel"
+     data-fdy-text-back-to-months="@BackToMonthsLabel"></div>

package/adapters/blazor/FdyMonthpicker.razor.cs

@@ -0,0 +1,102 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+/// <summary>
+/// A picker that answers with a whole month (<c>yyyy-MM</c>).
+/// </summary>
+/// <remarks>
+/// <para>This is the replacement for <c>FdyDatepicker</c> with <c>Mode="FdyDatepickerMode.Month"</c>,
+/// which shipped in 3.8.0 and is deprecated. There, <c>Value</c> is one <c>string?</c> holding
+/// <c>yyyy-MM-dd</c> or <c>yyyy-MM</c> and a different parameter decides which, so nothing about
+/// the binding tells a caller what to store in it. Here it has one format and there is no
+/// <c>Mode</c>. The deprecated spelling keeps working until 4.0.</para>
+/// <para>It is a separate seed rather than a wrapper around <c>FdyDatepicker</c>: that component
+/// renders once and then hands its DOM to the enhancer (<c>ShouldRender =&gt; !Hydrated</c>), so
+/// nesting it would mean forwarding an <c>ElementReference</c> and an event subscription through a
+/// component that owns neither. The logic the two share is the enhancer itself, which both reach
+/// through <c>FreedayDatepicker.init</c>, and that is already one copy.</para>
+/// <para>Month names come from the page's <c>&lt;html lang&gt;</c> through <c>Intl</c>, which is
+/// what <c>&lt;input type="month"&gt;</c> cannot do: it names the month in the browser's language.
+/// So an Indonesian page reads <c>Oktober 2026</c> with nothing configured.</para>
+/// </remarks>
+public partial class FdyMonthpicker
+{
+    /// <summary>The chosen month as an ISO string (<c>yyyy-MM</c>), or "" when unset. One format,
+    /// always. Two-way bindable via <c>@bind-Value</c>.</summary>
+    [Parameter] public string? Value { get; set; }
+    [Parameter] public EventCallback<string?> ValueChanged { get; set; }
+
+    /// <summary>Accessible label for the trigger. Defaults to the enhancer's <c>Month</c>.</summary>
+    [Parameter] public string? Label { get; set; }
+
+    /// <summary>Shown while nothing is picked. Defaults to the enhancer's <c>Choose a month</c>.</summary>
+    [Parameter] public string? Placeholder { get; set; }
+
+    /// <summary>Earliest selectable month (ISO <c>yyyy-MM</c>; a full <c>yyyy-MM-dd</c> is read too,
+    /// as its own month). A bound that falls inside a month leaves that month pickable.</summary>
+    [Parameter] public string? Min { get; set; }
+
+    /// <summary>Latest selectable month.</summary>
+    [Parameter] public string? Max { get; set; }
+
+    /// <summary>Id for the trigger the enhancer builds, so a form's own label can point at it.</summary>
+    [Parameter] public string? Id { get; set; }
+
+    /// <summary>Id of the help or error text the trigger describes itself with.</summary>
+    [Parameter] public string? Describedby { get; set; }
+
+    /// <summary>Greyed and out of the tab order.</summary>
+    [Parameter] public bool Disabled { get; set; }
+
+    /// <summary>Locked/view mode: focusable and showing its month, but the calendar will not open.
+    /// Unlike <see cref="Disabled"/> it keeps tab order and is not greyed.</summary>
+    [Parameter] public bool Readonly { get; set; }
+
+    /// <summary>Marks the field invalid (<c>aria-invalid</c> + the error styling).</summary>
+    [Parameter] public bool Invalid { get; set; }
+
+    /* The calendar's navigation labels, and only the ones this picker shows. Month NAMES follow the
+       page's `lang` through Intl and need nothing here. The day grid's own arrows are absent along
+       with the day grid, so there is no PrevMonthLabel to pass: the arrows beside a month grid step
+       a YEAR. Leave one null and the enhancer's English default stands. */
+    [Parameter] public string? PrevYearLabel { get; set; }
+    [Parameter] public string? NextYearLabel { get; set; }
+    [Parameter] public string? PrevYearsLabel { get; set; }
+    [Parameter] public string? NextYearsLabel { get; set; }
+
+    /// <summary>The title button that drills into the year grid. <c>{label}</c> is the year shown.</summary>
+    [Parameter] public string? ChooseYearLabel { get; set; }
+
+    /// <summary>The year grid's title, back to months. <c>{start}</c> and <c>{end}</c> are the page range.</summary>
+    [Parameter] public string? BackToMonthsLabel { get; set; }
+
+    protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayDatepicker.init", Root);
+
+    protected override async ValueTask OnHydratedAsync()
+        => await SubscribeAsync("fdy-datepicker-change", nameof(OnChange));
+
+    // The enhancer owns the built trigger + calendar; never let Blazor re-render the seed.
+    protected override bool ShouldRender() => !Hydrated;
+
+    /* Which is why the three states are pushed rather than re-rendered: the seed is written once,
+       so a page that disables this field later would otherwise be ignored in silence. */
+    protected override async Task OnParametersSetAsync()
+    {
+        if (!Hydrated) return;
+        await JS.InvokeVoidAsync("FreedayDatepicker.setState", Root,
+            new { disabled = Disabled, @readonly = Readonly, invalid = Invalid });
+    }
+
+    /// <summary>Invoked by the bridge when the user picks (or clears) a month.</summary>
+    [JSInvokable]
+    public async Task OnChange(ChangeDetail detail)
+    {
+        Value = detail.Value;
+        await ValueChanged.InvokeAsync(detail.Value);
+    }
+
+    /// <summary>The detail shape of the enhancer's <c>fdy-datepicker-change</c> event.</summary>
+    public sealed record ChangeDetail(string? Value, string? Date);
+}

package/adapters/blazor/FdyTable.razor

@@ -146,6 +146,11 @@
 
     @if (Pager)
     {
-        <FdyTableFooter Page="FooterPage" PageSizes="PageSizes" PageChanged="OnFooterPage" />
+        @* The six strings go through as given, null included: every default lives in the footer, so
+           a parameter left unset here is the footer's English and not a second copy of it. *@
+        <FdyTableFooter Page="FooterPage" PageSizes="PageSizes" PageChanged="OnFooterPage"
+                        InfoText="@InfoText" PageSizeLabel="@PageSizeLabel"
+                        PaginationLabel="@PaginationLabel" PrevLabel="@PrevLabel"
+                        NextLabel="@NextLabel" PageLabel="@PageLabel" />
     }
 </div>

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/blazor/FdyTableFooter.razor

@@ -9,12 +9,12 @@
 @if (Visible)
 {
     <div class="fdy-table-footer">
-        <span class="fdy-table-footer__info">Showing @RangeFrom–@RangeTo of @Page.Total</span>
+        <span class="fdy-table-footer__info">@InfoLine</span>
 
         @if (Sizes.Count > 0)
         {
             <div class="fdy-table-footer__size">
-                <span id="@SizeLabelId">Rows</span>
+                <span id="@SizeLabelId">@(PageSizeLabel ?? "Rows")</span>
                 @* The kit's own listbox, not a native <select>: an OS menu is unthemeable, and on
                    macOS it drops a dark panel into a light page. FdyCombo's own header says so. *@
                 <FdyCombo TValue="string" Value="@Page.Size.ToString()" Options="SizeOptions"
@@ -24,10 +24,10 @@
 
         @if (HasPager)
         {
-            <nav class="fdy-pagination" aria-label="Pagination">
+            <nav class="fdy-pagination" aria-label="@(PaginationLabel ?? "Pagination")">
                 <ul class="fdy-pagination__list">
                     <li>
-                        <button type="button" class="fdy-pagination__link" aria-label="Previous page"
+                        <button type="button" class="fdy-pagination__link" aria-label="@(PrevLabel ?? "Previous page")"
                                 disabled="@(CurrentPage1 == 1)" @onclick="() => GoTo(CurrentPage1 - 1)">‹</button>
                     </li>
                     @foreach (int? p in Pages)
@@ -44,13 +44,13 @@
                             else
                             {
                                 int page = p.Value;
-                                <button type="button" class="fdy-pagination__link" aria-label="@($"Go to page {page}")"
+                                <button type="button" class="fdy-pagination__link" aria-label="@PageAriaLabel(page)"
                                         @onclick="() => GoTo(page)">@(page)</button>
                             }
                         </li>
                     }
                     <li>
-                        <button type="button" class="fdy-pagination__link" aria-label="Next page"
+                        <button type="button" class="fdy-pagination__link" aria-label="@(NextLabel ?? "Next page")"
                                 disabled="@(CurrentPage1 == TotalPages)" @onclick="() => GoTo(CurrentPage1 + 1)">›</button>
                     </li>
                 </ul>

package/adapters/blazor/FdyTableFooter.razor.cs

@@ -21,6 +21,35 @@ public partial class FdyTableFooter
     /// </summary>
     [Parameter] public IReadOnlyList<int>? PageSizes { get; set; }
 
+    // The strings, six of them, one per thing this band says. The raw path has had a hatch since
+    // 1.39.0 (data-fdy-text-<key> read through textOf()) and this path had none, so an app that
+    // does not speak English could only rewrite the whole band by hand. A Blazor app mixes both
+    // paths by construction, since FreedayBlazor.initAll runs the enhancers, so these names follow
+    // the enhancer's TEXT keys where a key exists. Defaults stay English on every path, which
+    // COMPONENTS.md promises and the suite enforces.
+
+    /// <summary>
+    /// The range line. <c>{from}</c>, <c>{to}</c> and <c>{total}</c> are substituted, every
+    /// occurrence, as the enhancer's <c>textOf()</c> does. Default <c>Showing {from}–{to} of
+    /// {total}</c>, the enhancer's <c>info</c> key.
+    /// </summary>
+    [Parameter] public string? InfoText { get; set; }
+
+    /// <summary>The visible word beside the rows-per-page control, which also names it. Default <c>Rows</c>.</summary>
+    [Parameter] public string? PageSizeLabel { get; set; }
+
+    /// <summary>Accessible name of the pager landmark. Default <c>Pagination</c>.</summary>
+    [Parameter] public string? PaginationLabel { get; set; }
+
+    /// <summary>Accessible name of the previous-page arrow. Default <c>Previous page</c>.</summary>
+    [Parameter] public string? PrevLabel { get; set; }
+
+    /// <summary>Accessible name of the next-page arrow. Default <c>Next page</c>.</summary>
+    [Parameter] public string? NextLabel { get; set; }
+
+    /// <summary>Accessible name of a numbered page button. <c>{n}</c> substituted. Default <c>Go to page {n}</c>.</summary>
+    [Parameter] public string? PageLabel { get; set; }
+
     private IReadOnlyList<int> Sizes => PageSizes ?? Array.Empty<int>();
 
     // Just the number: the control sits beside a label reading "Rows", so "20 per page" states the
@@ -40,6 +69,13 @@ public partial class FdyTableFooter
 
     private bool HasPager => Page.Size > 0 && TotalPages > 1;
 
+    private string InfoLine => (InfoText ?? "Showing {from}–{to} of {total}")
+        .Replace("{from}", RangeFrom.ToString())
+        .Replace("{to}", RangeTo.ToString())
+        .Replace("{total}", Page.Total.ToString());
+
+    private string PageAriaLabel(int page1) => (PageLabel ?? "Go to page {n}").Replace("{n}", page1.ToString());
+
     // One page and no size control means there is nothing here to say, the table has always
     // withheld the whole band in that case, and this is where that decision now lives.
     private bool Visible => HasPager || Sizes.Count > 0;

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;