@box-kite/react 2.2.5 → 2.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@box-kite/react",
-  "version": "2.2.5",
+  "version": "2.2.6",
   "type": "module",
   "sideEffects": [
     "pages/**"
@@ -44,6 +44,11 @@
       "import": "./interop.mjs",
       "require": "./interop.cjs"
     },
+    "./date": {
+      "types": "./date.d.ts",
+      "import": "./date.mjs",
+      "require": "./date.cjs"
+    },
     "./spec": {
       "types": "./spec.d.ts",
       "import": "./spec.mjs",
@@ -117,7 +122,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "39.07 KB"
+      "limit": "39.45 KB"
     },
     {
       "name": "Box in a Server Component (react-server entry)",
@@ -129,7 +134,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "37.10 KB"
+      "limit": "37.47 KB"
     },
     {
       "name": "Behavior primitives (a11y entry)",
@@ -165,7 +170,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "58.71 KB"
+      "limit": "61.11 KB"
     },
     {
       "name": "Spec renderer (spec entry)",
@@ -191,11 +196,23 @@
       "gzip": true,
       "limit": "4 KB"
     },
+    {
+      "name": "Dates, times and zones (date entry, no React)",
+      "path": "dist/date.mjs",
+      "ignore": [
+        "react",
+        "react-dom",
+        "./diagnostics-*",
+        "./themeReveal-*"
+      ],
+      "gzip": true,
+      "limit": "7.59 KB"
+    },
     {
       "name": "Core engine (@box-kite/core, no React)",
       "path": "dist-core/core.mjs",
       "gzip": true,
-      "limit": "38.31 KB",
+      "limit": "38.68 KB",
       "ignore": [
         "./diagnostics-*",
         "./themeReveal-*"
@@ -211,7 +228,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "41.14 KB"
+      "limit": "41.54 KB"
     },
     {
       "name": "Popover",
@@ -223,7 +240,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "42.68 KB"
+      "limit": "43.07 KB"
     },
     {
       "name": "Menu",
@@ -235,7 +252,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "44.94 KB"
+      "limit": "45.31 KB"
     },
     {
       "name": "Accordion",
@@ -247,7 +264,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "40.41 KB"
+      "limit": "40.78 KB"
     },
     {
       "name": "Agent",
@@ -259,7 +276,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "41.19 KB"
+      "limit": "41.56 KB"
     },
     {
       "name": "Markdown",
@@ -271,7 +288,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "39.66 KB"
+      "limit": "40.04 KB"
     },
     {
       "name": "List",
@@ -283,7 +300,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "40.98 KB"
+      "limit": "41.36 KB"
     },
     {
       "name": "SwipeItem",
@@ -295,7 +312,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "44.06 KB"
+      "limit": "44.44 KB"
     },
     {
       "name": "SortableList",
@@ -307,7 +324,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "44.33 KB"
+      "limit": "44.72 KB"
     },
     {
       "name": "VirtualList",
@@ -319,7 +336,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "43.16 KB"
+      "limit": "43.53 KB"
     },
     {
       "name": "Skeleton",
@@ -331,7 +348,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "38.98 KB"
+      "limit": "39.39 KB"
     },
     {
       "name": "Tabs",
@@ -343,7 +360,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "41.62 KB"
+      "limit": "41.99 KB"
     },
     {
       "name": "Slider",
@@ -355,7 +372,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "40.77 KB"
+      "limit": "41.16 KB"
     },
     {
       "name": "Progress",
@@ -367,7 +384,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "38.96 KB"
+      "limit": "39.34 KB"
     },
     {
       "name": "Toaster",
@@ -379,7 +396,67 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "42.40 KB"
+      "limit": "42.77 KB"
+    },
+    {
+      "name": "DateField",
+      "path": "dist/components/dateField.mjs",
+      "ignore": [
+        "react",
+        "react-dom",
+        "./diagnostics-*",
+        "./themeReveal-*"
+      ],
+      "gzip": true,
+      "limit": "47.97 KB"
+    },
+    {
+      "name": "Calendar",
+      "path": "dist/components/calendar.mjs",
+      "ignore": [
+        "react",
+        "react-dom",
+        "./diagnostics-*",
+        "./themeReveal-*"
+      ],
+      "gzip": true,
+      "limit": "47.39 KB"
+    },
+    {
+      "name": "DatePicker",
+      "path": "dist/components/datePicker.mjs",
+      "ignore": [
+        "react",
+        "react-dom",
+        "./diagnostics-*",
+        "./themeReveal-*"
+      ],
+      "gzip": true,
+      "limit": "60.07 KB"
+    },
+    {
+      "name": "DateTime",
+      "path": "dist/components/dateTime.mjs",
+      "ignore": [
+        "react",
+        "react-dom",
+        "./diagnostics-*",
+        "./themeReveal-*"
+      ],
+      "gzip": true,
+      "limit": "42.9 KB"
+    },
+    {
+      "name": "TimeZoneSelect",
+      "path": "dist/components/timeZoneSelect.mjs",
+      "ignore": [
+        "react",
+        "react-dom",
+        "./diagnostics-*",
+        "./themeReveal-*"
+      ],
+      "gzip": true,
+      "limit": "50.51 KB"
     },
     {
       "name": "Combobox",
@@ -391,7 +468,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "48.21 KB"
+      "limit": "48.58 KB"
     },
     {
       "name": "Dashboard",
@@ -403,7 +480,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "44.62 KB"
+      "limit": "45.01 KB"
     },
     {
       "name": "DataGrid",
@@ -413,10 +490,11 @@
         "react-dom",
         "./diagnostics-*",
         "./themeReveal-*",
-        "../dataGridList.mjs"
+        "../dataGridList.mjs",
+        "../dataGridDateParts.mjs"
       ],
       "gzip": true,
-      "limit": "93.23 KB"
+      "limit": "94.65 KB"
     },
     {
       "name": "DataGrid export, the chunk fetched on the first press",
@@ -444,6 +522,20 @@
       "gzip": true,
       "limit": "7.83 KB"
     },
+    {
+      "name": "DataGrid dates, the chunk a grid with a date column fetches on top of the grid",
+      "path": "dist/dataGridDateParts.mjs",
+      "ignore": [
+        "react",
+        "react-dom",
+        "./diagnostics-*",
+        "./themeReveal-*",
+        "./box.mjs",
+        "./components/*"
+      ],
+      "gzip": true,
+      "limit": "7.49 KB"
+    },
     {
       "name": "Full library (Box + ssg + every component)",
       "path": "dev/size-full.mjs",
@@ -454,7 +546,7 @@
         "./themeReveal-*"
       ],
       "gzip": true,
-      "limit": "140.38 KB"
+      "limit": "162.25 KB"
     }
   ],
   "repository": {
@@ -494,7 +586,7 @@
     "react-dom": "^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@box-kite/core": "2.2.5",
+    "@box-kite/core": "2.2.6",
     "csstype": "^3.2.3",
     "use-sync-external-store": "^1.6.0"
   },

package/react/boxComponent.d.ts

@@ -4,7 +4,7 @@ type Render = (props: any, ref: any) => React.ReactNode;
  * A component that is a Box: memoized, which skips a leaf whose props are all primitives, and one fiber on
  * React 19. React 18 needs a `forwardRef` under the `memo`, which makes it two.
  */
-export default function boxComponent(render: Render, displayName: string): React.MemoExoticComponent<((props: {
+export default function boxComponent(render: Render, displayName: string): React.MemoExoticComponent<(({ ref, ...props }: {
     ref?: Ref<unknown>;
 }) => React.ReactNode) | React.ForwardRefExoticComponent<Omit<any, "ref"> & React.RefAttributes<unknown>>>;
 export {};

package/react/date/dateChange.d.ts

@@ -0,0 +1,18 @@
+import { DateReadings } from '../../utils/date/dateTime';
+import { ChangeDetails } from '../a11y/useControllableState';
+/**
+ * Why a date value changed: digits or arrows in a field, a paste, a day picked in a calendar or a time in a
+ * list, a preset, the clear button, or a form reset.
+ */
+export type DateChangeReason = 'keyboard' | 'paste' | 'select' | 'preset' | 'clear' | 'reset';
+/**
+ * What a date control hands its `onValueChange` beside the string: the reason, plus every reading of the
+ * value an app is likely to want — `utc`, the reader's `local` wall clock, a `Date`, the epoch.
+ *
+ * ```tsx
+ * <DateField type="datetime" onValueChange={(value, { utc, local }) => save(utc)} />
+ * ```
+ */
+export type DateChangeDetails<TReason extends string = DateChangeReason> = ChangeDetails<TReason> & DateReadings;
+/** A date control's change handler: the canonical string (or `null`) and the readings. */
+export type DateChangeHandler<TValue = string | null, TReason extends string = DateChangeReason> = (value: TValue, details: DateChangeDetails<TReason>) => void;

package/react/date/dateEnvironment.d.ts

@@ -0,0 +1,34 @@
+import { ZoneInput } from '../../utils/date/zones';
+/** What a subtree knows about its reader: the language and the zone. */
+export interface DateEnvironmentValue {
+    /** A BCP 47 tag. */
+    locale?: string;
+    /** The reader's zone — what `'local'` means inside. */
+    timeZone?: string;
+}
+export interface DateProviderProps extends DateEnvironmentValue {
+    children?: React.ReactNode;
+}
+/**
+ * Says who the reader is for every date component inside: their language and their zone. On a server that
+ * read the zone off a cookie (`readZoneCookie`), this is what makes the first paint already right — the
+ * server and the browser render the same text, and nothing changes after hydration.
+ */
+export declare function DateProvider({ locale, timeZone, children }: DateProviderProps): import("react").JSX.Element;
+export interface DateEnvironment {
+    locale: string;
+    /** The zone resolved to a name: `UTC`, an IANA zone or a fixed offset. */
+    zone: string;
+    /** The reader's own zone, which is what `'local'` resolved to. */
+    readerZone: string;
+}
+/**
+ * The locale and zone a date component renders in. A prop wins, then a `DateProvider`, then
+ * `configureDates()`, then the browser. **A server and a hydrating browser both use the fallback** — `UTC` and
+ * `en-US` unless something above configured them — because neither can know the other's runtime, and two
+ * renders that disagree are a hydration error. The render after hydration switches to the reader's own.
+ */
+export declare function useDateEnvironment(props?: {
+    locale?: string;
+    zone?: ZoneInput;
+}): DateEnvironment;

package/react-shared.cjs

@@ -1 +1 @@
-const e=require("./rolldown-runtime.cjs");let t=require("react");t=e.t(t,1);let n=require("@box-kite/core");function r({classNames:e,styleElements:t},r){return{className:(0,n.classNames)(e,r).join(` `),styles:t}}var i=parseInt(t.default.version,10)>=19;function a(e,n){let r=i?t=>e(t,t.ref??null):(0,t.forwardRef)(e),a=(0,t.memo)(r);return r.displayName=n,a.displayName=n,a}var o={selected:`aria-selected`},s;(function(e){function t(e,t,n){e!==void 0&&e!=null&&(n[o[t]??t]=Array.isArray(e)?e[0]:e)}e.assignBooleanProp=t})(s||={});var c=s;function l(e,t){let r=e,{props:i,className:a,disabled:o,required:s,checked:l,selected:u}=r,d={...i,className:(0,n.classNames)(t,a).join(` `)};return c.assignBooleanProp(o,`disabled`,d),c.assignBooleanProp(s,`required`,d),c.assignBooleanProp(l,`checked`,d),c.assignBooleanProp(u,`selected`,d),`style`in r&&(d.style=r.style),`id`in r&&(d.id=r.id),d}var u=parseInt(t.default.version,10)>=19,d=!1,f=new WeakMap,p=new WeakMap;function m(e){let n=f.get(e);if(!n){let{href:r,css:i,precedence:a}=e;n=t.default.createElement(`style`,{key:r,href:r,precedence:a,dangerouslySetInnerHTML:{__html:i}}),f.set(e,n)}return n}function h(e){if(!e?.length)return;!u&&!d&&(d=!0,console.warn(`[box-kite] Box.configure({ sink: 'element' }) needs React 19 to hoist and dedupe its <style> elements; React ${t.default.version} will render them inline. Use the default sink instead.`));let n=p.get(e);return n||(n=e.map(m),p.set(e,n)),n}function g(e,t,r){let{classNames:i,signature:a,styleElements:o}=(0,n.getDefaultEngine)().resolveClassNames(e,t,r);return{classNames:i,signature:a,styleElements:h(o)}}var _=`__boxAttributesInProps`;function v(e){return e[_]=!0,e}function y(e){return typeof e==`function`||typeof e==`object`&&e?e[_]===!0:!1}var b=[`role`,`aria-label`,`aria-labelledby`,`aria-hidden`];function x(e,t){if(e!==void 0)return{role:`img`,"aria-label":e};if(!(t&&b.some(e=>e in t)))return{"aria-hidden":!0}}var S;(function(e){function t(e){return e.charAt(0).toUpperCase()+e.slice(1)}e.capitalize=t})(S||={});var C=S,w;(function(e){function t(e,t,n){let r={...e},i=r.props||{};return t.forEach(e=>{e in r&&(i[e]=r[e],delete r[e])}),n&&Object.entries(n).forEach(([e,t])=>{i[e]=t}),r.props=i,r}e.buildProps=t;function n(e){return!!e&&typeof e==`object`}e.isObject=n;function r(e,t){return e in t}e.isKeyOf=r})(w||={});var T=w,E=[`sky-500`,`emerald-500`,`amber-500`,`violet-500`,`rose-500`,`cyan-500`],D=[`sky-400`,`emerald-400`,`amber-400`,`violet-400`,`rose-400`,`cyan-400`];function O(e){return e.reduce((e,t,n)=>(e[`chart-${n+1}`]=t,e),{})}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return C}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return v}}),Object.defineProperty(exports,"d",{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,"f",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return T}}),Object.defineProperty(exports,"l",{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return E}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return x}}),Object.defineProperty(exports,"p",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return O}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return y}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return D}}),Object.defineProperty(exports,"u",{enumerable:!0,get:function(){return h}});
+const e=require("./rolldown-runtime.cjs");let t=require("react");t=e.t(t,1);let n=require("@box-kite/core");function r({classNames:e,styleElements:t},r){return{className:(0,n.classNames)(e,r).join(` `),styles:t}}var i=parseInt(t.default.version,10)>=19;function a(e,n){let r=i?({ref:t,...n})=>e(n,t??null):(0,t.forwardRef)(e),a=(0,t.memo)(r);return r.displayName=n,a.displayName=n,a}var o={selected:`aria-selected`},s;(function(e){function t(e,t,n){e!==void 0&&e!=null&&(n[o[t]??t]=Array.isArray(e)?e[0]:e)}e.assignBooleanProp=t})(s||={});var c=s;function l(e,t){let r=e,{props:i,className:a,disabled:o,required:s,checked:l,selected:u}=r,d={...i,className:(0,n.classNames)(t,a).join(` `)};return c.assignBooleanProp(o,`disabled`,d),c.assignBooleanProp(s,`required`,d),c.assignBooleanProp(l,`checked`,d),c.assignBooleanProp(u,`selected`,d),`style`in r&&(d.style=r.style),`id`in r&&(d.id=r.id),d}var u=parseInt(t.default.version,10)>=19,d=!1,f=new WeakMap,p=new WeakMap;function m(e){let n=f.get(e);if(!n){let{href:r,css:i,precedence:a}=e;n=t.default.createElement(`style`,{key:r,href:r,precedence:a,dangerouslySetInnerHTML:{__html:i}}),f.set(e,n)}return n}function h(e){if(!e?.length)return;!u&&!d&&(d=!0,console.warn(`[box-kite] Box.configure({ sink: 'element' }) needs React 19 to hoist and dedupe its <style> elements; React ${t.default.version} will render them inline. Use the default sink instead.`));let n=p.get(e);return n||(n=e.map(m),p.set(e,n)),n}function g(e,t,r){let{classNames:i,signature:a,styleElements:o}=(0,n.getDefaultEngine)().resolveClassNames(e,t,r);return{classNames:i,signature:a,styleElements:h(o)}}var _=`__boxAttributesInProps`;function v(e){return e[_]=!0,e}function y(e){return typeof e==`function`||typeof e==`object`&&e?e[_]===!0:!1}var b=[`role`,`aria-label`,`aria-labelledby`,`aria-hidden`];function x(e,t){if(e!==void 0)return{role:`img`,"aria-label":e};if(!(t&&b.some(e=>e in t)))return{"aria-hidden":!0}}var S;(function(e){function t(e){return e.charAt(0).toUpperCase()+e.slice(1)}e.capitalize=t})(S||={});var C=S,w;(function(e){function t(e,t,n){let r={...e},i=r.props||{};return t.forEach(e=>{e in r&&(i[e]=r[e],delete r[e])}),n&&Object.entries(n).forEach(([e,t])=>{i[e]=t}),r.props=i,r}e.buildProps=t;function n(e){return!!e&&typeof e==`object`}e.isObject=n;function r(e,t){return e in t}e.isKeyOf=r})(w||={});var T=w,E=[`sky-500`,`emerald-500`,`amber-500`,`violet-500`,`rose-500`,`cyan-500`],D=[`sky-400`,`emerald-400`,`amber-400`,`violet-400`,`rose-400`,`cyan-400`];function O(e){return e.reduce((e,t,n)=>(e[`chart-${n+1}`]=t,e),{})}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return C}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return v}}),Object.defineProperty(exports,"d",{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,"f",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return T}}),Object.defineProperty(exports,"l",{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return E}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return x}}),Object.defineProperty(exports,"p",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return O}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return y}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return D}}),Object.defineProperty(exports,"u",{enumerable:!0,get:function(){return h}});

package/react-shared.mjs

@@ -11,7 +11,7 @@ function a({ classNames: e, styleElements: t }, n) {
 //#region src/react/boxComponent.ts
 var o = parseInt(e.version, 10) >= 19;
 function s(e, r) {
-	let i = o ? (t) => e(t, t.ref ?? null) : t(e), a = n(i);
+	let i = o ? ({ ref: t, ...n }) => e(n, t ?? null) : t(e), a = n(i);
 	return i.displayName = r, a.displayName = r, a;
 }
 //#endregion

package/ssg.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./rolldown-runtime.cjs"),t=require("./client.cjs");let n=require("react-dom/server");n=e.t(n,1);function r(){return t.i.getStyles()}function i(){return t.i.getStyleTag()}function a(){t.i.clear()}function o(e,t=!0){let o=n.default.renderToStaticMarkup(e),s=r(),c=i();if(t){let e=o.indexOf(`<head>`);if(e>-1){let t=e+6;o=o.substring(0,t)+c+o.substring(t)}}return a(),{html:o,styles:s,styleTag:c}}exports.getStyleTag=i,exports.getStyles=r,exports.renderToStaticMarkup=o,exports.resetStyles=a;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./rolldown-runtime.cjs"),t=require("./client.cjs");let n=require("react-dom/server");n=e.t(n,1);function r(){return t.r.getStyles()}function i(){return t.r.getStyleTag()}function a(){t.r.clear()}function o(e,t=!0){let o=n.default.renderToStaticMarkup(e),s=r(),c=i();if(t){let e=o.indexOf(`<head>`);if(e>-1){let t=e+6;o=o.substring(0,t)+c+o.substring(t)}}return a(),{html:o,styles:s,styleTag:c}}exports.getStyleTag=i,exports.getStyles=r,exports.renderToStaticMarkup=o,exports.resetStyles=a;

package/ssg.mjs

@@ -1,4 +1,4 @@
-import { i as e } from "./client.mjs";
+import { r as e } from "./client.mjs";
 import t from "react-dom/server";
 //#region src/ssg.ts
 function n() {

package/utils/date/calendar.d.ts

@@ -0,0 +1,44 @@
+/** A day on the proleptic Gregorian calendar, with no time and no zone. `month` is 1–12. */
+export interface DateFields {
+    year: number;
+    month: number;
+    day: number;
+}
+/** A wall-clock time, with no date and no zone. */
+export interface TimeFields {
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+}
+export type DateTimeFields = DateFields & TimeFields;
+export declare const MS_PER_MINUTE = 60000;
+export declare const MS_PER_HOUR = 3600000;
+export declare const MS_PER_DAY = 86400000;
+export declare const MIDNIGHT: TimeFields;
+/** Floor division, so a negative epoch lands on the day before rather than the day after. */
+export declare function floorDiv(value: number, by: number): number;
+/** A remainder that is never negative. */
+export declare function mod(value: number, by: number): number;
+export declare function isLeapYear(year: number): boolean;
+export declare function daysInMonth(year: number, month: number): number;
+/** Days since 1970-01-01, for any year — Howard Hinnant's `days_from_civil`, pure integer arithmetic and no `Date`. */
+export declare function epochDay({ year, month, day }: DateFields): number;
+/** The inverse of `epochDay`. */
+export declare function fromEpochDay(days: number): DateFields;
+/** 0 is Sunday, which is what `Intl.Locale#getWeekInfo` counts from too once its 7 is taken as 0. */
+export declare function dayOfWeek(date: DateFields): number;
+/** A wall clock read as though it were UTC — the number every zone conversion starts from. */
+export declare function fieldsToMs(fields: DateTimeFields): number;
+export declare function msToFields(ms: number): DateTimeFields;
+export declare function addDays(date: DateFields, days: number): DateFields;
+/** Months forward or back, the day clamped to the month it lands in — 31 January plus a month is 28 or 29 February. */
+export declare function addMonths(date: DateFields, months: number): DateFields;
+export declare function compareDates(a: DateFields, b: DateFields): number;
+export declare function isValidDate({ year, month, day }: DateFields): boolean;
+export declare function isValidTime({ hour, minute, second, millisecond }: TimeFields): boolean;
+/** The ISO 8601 week: weeks start on Monday and week 1 holds the year's first Thursday. */
+export declare function isoWeek(date: DateFields): {
+    year: number;
+    week: number;
+};

package/utils/date/calendarModel.d.ts

@@ -0,0 +1,46 @@
+import { DateFields } from './calendar';
+/** One day cell of a month grid. */
+export interface CalendarDay {
+    /** `2026-10-19`. */
+    date: string;
+    day: number;
+    /** Whether it belongs to the month on show rather than the weeks either side of it. */
+    outside: boolean;
+}
+export interface CalendarWeek {
+    /** The ISO week number of the week's Thursday-anchored year. */
+    week: number;
+    days: CalendarDay[];
+}
+/** A day as fields, or `null` for anything that is not a date. */
+export declare function dayOf(value: string | null | undefined): DateFields | null;
+export declare function dayText(date: DateFields): string;
+/**
+ * Six weeks starting on the locale's first day, always six so the grid does not change height from month to
+ * month — the month on show plus the days around it that complete its weeks.
+ */
+export declare function monthGrid(year: number, month: number, firstDay: number): CalendarWeek[];
+export interface NavigationOptions {
+    rtl: boolean;
+    firstDay: number;
+}
+/**
+ * Where a key moves the focused day, APG's map: the arrows a day or a week (the sideways pair following the
+ * reading order), Home and End the week's ends, Page Up and Down a month, with Shift a year. `null` for any
+ * other key.
+ */
+export declare function moveFocus(focused: DateFields, key: string, shift: boolean, options: NavigationOptions): DateFields | null;
+export interface Bounds {
+    min?: DateFields | null;
+    max?: DateFields | null;
+}
+/** Whether a day is before `min` or after `max`. */
+export declare function isOutOfBounds(date: DateFields, bounds: Bounds): boolean;
+/** A day pulled inside the bounds. */
+export declare function clampDay(date: DateFields, bounds: Bounds): DateFields;
+/** A range in order, whichever end was picked first. */
+export declare function orderedRange(a: DateFields, b: DateFields): [DateFields, DateFields];
+/** Where a day sits relative to a range: its first day, its last, strictly inside, or not in it. */
+export declare function rangePosition(date: DateFields, start: DateFields | null, end: DateFields | null): 'start' | 'end' | 'middle' | null;
+/** Whether any day of a range is one nobody can choose — a range is refused across a blocked day. */
+export declare function rangeCrosses(start: DateFields, end: DateFields, isBlocked: (date: string) => boolean): boolean;

package/utils/date/dateTime.d.ts

@@ -0,0 +1,144 @@
+import { DateKind } from './iso';
+import { DateInput, ZoneOptions } from './value';
+import { ZoneInput } from './zones';
+/** An amount of time to move a value by. Years to days move the calendar; hours and below move the clock. */
+export interface Duration {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+export type DateUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+export interface UnitOptions extends ZoneOptions {
+    /** Whose week `'week'` means — Monday-first in Moldova, Sunday-first in the US. Default the configured locale. */
+    locale?: string;
+}
+/** Every reading of one value at once — what a date control hands its `onValueChange` beside the string. */
+export interface DateTimeDetails {
+    /** The value itself, written canonically. */
+    value: string;
+    kind: DateKind;
+    /** The zone the wall-clock fields below are read in. */
+    zone: string;
+    /** The moment in UTC (`…Z`). A date is its midnight in `zone`; a time has none. */
+    utc: string | null;
+    /** The moment on `zone`'s wall clock, with its offset. */
+    zoned: string | null;
+    /** The same moment as the reader's own wall clock, with no zone: what a person in the browser sees. */
+    local: string | null;
+    /** `zone`'s offset at that moment, `+03:00`. */
+    offset: string | null;
+    /** A `Date` for the moment, for an API that wants one. */
+    date: Date | null;
+    /** Epoch milliseconds. */
+    epoch: number | null;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+}
+/** What kind a string is, or `null` when it is not a date value at all. */
+export declare function kindOf(input: DateInput): DateKind | null;
+/** Whether the input is a value — of `kind`, when one is named. */
+export declare function isValid(input: DateInput, kind?: DateKind): boolean;
+/** The input rewritten canonically, its kind kept: `2026-10-19 14:30` → `2026-10-19T14:30:00`. */
+export declare function normalize(input: DateInput): string | null;
+/** The moment in UTC: `2026-10-19T11:30:00Z`. A date-time is read on `zone`'s wall clock, a date as its midnight there. */
+export declare function toUtc(input: DateInput, options?: Omit<ZoneOptions, 'zone'> & {
+    from?: ZoneInput;
+}): string | null;
+/** The moment on another zone's wall clock, with that zone's offset: `2026-10-19T07:30:00-04:00`. */
+export declare function toZone(input: DateInput, zone: ZoneInput, options?: Omit<ZoneOptions, 'zone'> & {
+    from?: ZoneInput;
+}): string | null;
+/** The moment on the reader's wall clock, with its offset. On a server, "the reader" is `configureDates({ timeZone })` or the server. */
+export declare function toLocal(input: DateInput, options?: Omit<ZoneOptions, 'zone'> & {
+    from?: ZoneInput;
+}): string | null;
+/** The day an input falls on in `zone`: `2026-10-19`. */
+export declare function toPlainDate(input: DateInput, options?: ZoneOptions): string | null;
+/** The wall-clock time an input shows in `zone`: `14:30:00`. */
+export declare function toPlainTime(input: DateInput, options?: ZoneOptions): string | null;
+/** The wall clock an input shows in `zone`, with no zone attached: `2026-10-19T14:30:00`. */
+export declare function toPlainDateTime(input: DateInput, options?: ZoneOptions): string | null;
+/** The instant an input names, on `zone`'s wall clock. A date-time is read there; a date is its midnight. */
+export declare function toInstant(input: DateInput, options?: ZoneOptions): string | null;
+/** Epoch milliseconds. */
+export declare function toEpoch(input: DateInput, options?: ZoneOptions): number | null;
+/** A `Date`, for an API that insists. A date is its midnight in `zone`, which is the one way a `Date` can hold a day. */
+export declare function toDate(input: DateInput, options?: ZoneOptions): Date | null;
+/** A `Date` or epoch milliseconds as a value of `kind` — by default the instant, in UTC. */
+export declare function fromDate(date: Date | number, options?: ZoneOptions & {
+    kind?: DateKind;
+}): string | null;
+/** A date and a time put together: a date-time, or with `zone` the instant it names there. */
+export declare function combine(date: DateInput, time: DateInput, options?: ZoneOptions): string | null;
+/** Today's date in `zone`. Default the reader's. */
+export declare function today(zone?: ZoneInput): string;
+/** This moment on `zone`'s wall clock, with its offset — `now('utc')` is `…Z`. */
+export declare function now(zone?: ZoneInput): string;
+/** The time on `zone`'s wall clock. */
+export declare function currentTime(zone?: ZoneInput): string;
+/**
+ * Moves a value by a duration, keeping its kind. The calendar half (years to days) moves the wall clock, so a
+ * day later is the same time tomorrow across a DST change; the clock half (hours down) moves the instant. A
+ * date ignores the clock half, and a time wraps round midnight.
+ */
+export declare function add(input: DateInput, duration: Duration, options?: ZoneOptions): string | null;
+export declare function subtract(input: DateInput, duration: Duration, options?: ZoneOptions): string | null;
+/** The first moment of the unit a value is in — the 1st of its month, its week's first day in the locale, its hour. */
+export declare function startOf(input: DateInput, unit: DateUnit, options?: UnitOptions): string | null;
+/** The last moment of the unit — for a date, the last day; for anything with a clock, one millisecond before the next unit. */
+export declare function endOf(input: DateInput, unit: DateUnit, options?: UnitOptions): string | null;
+/**
+ * Below zero when `a` is earlier, above when later, `0` when equal. Two values of one zone-free kind compare
+ * on their wall clocks; anything else compares as instants, a zone-free side read in `zone`.
+ */
+export declare function compare(a: DateInput, b: DateInput, options?: ZoneOptions): number;
+export declare function isBefore(a: DateInput, b: DateInput, options?: ZoneOptions): boolean;
+export declare function isAfter(a: DateInput, b: DateInput, options?: ZoneOptions): boolean;
+/** Whether two inputs are the same moment — `…14:30+03:00` and `…11:30Z` are. */
+export declare function isEqual(a: DateInput, b: DateInput, options?: ZoneOptions): boolean;
+/** Whether two inputs fall in the same unit — the same day, the same week in the locale — on `zone`'s wall clock. */
+export declare function isSame(a: DateInput, b: DateInput, unit: DateUnit, options?: UnitOptions): boolean;
+/** Whether `input` is from `start` to `end`, both included. A missing end is open. */
+export declare function isBetween(input: DateInput, start: DateInput, end: DateInput, options?: ZoneOptions): boolean;
+/** The input, moved inside `[min, max]`. */
+export declare function clamp(input: DateInput, min: DateInput, max: DateInput, options?: ZoneOptions): string | null;
+/**
+ * How many whole units `a` is after `b` (negative when before). Months and years count on the calendar — 31
+ * January to 28 February is not yet a month — and days count calendar days between two dates.
+ */
+export declare function difference(a: DateInput, b: DateInput, unit: DateUnit, options?: ZoneOptions): number | null;
+/** How many days the month a value falls in has. */
+export declare function daysInMonthOf(input: DateInput, options?: ZoneOptions): number | null;
+/**
+ * Every reading of a value at once: the canonical string, the UTC moment, the moment on `zone`'s wall clock
+ * and on the reader's, the offset, a `Date`, the epoch, and the wall-clock fields. `null` for a non-value.
+ */
+export declare function details(input: DateInput, options?: ZoneOptions): DateTimeDetails | null;
+/** Minutes east of UTC that `zone` is at a moment (default now): `180` for Chisinau in summer, `-240` for New York. */
+export declare function offsetOf(zone?: ZoneInput, at?: DateInput): number | null;
+/** What a date control reports beside its value: the readings an app most often wants, all `null` for no value. */
+export interface DateReadings {
+    /** The moment in UTC, `…Z`. A date is its midnight in the control's zone; a time has none. */
+    utc: string | null;
+    /** The moment on the reader's own wall clock, with no zone. */
+    local: string | null;
+    /** The moment on the control's zone's wall clock, with its offset. */
+    zoned: string | null;
+    date: Date | null;
+    epoch: number | null;
+    /** The zone the control reads and writes in. */
+    zone: string;
+    offset: string | null;
+}
+/** The readings for a value in a control's zone — what `onValueChange` hands over beside the string. */
+export declare function readingsOf(value: string | null | undefined, zone?: ZoneInput): DateReadings;