stimeo-ui 0.15.0 → 0.16.0

package/dist/controllers/calendar_controller.d.ts

@@ -7,6 +7,8 @@ import { Controller } from '@hotwired/stimulus';
  *   <div data-controller="stimeo--calendar"
  *        data-stimeo--calendar-month-value="2026-05"
  *        data-stimeo--calendar-selected-value="2026-05-31">
+ *     <input type="hidden" name="on" data-stimeo--calendar-target="field" />
+ *     <input type="hidden" name="month" data-stimeo--calendar-target="monthField" />
  *     <button data-action="click->stimeo--calendar#prev">Previous</button>
  *     <span data-stimeo--calendar-target="label">May 2026</span>
  *     <button data-action="click->stimeo--calendar#next">Next</button>
@@ -27,15 +29,63 @@ import { Controller } from '@hotwired/stimulus';
  *   the `locale` Value, else the nearest `lang` up the ancestor chain, else the
  *   runtime default; a malformed language tag falls back to English so the grid
  *   still paints.
- * - Roving tabindex focus tracking (exactly one focusable day at any time).
+ * - Without a `month`, the grid opens on the month of the selected day, else on
+ *   the current month, when an instance first connects, and stays on the month
+ *   it shows until a month step or the page writes `month` — a later connection
+ *   of the same instance, after an in-page move or with the identifier added
+ *   back, keeps it too. Opening on a month writes nothing to `month`.
+ * - Roving tabindex focus tracking (exactly one focusable day at any time). The
+ *   tab stop opens on the selected day, else on today when the shown month
+ *   holds it, else on the 1st of the shown month; a selected day the grid does
+ *   not show leaves it on the 1st.
  * - Full grid keyboard controls (arrows, PageUp/Down, Home/End, Shift+PageUp/Down).
  * - Automatic month wrapping and date clamping for missing dates (e.g. leap years, 31st to 30th).
+ * - `min`, `max` and `weekStart` changed at runtime repaint the month on screen
+ *   once connected, and DOM focus in the grid stays on the day it was on while
+ *   that day is still shown.
+ * - A `month` that moves the painted month — written by application code, a
+ *   morph, or the grid's own month steps — takes DOM focus in the grid to the
+ *   tab stop of the new month. A key that crosses into another month makes the
+ *   day it moved to that tab stop, so focus lands there.
+ * - An `aria-disabled` the consumer wrote on a day stays with that date while
+ *   the grid shows it, in whichever cell a repaint moves the date to.
+ *
+ * `selected` is a request: the grid publishes it as the selection only while
+ * `min` / `max` allow that day. A day outside them is neither `aria-selected`
+ * nor mirrored into `field`, and it comes back once the bounds allow it again;
+ * the Value itself is never rewritten.
  *
  * `monthchange` dispatches `{ month: string }`; `select` dispatches `{ date: string }`.
+ * `reconcile` dispatches `{ date: string }` — the selection now published, empty
+ * when there is none — once per paint in which a change the page made after
+ * connect moved the published selection: `selected` written by application
+ * code or a morph, or `min` / `max` withholding the requested day or giving it
+ * back. A selection the user picks is reported as `select` alone. Connecting,
+ * or connecting again, reports neither `monthchange` nor `reconcile`, whichever
+ * month the grid opens on.
+ *
+ * Two optional fields carry the grid's state into a form, so a server can serve
+ * the days it is showing: `field` mirrors the published selection (`YYYY-MM-DD`,
+ * empty when nothing is selected) and `monthField` the month being painted
+ * (`YYYY-MM`). A move the user made — the previous/next controls, a month
+ * crossing by keyboard, picking a day — emits a native bubbling `change` from
+ * the field that moved, the way a form control does, so `stimeo--auto-submit`
+ * and form-level validation hear it. A repaint driven by the Values, by a
+ * replacement field, or by the initial paint refreshes both mirrors silently,
+ * and so does a move of the selection a change the page made, which `reconcile`
+ * reports even in a paint the user's own move asked for.
+ *
+ * A day `min` / `max` exclude cannot be picked, even before a paint has marked
+ * its cell. A pick is painted — `aria-selected` and both fields — before
+ * anything reports it: each field that moved, then `monthchange` when the paint
+ * moved the month, then `select`. A listener that replaces the selection before
+ * these reports are all out — by picking another day, or with a paint in which
+ * `min` / `max` withhold this one — has the newer selection report itself, and
+ * what is still pending for the replaced pick is not sent.
  *
  * @remarks
- * Behavior only. The controller updates classes, attributes (aria-selected, data-outside, etc.),
- * and text contents dynamically on 42 pre-allocated `day` targets.
+ * Behavior only. The controller updates attributes (`aria-selected`, `data-outside`,
+ * `tabindex`, …) and text content on the 42 pre-allocated `day` targets.
  */
 declare class CalendarController extends Controller<HTMLElement> {
     #private;
@@ -67,12 +117,16 @@ declare class CalendarController extends Controller<HTMLElement> {
         };
     };
     static actions: readonly ["next", "onKeydown", "prev", "selectByClick"];
-    static events: readonly ["monthchange", "select"];
+    static events: readonly ["monthchange", "reconcile", "select"];
     readonly labelTarget: HTMLElement;
     readonly gridTarget: HTMLElement;
     readonly dayTargets: HTMLElement[];
+    readonly fieldTarget: HTMLInputElement;
+    readonly monthFieldTarget: HTMLInputElement;
     readonly hasLabelTarget: boolean;
     readonly hasGridTarget: boolean;
+    readonly hasFieldTarget: boolean;
+    readonly hasMonthFieldTarget: boolean;
     monthValue: string;
     selectedValue: string;
     minValue: string;
@@ -82,11 +136,14 @@ declare class CalendarController extends Controller<HTMLElement> {
     /** The date currently receiving focus in the grid (local time). */
     focusedDate: Date;
     connect(): void;
-    /** Cancels any pending deferred focus so it never fires on a detached element. */
+    /**
+     * Drops a pending repaint and a pending focus move, and stops reporting, so
+     * nothing reaches for a grid that is not connected.
+     */
     disconnect(): void;
     /**
-     * Stimulus lifecycle callback triggered automatically when the monthValue changes.
-     * Forces a re-render of the date grid and updates labels.
+     * Paints the month `month` names, whether application code, a morph or the
+     * grid's own navigation wrote it; focus in the grid follows to the tab stop.
      */
     monthValueChanged(): void;
     /**
@@ -94,15 +151,28 @@ declare class CalendarController extends Controller<HTMLElement> {
      *
      * Stimulus runs this for the initial Value too, before `connect()`. The paint
      * it triggers is idempotent — the month comes from `month` (or, while that is
-     * still empty, from `focusedDate`), and `monthchange` only reports a move away
-     * from a month already announced, so the first paint never reports one.
+     * still empty, from `focusedDate`) — and a grid that has not connected
+     * reports nothing, so that paint never reports a month.
      */
     localeValueChanged(): void;
     /**
-     * Stimulus lifecycle callback triggered automatically when the selectedValue changes.
-     * Re-renders grid cells to update `aria-selected` indicators.
+     * Repaints `aria-selected` and the field when the requested day changes, and
+     * moves the tab stop to the day the grid now publishes. A request `min` /
+     * `max` withhold is not published, so the tab stop stays where it was.
      */
     selectedValueChanged(): void;
+    /** Repaints when `min` changes after connect, so the disabled days and the selection follow. */
+    minValueChanged(): void;
+    /** Repaints when `max` changes after connect, so the disabled days and the selection follow. */
+    maxValueChanged(): void;
+    /**
+     * Lays the grid out again when `weekStart` changes after connect, so every
+     * date moves to the column of its weekday.
+     *
+     * Only the day cells are painted: column headers are author markup, so the
+     * author updates them together with the Value.
+     */
+    weekStartValueChanged(): void;
     /** Navigates to the previous month. */
     prev(event?: Event): void;
     /** Navigates to the next month. */
@@ -111,18 +181,10 @@ declare class CalendarController extends Controller<HTMLElement> {
     selectByClick(event: MouseEvent): void;
     /** Handles grid cell keyboard navigation and triggers selection. */
     onKeydown(event: KeyboardEvent): void;
-    /**
-     * Renders the grid days and updates the month/year label, then reports the
-     * painted month once it differs from the one already announced.
-     *
-     * The report belongs to the paint, not to the `month` Value: the Value is only
-     * one of the things that decide the month on screen. While a malformed `month`
-     * falls back, changing `selected` and selecting a neighbouring month's cell
-     * move the painted month too, and both repaint from here. Reading the report
-     * off the paint keeps the event naming the month the grid shows, in the
-     * `YYYY-MM` the detail contract promises, whichever route repainted.
-     */
-    render(): void;
+    /** Fills a selected-day field inserted or replaced at runtime with the published selection. */
+    fieldTargetConnected(field: HTMLInputElement): void;
+    /** Fills a painted-month field inserted or replaced at runtime. */
+    monthFieldTargetConnected(field: HTMLInputElement): void;
     selectDayElement(dayElement: HTMLElement): void;
 }