plass-ui 0.0.1 → 1.0.0

package/dist/internal/date.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The arithmetic and the naming the four pickers share.
+ *
+ * No date library under it, deliberately. Plass has one runtime dependency —
+ * Base UI — and a component library that quietly adds `date-fns`, or worse
+ * picks a side in the dayjs/luxon/Temporal argument on its consumer's behalf,
+ * has made a decision that was not its to make. Everything here is either
+ * `Date` arithmetic, which is a dozen lines, or `Intl`, which the platform
+ * already ships and which knows more about month names in more languages than
+ * any bundled table ever will.
+ *
+ * **That is also the whole of the localisation story.** There is no table of
+ * translated month names to import and no per-language module to register: the
+ * only strings a picker says that `Intl` has no opinion about are the labels on
+ * its own buttons, and those are one `labels` prop with English defaults. A
+ * project that ships in twelve languages pays nothing for eleven of them.
+ *
+ * Two rules hold everywhere below:
+ *
+ * - **Local time, always.** A calendar day is a thing a person is looking at on
+ *   a wall, not an instant on a line. `makeDate(2026, 6, 27)` is midnight local
+ *   and every comparison here is made on the local Y/M/D triple, so a picker in
+ *   Seoul and a picker in São Paulo both light up the cell that says 27.
+ * - **Nothing is mutated.** `Date` is mutable and every method on it that
+ *   sounds like a question is actually a command. Each function here copies
+ *   first, so a `value` handed in by a caller is never the object that comes
+ *   back out.
+ */
+import type { PlassWeekday } from '../types.js';
+/** Which unit the calendar is currently letting you pick. */
+export type CalendarView = 'day' | 'month' | 'year';
+/** How many years one page of the year grid holds. Four columns of three. */
+export declare const YEAR_PAGE_SIZE = 12;
+/**
+ * A local midnight on the given Y/M/D, with out-of-range parts normalised —
+ * month `12` rolls into January, day `0` into the last day of the month before.
+ *
+ * Built through `setFullYear` rather than `new Date(year, month, day)` because
+ * the multi-argument constructor maps years 0–99 onto 1900–1999. Nobody is
+ * going to pick a date in the year 47, but a component that silently rewrites
+ * the year it was handed is a component that will eventually be blamed for
+ * something else.
+ */
+export declare function makeDate(year: number, month: number, day: number): Date;
+/** Is this a `Date` that stands for a real instant? `new Date('nope')` is not. */
+export declare function isValidDate(value: unknown): value is Date;
+/** The same day with the clock wound back to midnight. */
+export declare function startOfDay(date: Date): Date;
+/** The first day of the month this date is in, at midnight. */
+export declare function startOfMonth(date: Date): Date;
+/** How many days a month has, leap years included. */
+export declare function daysInMonth(year: number, month: number): number;
+/** Today, at midnight. The one place the pickers read the clock for a *date*. */
+export declare function today(): Date;
+export declare function addDays(date: Date, amount: number): Date;
+/**
+ * Months, with the day of the month clamped rather than allowed to overflow.
+ *
+ * 31 January plus one month is 28 February, not 3 March. The naive
+ * `setMonth(getMonth() + 1)` gives the second answer, which is why stepping a
+ * calendar forward from a 31st with it skips February entirely.
+ */
+export declare function addMonths(date: Date, amount: number): Date;
+export declare function addYears(date: Date, amount: number): Date;
+/** Negative, zero or positive, the way a sort comparator wants it. */
+export declare function compareDay(a: Date, b: Date): number;
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+export declare function isSameMonth(a: Date | null | undefined, b: Date | null | undefined): boolean;
+/** Holds a date inside `[min, max]`, at whatever precision the bounds carry. */
+export declare function clampDate(date: Date, min?: Date | null, max?: Date | null): Date;
+/**
+ * Is this calendar *day* outside the allowed span?
+ *
+ * Day-granular on purpose. A `maxDate` of 27 July at 09:00 still leaves the
+ * 27th pickable — the bound is about which days exist, and the time of day is
+ * the time picker's problem. `PlDateTimePicker` re-checks at full precision
+ * once an hour has been chosen.
+ */
+export declare function isDayOutside(date: Date, min?: Date | null, max?: Date | null): boolean;
+/** Seconds since local midnight — what `minTime`/`maxTime` are compared on. */
+export declare function secondsOfDay(date: Date): number;
+/** Which column of a clock a candidate time is being offered for. */
+export type TimeUnit = 'hour' | 'minute' | 'second' | 'meridiem';
+/**
+ * The span of the day one row of one column covers, in seconds since midnight.
+ *
+ * This is the detail that separates a working time picker from a frustrating
+ * one. A bound has to be checked against the *span* a row stands for, not
+ * against one instant inside it: with a `minTime` of 09:30, the hour `9` covers
+ * 09:00:00–09:59:59, which overlaps what is allowed, so it stays available and
+ * the minute column is where `00` through `25` grey out. Comparing the whole
+ * candidate instead hides the 9 and makes half past nine unreachable.
+ */
+export declare function timeUnitSpan(unit: TimeUnit, at: Date): [number, number];
+/** The same instant with one or more clock fields replaced. */
+export declare function withTime(date: Date, parts: {
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}): Date;
+/** `date`'s calendar day wearing `time`'s clock. */
+export declare function mergeDateAndTime(date: Date, time: Date): Date;
+/**
+ * Six weeks of seven days, always — including the leading and trailing days
+ * that belong to the neighbouring months.
+ *
+ * Six rows whatever the month, and that is the whole point. A February that
+ * starts on a Sunday needs four rows and a 31-day month starting on a Saturday
+ * needs six; a grid that renders only the rows it needs is a grid that changes
+ * height when you step a month forward, moving every cell out from under the
+ * pointer that just pressed one. The same reason `PlPagination` pins its slot
+ * count.
+ */
+export declare function calendarWeeks(month: Date, weekStartsOn: PlassWeekday): Date[][];
+/** The first year on the page a given year falls on. 2026 becomes 2016 at 12 a page. */
+export declare function yearPageStart(year: number): number;
+/** Formats a date, tolerating the `null` a cleared picker holds. */
+export declare function formatDate(date: Date | null | undefined, locale: string | undefined, options: Intl.DateTimeFormatOptions): string;
+/**
+ * Every distinct string those instants format to. Deduplicated, because a
+ * date-only format collapses twenty-four of them into a handful.
+ */
+export declare function displaySamples(locale: string | undefined, options: Intl.DateTimeFormatOptions): string[];
+/**
+ * The samples plus the placeholder, when the placeholder is a string.
+ *
+ * An empty picker shows the placeholder, which can easily be longer than any
+ * date — "Pick a departure date" against "3 Aug 2026" — and a trigger that
+ * shrinks the moment the first date is chosen is the same jump from the other
+ * direction. A `ReactNode` placeholder is left out: there is nothing to measure
+ * without rendering it twice.
+ */
+export declare function withPlaceholder(samples: string[], placeholder: unknown): string[];
+/**
+ * The three machine-readable spellings, for the hidden input that makes a
+ * picker submit with a form.
+ *
+ * Local, not UTC, and that is the whole point: `toISOString()` on a `Date`
+ * standing for 27 July in Seoul gives `2026-07-26T15:00:00Z`, and a form field
+ * that quietly reports the day before the one on screen is the single most
+ * expensive bug a date picker can ship. The shapes are the ones the native
+ * `<input type="date">`, `type="time"` and `type="datetime-local"` submit, so a
+ * server that already parses those needs no new code.
+ */
+export declare function toISODate(date: Date): string;
+export declare function toISOTime(date: Date, withSeconds?: boolean): string;
+export declare function toISODateTime(date: Date, withSeconds?: boolean): string;
+/**
+ * The seven column headers, rotated so the first one is `weekStartsOn`.
+ *
+ * `short` rather than `narrow`: narrow gives `S`, `M`, `T`, `W`, `T`, `F`, `S`
+ * in English, where two pairs are indistinguishable. The full name goes on the
+ * header's `aria-label` so a screen reader hears "Monday" rather than "Mon".
+ */
+export declare function weekdayLabels(locale: string | undefined, weekStartsOn: PlassWeekday, weekday?: 'narrow' | 'short' | 'long'): string[];
+/** The twelve month names, January first, in the locale's own words. */
+export declare function monthLabels(locale: string | undefined, month?: 'short' | 'long'): string[];
+/**
+ * Does this locale write the month before the year?
+ *
+ * The calendar's header is two separate buttons — one that opens the month grid
+ * and one that opens the year grid — so it cannot just print what `Intl` gives
+ * it. Asking `formatToParts` which part came first is how the two buttons end
+ * up in the order the reader expects: `July 2026` in English, `2026년 7월` in
+ * Korean. Getting this wrong is subtle and reads as broken to exactly the
+ * people it is wrong for.
+ */
+export declare function isMonthBeforeYear(locale: string | undefined): boolean;
+/** Does this locale put a clock on a 12-hour dial? */
+export declare function isHour12(locale: string | undefined): boolean;
+/** What this locale calls AM and PM. */
+export declare function meridiemLabels(locale: string | undefined): [string, string];
+export declare function localeWeekStart(locale: string | undefined): PlassWeekday;

package/dist/internal/date.js

@@ -0,0 +1,353 @@
+/**
+ * The arithmetic and the naming the four pickers share.
+ *
+ * No date library under it, deliberately. Plass has one runtime dependency —
+ * Base UI — and a component library that quietly adds `date-fns`, or worse
+ * picks a side in the dayjs/luxon/Temporal argument on its consumer's behalf,
+ * has made a decision that was not its to make. Everything here is either
+ * `Date` arithmetic, which is a dozen lines, or `Intl`, which the platform
+ * already ships and which knows more about month names in more languages than
+ * any bundled table ever will.
+ *
+ * **That is also the whole of the localisation story.** There is no table of
+ * translated month names to import and no per-language module to register: the
+ * only strings a picker says that `Intl` has no opinion about are the labels on
+ * its own buttons, and those are one `labels` prop with English defaults. A
+ * project that ships in twelve languages pays nothing for eleven of them.
+ *
+ * Two rules hold everywhere below:
+ *
+ * - **Local time, always.** A calendar day is a thing a person is looking at on
+ *   a wall, not an instant on a line. `makeDate(2026, 6, 27)` is midnight local
+ *   and every comparison here is made on the local Y/M/D triple, so a picker in
+ *   Seoul and a picker in São Paulo both light up the cell that says 27.
+ * - **Nothing is mutated.** `Date` is mutable and every method on it that
+ *   sounds like a question is actually a command. Each function here copies
+ *   first, so a `value` handed in by a caller is never the object that comes
+ *   back out.
+ */
+import { dateFormatter } from './format.js';
+/** How many years one page of the year grid holds. Four columns of three. */
+export const YEAR_PAGE_SIZE = 12;
+/* ---------------------------------------------------------------------------
+ * Construction
+ * ------------------------------------------------------------------------- */
+/**
+ * A local midnight on the given Y/M/D, with out-of-range parts normalised —
+ * month `12` rolls into January, day `0` into the last day of the month before.
+ *
+ * Built through `setFullYear` rather than `new Date(year, month, day)` because
+ * the multi-argument constructor maps years 0–99 onto 1900–1999. Nobody is
+ * going to pick a date in the year 47, but a component that silently rewrites
+ * the year it was handed is a component that will eventually be blamed for
+ * something else.
+ */
+export function makeDate(year, month, day) {
+    const date = new Date(0);
+    date.setFullYear(year, month, day);
+    date.setHours(0, 0, 0, 0);
+    return date;
+}
+/** Is this a `Date` that stands for a real instant? `new Date('nope')` is not. */
+export function isValidDate(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime());
+}
+/** The same day with the clock wound back to midnight. */
+export function startOfDay(date) {
+    const next = new Date(date.getTime());
+    next.setHours(0, 0, 0, 0);
+    return next;
+}
+/** The first day of the month this date is in, at midnight. */
+export function startOfMonth(date) {
+    return makeDate(date.getFullYear(), date.getMonth(), 1);
+}
+/** How many days a month has, leap years included. */
+export function daysInMonth(year, month) {
+    return makeDate(year, month + 1, 0).getDate();
+}
+/** Today, at midnight. The one place the pickers read the clock for a *date*. */
+export function today() {
+    return startOfDay(new Date());
+}
+/* ---------------------------------------------------------------------------
+ * Arithmetic
+ * ------------------------------------------------------------------------- */
+export function addDays(date, amount) {
+    const next = new Date(date.getTime());
+    next.setDate(next.getDate() + amount);
+    return next;
+}
+/**
+ * Months, with the day of the month clamped rather than allowed to overflow.
+ *
+ * 31 January plus one month is 28 February, not 3 March. The naive
+ * `setMonth(getMonth() + 1)` gives the second answer, which is why stepping a
+ * calendar forward from a 31st with it skips February entirely.
+ */
+export function addMonths(date, amount) {
+    const next = new Date(date.getTime());
+    // Normalised through a first-of-month so the day never carries the overflow.
+    const target = makeDate(date.getFullYear(), date.getMonth() + amount, 1);
+    next.setFullYear(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), daysInMonth(target.getFullYear(), target.getMonth())));
+    return next;
+}
+export function addYears(date, amount) {
+    return addMonths(date, amount * 12);
+}
+/* ---------------------------------------------------------------------------
+ * Comparison
+ *
+ * All of it on the local Y/M/D triple, never on `getTime()`. Two `Date`s that
+ * are the same calendar day differ by milliseconds far more often than not — a
+ * value carrying a time of day, a `min` built at noon — and every one of those
+ * comparisons has to come out `true`.
+ * ------------------------------------------------------------------------- */
+/** Negative, zero or positive, the way a sort comparator wants it. */
+export function compareDay(a, b) {
+    return startOfDay(a).getTime() - startOfDay(b).getTime();
+}
+export function isSameDay(a, b) {
+    return isValidDate(a) && isValidDate(b) && compareDay(a, b) === 0;
+}
+export function isSameMonth(a, b) {
+    return (isValidDate(a) &&
+        isValidDate(b) &&
+        a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth());
+}
+/** Holds a date inside `[min, max]`, at whatever precision the bounds carry. */
+export function clampDate(date, min, max) {
+    if (isValidDate(min) && date.getTime() < min.getTime()) {
+        return new Date(min.getTime());
+    }
+    if (isValidDate(max) && date.getTime() > max.getTime()) {
+        return new Date(max.getTime());
+    }
+    return date;
+}
+/**
+ * Is this calendar *day* outside the allowed span?
+ *
+ * Day-granular on purpose. A `maxDate` of 27 July at 09:00 still leaves the
+ * 27th pickable — the bound is about which days exist, and the time of day is
+ * the time picker's problem. `PlDateTimePicker` re-checks at full precision
+ * once an hour has been chosen.
+ */
+export function isDayOutside(date, min, max) {
+    if (isValidDate(min) && compareDay(date, min) < 0) {
+        return true;
+    }
+    return isValidDate(max) && compareDay(date, max) > 0;
+}
+/* ---------------------------------------------------------------------------
+ * Time of day
+ * ------------------------------------------------------------------------- */
+/** Seconds since local midnight — what `minTime`/`maxTime` are compared on. */
+export function secondsOfDay(date) {
+    return date.getHours() * 3600 + date.getMinutes() * 60 + date.getSeconds();
+}
+/**
+ * The span of the day one row of one column covers, in seconds since midnight.
+ *
+ * This is the detail that separates a working time picker from a frustrating
+ * one. A bound has to be checked against the *span* a row stands for, not
+ * against one instant inside it: with a `minTime` of 09:30, the hour `9` covers
+ * 09:00:00–09:59:59, which overlaps what is allowed, so it stays available and
+ * the minute column is where `00` through `25` grey out. Comparing the whole
+ * candidate instead hides the 9 and makes half past nine unreachable.
+ */
+export function timeUnitSpan(unit, at) {
+    const seconds = secondsOfDay(at);
+    if (unit === 'hour') {
+        const start = Math.floor(seconds / 3600) * 3600;
+        return [start, start + 3599];
+    }
+    if (unit === 'minute') {
+        const start = Math.floor(seconds / 60) * 60;
+        return [start, start + 59];
+    }
+    if (unit === 'second') {
+        return [seconds, seconds];
+    }
+    const start = at.getHours() < 12 ? 0 : 12 * 3600;
+    return [start, start + 12 * 3600 - 1];
+}
+/** The same instant with one or more clock fields replaced. */
+export function withTime(date, parts) {
+    const next = new Date(date.getTime());
+    next.setHours(parts.hours ?? next.getHours(), parts.minutes ?? next.getMinutes(), parts.seconds ?? next.getSeconds(), 0);
+    return next;
+}
+/** `date`'s calendar day wearing `time`'s clock. */
+export function mergeDateAndTime(date, time) {
+    return withTime(startOfDay(date), {
+        hours: time.getHours(),
+        minutes: time.getMinutes(),
+        seconds: time.getSeconds()
+    });
+}
+/* ---------------------------------------------------------------------------
+ * The grid
+ * ------------------------------------------------------------------------- */
+/**
+ * Six weeks of seven days, always — including the leading and trailing days
+ * that belong to the neighbouring months.
+ *
+ * Six rows whatever the month, and that is the whole point. A February that
+ * starts on a Sunday needs four rows and a 31-day month starting on a Saturday
+ * needs six; a grid that renders only the rows it needs is a grid that changes
+ * height when you step a month forward, moving every cell out from under the
+ * pointer that just pressed one. The same reason `PlPagination` pins its slot
+ * count.
+ */
+export function calendarWeeks(month, weekStartsOn) {
+    const first = startOfMonth(month);
+    const lead = (first.getDay() - weekStartsOn + 7) % 7;
+    const origin = addDays(first, -lead);
+    return Array.from({ length: 6 }, (_, week) => Array.from({ length: 7 }, (_, day) => addDays(origin, week * 7 + day)));
+}
+/** The first year on the page a given year falls on. 2026 becomes 2016 at 12 a page. */
+export function yearPageStart(year) {
+    return year - (((year % YEAR_PAGE_SIZE) + YEAR_PAGE_SIZE) % YEAR_PAGE_SIZE);
+}
+/* ---------------------------------------------------------------------------
+ * Naming
+ *
+ * Every string a picker draws that is not a number comes from `Intl`, through
+ * the memoised formatters in `internal/format.ts` — constructing one is the
+ * expensive half of using one, and a calendar builds seven weekday names and
+ * twelve month names on every render of the month view.
+ * ------------------------------------------------------------------------- */
+/** Formats a date, tolerating the `null` a cleared picker holds. */
+export function formatDate(date, locale, options) {
+    return isValidDate(date) ? dateFormatter(locale, options).format(date) : '';
+}
+/**
+ * Twenty-four instants that between them exercise everything a picker's display
+ * can vary by: all twelve month names, all seven weekday names, a two-digit
+ * day, every hour of the clock and a two-digit minute and second.
+ *
+ * They exist to be measured, not read. A picker's trigger is sized by its
+ * content, so `Jul 1, 2026` and `Sep 28, 2026` are different widths and the
+ * field would jump every time a date was chosen — with the whole row of
+ * controls beside it shuffling along. Rendering all of these invisibly pins the
+ * trigger to the widest thing it could ever say.
+ *
+ * Both cycles are prime to twelve in the right way — `i % 12` walks the months
+ * and `i % 7` walks the days 21…27 — so every name appears without the two
+ * being multiplied out into eighty-four samples.
+ */
+const DISPLAY_SAMPLES = /* @__PURE__ */ Array.from({ length: 24 }, (_, index) => new Date(2027, index % 12, 21 + (index % 7), index, 58, 58));
+/**
+ * Every distinct string those instants format to. Deduplicated, because a
+ * date-only format collapses twenty-four of them into a handful.
+ */
+export function displaySamples(locale, options) {
+    const formatter = dateFormatter(locale, options);
+    return [...new Set(DISPLAY_SAMPLES.map((date) => formatter.format(date)))];
+}
+/**
+ * The samples plus the placeholder, when the placeholder is a string.
+ *
+ * An empty picker shows the placeholder, which can easily be longer than any
+ * date — "Pick a departure date" against "3 Aug 2026" — and a trigger that
+ * shrinks the moment the first date is chosen is the same jump from the other
+ * direction. A `ReactNode` placeholder is left out: there is nothing to measure
+ * without rendering it twice.
+ */
+export function withPlaceholder(samples, placeholder) {
+    return typeof placeholder === 'string' && placeholder !== ''
+        ? [...samples, placeholder]
+        : samples;
+}
+/**
+ * The three machine-readable spellings, for the hidden input that makes a
+ * picker submit with a form.
+ *
+ * Local, not UTC, and that is the whole point: `toISOString()` on a `Date`
+ * standing for 27 July in Seoul gives `2026-07-26T15:00:00Z`, and a form field
+ * that quietly reports the day before the one on screen is the single most
+ * expensive bug a date picker can ship. The shapes are the ones the native
+ * `<input type="date">`, `type="time"` and `type="datetime-local"` submit, so a
+ * server that already parses those needs no new code.
+ */
+export function toISODate(date) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+export function toISOTime(date, withSeconds = false) {
+    const pad = (value) => String(value).padStart(2, '0');
+    const base = `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+    return withSeconds ? `${base}:${pad(date.getSeconds())}` : base;
+}
+export function toISODateTime(date, withSeconds = false) {
+    return `${toISODate(date)}T${toISOTime(date, withSeconds)}`;
+}
+/** A Sunday, used as the origin for every weekday name below. 1 Aug 2021. */
+const WEEKDAY_ORIGIN = /* @__PURE__ */ makeDate(2021, 7, 1);
+/**
+ * The seven column headers, rotated so the first one is `weekStartsOn`.
+ *
+ * `short` rather than `narrow`: narrow gives `S`, `M`, `T`, `W`, `T`, `F`, `S`
+ * in English, where two pairs are indistinguishable. The full name goes on the
+ * header's `aria-label` so a screen reader hears "Monday" rather than "Mon".
+ */
+export function weekdayLabels(locale, weekStartsOn, weekday = 'short') {
+    const formatter = dateFormatter(locale, { weekday });
+    return Array.from({ length: 7 }, (_, index) => formatter.format(addDays(WEEKDAY_ORIGIN, (weekStartsOn + index) % 7)));
+}
+/** The twelve month names, January first, in the locale's own words. */
+export function monthLabels(locale, month = 'short') {
+    const formatter = dateFormatter(locale, { month });
+    return Array.from({ length: 12 }, (_, index) => formatter.format(makeDate(2021, index, 1)));
+}
+/**
+ * Does this locale write the month before the year?
+ *
+ * The calendar's header is two separate buttons — one that opens the month grid
+ * and one that opens the year grid — so it cannot just print what `Intl` gives
+ * it. Asking `formatToParts` which part came first is how the two buttons end
+ * up in the order the reader expects: `July 2026` in English, `2026년 7월` in
+ * Korean. Getting this wrong is subtle and reads as broken to exactly the
+ * people it is wrong for.
+ */
+export function isMonthBeforeYear(locale) {
+    const parts = dateFormatter(locale, { year: 'numeric', month: 'long' }).formatToParts(WEEKDAY_ORIGIN);
+    return (parts.findIndex((part) => part.type === 'month') <
+        parts.findIndex((part) => part.type === 'year'));
+}
+/** Does this locale put a clock on a 12-hour dial? */
+export function isHour12(locale) {
+    const resolved = dateFormatter(locale, { hour: 'numeric' }).resolvedOptions();
+    if (resolved.hourCycle) {
+        return resolved.hourCycle === 'h11' || resolved.hourCycle === 'h12';
+    }
+    return resolved.hour12 === true;
+}
+/** What this locale calls AM and PM. */
+export function meridiemLabels(locale) {
+    const formatter = dateFormatter(locale, { hour: 'numeric', hour12: true });
+    const read = (hours) => {
+        const part = formatter
+            .formatToParts(withTime(WEEKDAY_ORIGIN, { hours }))
+            .find((entry) => entry.type === 'dayPeriod');
+        return part?.value ?? (hours < 12 ? 'AM' : 'PM');
+    };
+    return [read(9), read(21)];
+}
+export function localeWeekStart(locale) {
+    try {
+        const resolved = locale ?? new Intl.DateTimeFormat().resolvedOptions().locale;
+        const info = new Intl.Locale(resolved);
+        const week = typeof info.getWeekInfo === 'function' ? info.getWeekInfo() : info.weekInfo;
+        // CLDR counts Monday as 1 through Sunday as 7; `getDay` counts Sunday as 0.
+        if (typeof week?.firstDay === 'number') {
+            return (week.firstDay % 7);
+        }
+    }
+    catch {
+        // An unparseable locale tag. Not worth taking the calendar down over.
+    }
+    return 0;
+}

package/dist/internal/format.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `Intl` formatters, memoised.
+ *
+ * Here rather than inline for one reason: constructing a formatter is the
+ * expensive half of using one. On V8, `new Intl.DateTimeFormat(...).format(d)`
+ * costs about 16us and `format(d)` on a formatter that already exists costs
+ * about 0.3us — fifty-five times the work for the same string.
+ *
+ * That ratio only matters where the call is in a loop or in a render, and in the
+ * pickers it is both: a calendar builds seven weekday names and twelve month
+ * names for a 42-cell month view, and it builds them again on every step, every
+ * hover and every keystroke.
+ *
+ * The cache is unbounded on purpose. The keys are not user data — they come from
+ * a component's own option objects, of which any one page has a handful — so
+ * there is nothing here that grows with the size of anything.
+ *
+ * The options object is deliberately **not** part of the key by identity. A
+ * caller writing `format={{ dateStyle: 'medium' }}` inline hands over a new
+ * object on every render, which is the ordinary way that prop gets written, and
+ * keying on identity would miss every time and cache nothing but garbage.
+ */
+/** A memoised `Intl.DateTimeFormat`. */
+export declare function dateFormatter(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;

package/dist/internal/format.js

@@ -0,0 +1,41 @@
+/**
+ * The `Intl` formatters, memoised.
+ *
+ * Here rather than inline for one reason: constructing a formatter is the
+ * expensive half of using one. On V8, `new Intl.DateTimeFormat(...).format(d)`
+ * costs about 16us and `format(d)` on a formatter that already exists costs
+ * about 0.3us — fifty-five times the work for the same string.
+ *
+ * That ratio only matters where the call is in a loop or in a render, and in the
+ * pickers it is both: a calendar builds seven weekday names and twelve month
+ * names for a 42-cell month view, and it builds them again on every step, every
+ * hover and every keystroke.
+ *
+ * The cache is unbounded on purpose. The keys are not user data — they come from
+ * a component's own option objects, of which any one page has a handful — so
+ * there is nothing here that grows with the size of anything.
+ *
+ * The options object is deliberately **not** part of the key by identity. A
+ * caller writing `format={{ dateStyle: 'medium' }}` inline hands over a new
+ * object on every render, which is the ordinary way that prop gets written, and
+ * keying on identity would miss every time and cache nothing but garbage.
+ */
+/**
+ * `undefined` locale means the runtime's own, and is a key of its own. The two
+ * halves are parted by a NUL, which no locale tag and no option name can
+ * contain, so no two different pairs of inputs can spell the same key.
+ */
+function cacheKey(locale, options) {
+    return `${locale ?? ''}\u0000${options ? JSON.stringify(options) : ''}`;
+}
+const dateFormatters = new Map();
+/** A memoised `Intl.DateTimeFormat`. */
+export function dateFormatter(locale, options) {
+    const key = cacheKey(locale, options);
+    let formatter = dateFormatters.get(key);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat(locale, options);
+        dateFormatters.set(key, formatter);
+    }
+    return formatter;
+}

package/dist/internal/grid.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The arithmetic and the vocabulary `PlGrid` and `PlGridItem` share.
+ *
+ * Like `internal/styles.ts` this is the library talking to itself, and it lives
+ * here rather than in either component's folder for one reason: the two are one
+ * system in two elements, and neither should have to import the other.
+ *
+ * What is *not* here is the layout itself. A column width is
+ * `(100% + gap) * span / columns - gap`, it has to change at four breakpoints,
+ * and it is the width of an element whose column count is declared on its
+ * parent — none of which Tailwind can spell, because Tailwind only ever sees
+ * class names written out literally and `columns` is a number a caller picks.
+ * So the widths are real CSS in `styles.css`, driven by the `--p-*` slots this
+ * file generates. That is the same split the rest of the library makes:
+ * per-instance values go in inline custom properties, never in class names.
+ */
+import type * as React from 'react';
+import type { PlassAlignItems, PlassAlignSelf, PlassBreakpoint, PlassJustify, PlassResponsive } from '../types.js';
+/** Smallest first, which is also the order the media queries have to be in. */
+export declare const breakpoints: readonly PlassBreakpoint[];
+/**
+ * Turns a responsive value into the `--p-{name}-{breakpoint}` slots the CSS
+ * reads, emitting only the breakpoints the caller actually named.
+ *
+ * The gaps are filled in by CSS rather than here: each breakpoint's rule falls
+ * back through the ones below it, so `{ md: 6 }` needs one slot and not five.
+ * That keeps the inline style on a grid item down to what was asked for.
+ */
+export declare function responsiveSlots<T>(name: string, value: PlassResponsive<T> | undefined, toCss: (value: T) => string): React.CSSProperties;
+/**
+ * Fills in the `xs` entry of a partial map with the prop's own default.
+ *
+ * Without this, `spacing={{ md: 4 }}` would be a grid with no gutter at all
+ * below 48rem — the CSS fallback rather than the documented default — and a
+ * caller who narrowed one breakpoint would silently lose every other one. A map
+ * says "from here up, use this instead"; it does not say "and nothing below".
+ */
+export declare function withBaseline<T>(value: PlassResponsive<T> | undefined, baseline: T): PlassResponsive<T>;
+/**
+ * A count of columns, as a plain number for `calc()` to divide by.
+ *
+ * Rounded and floored at 1 because the value ends up as a divisor: a grid of
+ * 2.5 columns is not a thing anybody meant, and a grid of 0 is a division by
+ * zero that would take the width declaration down with it.
+ */
+export declare function columnCount(value: number): string;
+/** A span or an offset. Same rounding; an offset of 0 is meaningful. */
+export declare function columnUnits(value: number, min: number): string;
+export declare const spanValue: (value: number) => string;
+export declare const offsetValue: (value: number) => string;
+/**
+ * A gutter, as a length.
+ *
+ * Fractions are the point — `spacing={1.5}` is `0.375rem`, the same step
+ * `gap-1.5` is — so the multiplication is rounded to five places rather than
+ * left to print `0.30000000000000004rem` into the DOM.
+ */
+export declare function spacingValue(units: number): string;
+export declare const justifyClasses: Record<PlassJustify, string>;
+export declare const alignItemsClasses: Record<PlassAlignItems, string>;
+/**
+ * Where the *rows* sit when the grid is shorter than the box holding it. Only
+ * ever visible on a grid with a height of its own, which is why it takes the
+ * full distribution vocabulary and `alignItems` does not.
+ */
+export declare const alignContentClasses: Record<PlassJustify, string>;
+export declare const alignSelfClasses: Record<PlassAlignSelf, string>;