@petrarca/sonnet-core 0.5.0 → 0.6.0

package/dist/config/index.d.ts

@@ -28,8 +28,18 @@ import React__default from 'react';
  */
 interface SonnetComponentDefaults {
 }
-/** Cross-cutting global settings. Extend via declaration merging as needed. */
+/**
+ * Cross-cutting global settings. Extend via declaration merging as needed.
+ * Empty by default; packages add fields without editing this file.
+ */
 interface SonnetGlobalConfig {
+    /**
+     * BCP-47 locale (e.g. `"en-US"`, `"de-DE"`) used for display and input
+     * parsing of locale-sensitive components (dates, numbers). Values exchanged
+     * with consumers stay locale-independent (ISO). When unset, components fall
+     * back to the browser locale (`navigator.language`), then `"en"`.
+     */
+    locale?: string;
 }
 /** The full app-wide configuration object held by SonnetConfigProvider. */
 interface SonnetConfig {
@@ -75,4 +85,16 @@ declare const SonnetConfigContext: React.Context<SonnetConfig>;
  */
 declare function useComponentDefaults<Props extends Record<string, unknown>>(componentName: string, builtinDefaults: Partial<Props>, props: Props): Props;
 
-export { type SonnetComponentDefaults, type SonnetConfig, SonnetConfigContext, SonnetConfigProvider, type SonnetConfigProviderProps, type SonnetGlobalConfig, useComponentDefaults };
+/**
+ * useLocale -- resolve the active BCP-47 locale.
+ *
+ * Resolution order: explicit override > provider global (SonnetConfigProvider)
+ * > browser (`navigator.language`) > `"en"`. Locale-sensitive components use
+ * this for display and input parsing only; values exchanged with consumers
+ * remain locale-independent (ISO).
+ */
+/** The browser locale, or "en" when unavailable (e.g. SSR). */
+declare function getBrowserLocale(): string;
+declare function useLocale(override?: string): string;
+
+export { type SonnetComponentDefaults, type SonnetConfig, SonnetConfigContext, SonnetConfigProvider, type SonnetConfigProviderProps, type SonnetGlobalConfig, getBrowserLocale, useComponentDefaults, useLocale };

package/dist/config/index.js

@@ -55,9 +55,24 @@ function useComponentDefaults(componentName, builtinDefaults, props) {
     return resolved;
   }, [builtinDefaults, providerDefaults, props]);
 }
+
+// src/config/useLocale.ts
+import { useContext as useContext3 } from "react";
+function getBrowserLocale() {
+  if (typeof navigator !== "undefined" && navigator.language) {
+    return navigator.language;
+  }
+  return "en";
+}
+function useLocale(override) {
+  const config = useContext3(SonnetConfigContext);
+  return override ?? config.globals?.locale ?? getBrowserLocale();
+}
 export {
   SonnetConfigContext,
   SonnetConfigProvider,
-  useComponentDefaults
+  getBrowserLocale,
+  useComponentDefaults,
+  useLocale
 };
 //# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/config/SonnetConfigProvider.tsx","../../src/config/SonnetConfigContext.ts","../../src/config/useComponentDefaults.ts"],"sourcesContent":["/**\n * SonnetConfigProvider -- sets app-wide component defaults.\n *\n * Place once at the app root to define default props for components (and\n * cross-cutting globals). Individual instances still override via props.\n * Nested providers merge into their parent, so a subtree can refine or\n * override outer defaults.\n *\n * Resolution order for any prop (see useComponentDefaults):\n *   instance prop > provider default > built-in default.\n */\n\nimport React, { useContext, useMemo } from \"react\";\nimport { SonnetConfigContext } from \"./SonnetConfigContext\";\nimport type { SonnetConfig } from \"./types\";\n\nexport interface SonnetConfigProviderProps {\n  /** The configuration to apply. Merged onto any parent provider's config. */\n  value: SonnetConfig;\n  children: React.ReactNode;\n}\n\n// Merge child config onto parent. Globals shallow-merge; component defaults\n// merge per component name, with each component's defaultProps shallow-merged\n// (child wins). One level of nesting is sufficient for the defaultProps shape.\nfunction mergeConfig(parent: SonnetConfig, child: SonnetConfig): SonnetConfig {\n  const components: Record<string, { defaultProps?: Record<string, unknown> }> =\n    {\n      ...(parent.components as Record<\n        string,\n        { defaultProps?: Record<string, unknown> }\n      >),\n    };\n  const childComponents = child.components as\n    | Record<string, { defaultProps?: Record<string, unknown> }>\n    | undefined;\n  if (childComponents) {\n    for (const name of Object.keys(childComponents)) {\n      components[name] = {\n        ...components[name],\n        ...childComponents[name],\n        defaultProps: {\n          ...components[name]?.defaultProps,\n          ...childComponents[name]?.defaultProps,\n        },\n      };\n    }\n  }\n  return {\n    globals: { ...parent.globals, ...child.globals },\n    components: components as SonnetConfig[\"components\"],\n  };\n}\n\nexport function SonnetConfigProvider({\n  value,\n  children,\n}: SonnetConfigProviderProps): React.ReactElement {\n  const parent = useContext(SonnetConfigContext);\n  const merged = useMemo(() => mergeConfig(parent, value), [parent, value]);\n  return (\n    <SonnetConfigContext.Provider value={merged}>\n      {children}\n    </SonnetConfigContext.Provider>\n  );\n}\n","/**\n * React context holding the resolved app-wide SonnetConfig.\n *\n * Nested providers merge into their parent (see SonnetConfigProvider), so a\n * provider deeper in the tree can refine or override an outer one for its\n * subtree. The default is an empty config -- with no provider, components fall\n * back to their built-in defaults, preserving existing behavior.\n */\n\nimport { createContext } from \"react\";\nimport type { SonnetConfig } from \"./types\";\n\nexport const SonnetConfigContext = createContext<SonnetConfig>({});\n","/**\n * useComponentDefaults -- resolve a component's props against app-wide config.\n *\n * Resolution order, per prop: instance prop > provider default > built-in.\n * A component calls this at the top of its body:\n *\n *   const resolved = useComponentDefaults(\"EntityTable\", BUILTIN, props);\n *\n * where BUILTIN is a stable (module-level) object of the component's built-in\n * defaults. With no provider in the tree, the result is BUILTIN merged with\n * props -- identical to not using the config at all, so existing behavior is\n * preserved.\n */\n\nimport { useContext, useMemo } from \"react\";\nimport { SonnetConfigContext } from \"./SonnetConfigContext\";\n\nexport function useComponentDefaults<Props extends Record<string, unknown>>(\n  componentName: string,\n  builtinDefaults: Partial<Props>,\n  props: Props,\n): Props {\n  const config = useContext(SonnetConfigContext);\n  const components = config.components as\n    | Record<string, { defaultProps?: Partial<Props> } | undefined>\n    | undefined;\n  const providerDefaults = components?.[componentName]?.defaultProps;\n\n  return useMemo(() => {\n    // Spread order encodes precedence: builtin < provider < instance props.\n    // Only undefined instance props fall through to provider/builtin, so an\n    // explicit prop always wins.\n    const resolved: Record<string, unknown> = {\n      ...builtinDefaults,\n      ...providerDefaults,\n    };\n    for (const key of Object.keys(props)) {\n      if (props[key] !== undefined) resolved[key] = props[key];\n    }\n    return resolved as Props;\n  }, [builtinDefaults, providerDefaults, props]);\n}\n"],"mappings":";AAYA,SAAgB,YAAY,eAAe;;;ACH3C,SAAS,qBAAqB;AAGvB,IAAM,sBAAsB,cAA4B,CAAC,CAAC;;;ADiD7D;AApCJ,SAAS,YAAY,QAAsB,OAAmC;AAC5E,QAAM,aACJ;AAAA,IACE,GAAI,OAAO;AAAA,EAIb;AACF,QAAM,kBAAkB,MAAM;AAG9B,MAAI,iBAAiB;AACnB,eAAW,QAAQ,OAAO,KAAK,eAAe,GAAG;AAC/C,iBAAW,IAAI,IAAI;AAAA,QACjB,GAAG,WAAW,IAAI;AAAA,QAClB,GAAG,gBAAgB,IAAI;AAAA,QACvB,cAAc;AAAA,UACZ,GAAG,WAAW,IAAI,GAAG;AAAA,UACrB,GAAG,gBAAgB,IAAI,GAAG;AAAA,QAC5B;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,SAAO;AAAA,IACL,SAAS,EAAE,GAAG,OAAO,SAAS,GAAG,MAAM,QAAQ;AAAA,IAC/C;AAAA,EACF;AACF;AAEO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAAkD;AAChD,QAAM,SAAS,WAAW,mBAAmB;AAC7C,QAAM,SAAS,QAAQ,MAAM,YAAY,QAAQ,KAAK,GAAG,CAAC,QAAQ,KAAK,CAAC;AACxE,SACE,oBAAC,oBAAoB,UAApB,EAA6B,OAAO,QAClC,UACH;AAEJ;;;AEnDA,SAAS,cAAAA,aAAY,WAAAC,gBAAe;AAG7B,SAAS,qBACd,eACA,iBACA,OACO;AACP,QAAM,SAASC,YAAW,mBAAmB;AAC7C,QAAM,aAAa,OAAO;AAG1B,QAAM,mBAAmB,aAAa,aAAa,GAAG;AAEtD,SAAOC,SAAQ,MAAM;AAInB,UAAM,WAAoC;AAAA,MACxC,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AACA,eAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,UAAI,MAAM,GAAG,MAAM,OAAW,UAAS,GAAG,IAAI,MAAM,GAAG;AAAA,IACzD;AACA,WAAO;AAAA,EACT,GAAG,CAAC,iBAAiB,kBAAkB,KAAK,CAAC;AAC/C;","names":["useContext","useMemo","useContext","useMemo"]}
+{"version":3,"sources":["../../src/config/SonnetConfigProvider.tsx","../../src/config/SonnetConfigContext.ts","../../src/config/useComponentDefaults.ts","../../src/config/useLocale.ts"],"sourcesContent":["/**\n * SonnetConfigProvider -- sets app-wide component defaults.\n *\n * Place once at the app root to define default props for components (and\n * cross-cutting globals). Individual instances still override via props.\n * Nested providers merge into their parent, so a subtree can refine or\n * override outer defaults.\n *\n * Resolution order for any prop (see useComponentDefaults):\n *   instance prop > provider default > built-in default.\n */\n\nimport React, { useContext, useMemo } from \"react\";\nimport { SonnetConfigContext } from \"./SonnetConfigContext\";\nimport type { SonnetConfig } from \"./types\";\n\nexport interface SonnetConfigProviderProps {\n  /** The configuration to apply. Merged onto any parent provider's config. */\n  value: SonnetConfig;\n  children: React.ReactNode;\n}\n\n// Merge child config onto parent. Globals shallow-merge; component defaults\n// merge per component name, with each component's defaultProps shallow-merged\n// (child wins). One level of nesting is sufficient for the defaultProps shape.\nfunction mergeConfig(parent: SonnetConfig, child: SonnetConfig): SonnetConfig {\n  const components: Record<string, { defaultProps?: Record<string, unknown> }> =\n    {\n      ...(parent.components as Record<\n        string,\n        { defaultProps?: Record<string, unknown> }\n      >),\n    };\n  const childComponents = child.components as\n    | Record<string, { defaultProps?: Record<string, unknown> }>\n    | undefined;\n  if (childComponents) {\n    for (const name of Object.keys(childComponents)) {\n      components[name] = {\n        ...components[name],\n        ...childComponents[name],\n        defaultProps: {\n          ...components[name]?.defaultProps,\n          ...childComponents[name]?.defaultProps,\n        },\n      };\n    }\n  }\n  return {\n    globals: { ...parent.globals, ...child.globals },\n    components: components as SonnetConfig[\"components\"],\n  };\n}\n\nexport function SonnetConfigProvider({\n  value,\n  children,\n}: SonnetConfigProviderProps): React.ReactElement {\n  const parent = useContext(SonnetConfigContext);\n  const merged = useMemo(() => mergeConfig(parent, value), [parent, value]);\n  return (\n    <SonnetConfigContext.Provider value={merged}>\n      {children}\n    </SonnetConfigContext.Provider>\n  );\n}\n","/**\n * React context holding the resolved app-wide SonnetConfig.\n *\n * Nested providers merge into their parent (see SonnetConfigProvider), so a\n * provider deeper in the tree can refine or override an outer one for its\n * subtree. The default is an empty config -- with no provider, components fall\n * back to their built-in defaults, preserving existing behavior.\n */\n\nimport { createContext } from \"react\";\nimport type { SonnetConfig } from \"./types\";\n\nexport const SonnetConfigContext = createContext<SonnetConfig>({});\n","/**\n * useComponentDefaults -- resolve a component's props against app-wide config.\n *\n * Resolution order, per prop: instance prop > provider default > built-in.\n * A component calls this at the top of its body:\n *\n *   const resolved = useComponentDefaults(\"EntityTable\", BUILTIN, props);\n *\n * where BUILTIN is a stable (module-level) object of the component's built-in\n * defaults. With no provider in the tree, the result is BUILTIN merged with\n * props -- identical to not using the config at all, so existing behavior is\n * preserved.\n */\n\nimport { useContext, useMemo } from \"react\";\nimport { SonnetConfigContext } from \"./SonnetConfigContext\";\n\nexport function useComponentDefaults<Props extends Record<string, unknown>>(\n  componentName: string,\n  builtinDefaults: Partial<Props>,\n  props: Props,\n): Props {\n  const config = useContext(SonnetConfigContext);\n  const components = config.components as\n    | Record<string, { defaultProps?: Partial<Props> } | undefined>\n    | undefined;\n  const providerDefaults = components?.[componentName]?.defaultProps;\n\n  return useMemo(() => {\n    // Spread order encodes precedence: builtin < provider < instance props.\n    // Only undefined instance props fall through to provider/builtin, so an\n    // explicit prop always wins.\n    const resolved: Record<string, unknown> = {\n      ...builtinDefaults,\n      ...providerDefaults,\n    };\n    for (const key of Object.keys(props)) {\n      if (props[key] !== undefined) resolved[key] = props[key];\n    }\n    return resolved as Props;\n  }, [builtinDefaults, providerDefaults, props]);\n}\n","/**\n * useLocale -- resolve the active BCP-47 locale.\n *\n * Resolution order: explicit override > provider global (SonnetConfigProvider)\n * > browser (`navigator.language`) > `\"en\"`. Locale-sensitive components use\n * this for display and input parsing only; values exchanged with consumers\n * remain locale-independent (ISO).\n */\n\nimport { useContext } from \"react\";\nimport { SonnetConfigContext } from \"./SonnetConfigContext\";\n\n/** The browser locale, or \"en\" when unavailable (e.g. SSR). */\nexport function getBrowserLocale(): string {\n  if (typeof navigator !== \"undefined\" && navigator.language) {\n    return navigator.language;\n  }\n  return \"en\";\n}\n\nexport function useLocale(override?: string): string {\n  const config = useContext(SonnetConfigContext);\n  return override ?? config.globals?.locale ?? getBrowserLocale();\n}\n"],"mappings":";AAYA,SAAgB,YAAY,eAAe;;;ACH3C,SAAS,qBAAqB;AAGvB,IAAM,sBAAsB,cAA4B,CAAC,CAAC;;;ADiD7D;AApCJ,SAAS,YAAY,QAAsB,OAAmC;AAC5E,QAAM,aACJ;AAAA,IACE,GAAI,OAAO;AAAA,EAIb;AACF,QAAM,kBAAkB,MAAM;AAG9B,MAAI,iBAAiB;AACnB,eAAW,QAAQ,OAAO,KAAK,eAAe,GAAG;AAC/C,iBAAW,IAAI,IAAI;AAAA,QACjB,GAAG,WAAW,IAAI;AAAA,QAClB,GAAG,gBAAgB,IAAI;AAAA,QACvB,cAAc;AAAA,UACZ,GAAG,WAAW,IAAI,GAAG;AAAA,UACrB,GAAG,gBAAgB,IAAI,GAAG;AAAA,QAC5B;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,SAAO;AAAA,IACL,SAAS,EAAE,GAAG,OAAO,SAAS,GAAG,MAAM,QAAQ;AAAA,IAC/C;AAAA,EACF;AACF;AAEO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAAkD;AAChD,QAAM,SAAS,WAAW,mBAAmB;AAC7C,QAAM,SAAS,QAAQ,MAAM,YAAY,QAAQ,KAAK,GAAG,CAAC,QAAQ,KAAK,CAAC;AACxE,SACE,oBAAC,oBAAoB,UAApB,EAA6B,OAAO,QAClC,UACH;AAEJ;;;AEnDA,SAAS,cAAAA,aAAY,WAAAC,gBAAe;AAG7B,SAAS,qBACd,eACA,iBACA,OACO;AACP,QAAM,SAASC,YAAW,mBAAmB;AAC7C,QAAM,aAAa,OAAO;AAG1B,QAAM,mBAAmB,aAAa,aAAa,GAAG;AAEtD,SAAOC,SAAQ,MAAM;AAInB,UAAM,WAAoC;AAAA,MACxC,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AACA,eAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,UAAI,MAAM,GAAG,MAAM,OAAW,UAAS,GAAG,IAAI,MAAM,GAAG;AAAA,IACzD;AACA,WAAO;AAAA,EACT,GAAG,CAAC,iBAAiB,kBAAkB,KAAK,CAAC;AAC/C;;;AChCA,SAAS,cAAAC,mBAAkB;AAIpB,SAAS,mBAA2B;AACzC,MAAI,OAAO,cAAc,eAAe,UAAU,UAAU;AAC1D,WAAO,UAAU;AAAA,EACnB;AACA,SAAO;AACT;AAEO,SAAS,UAAU,UAA2B;AACnD,QAAM,SAASC,YAAW,mBAAmB;AAC7C,SAAO,YAAY,OAAO,SAAS,UAAU,iBAAiB;AAChE;","names":["useContext","useMemo","useContext","useMemo","useContext","useContext"]}

package/dist/index.d.ts

@@ -34,6 +34,189 @@ declare function formatDateTimeTz(iso: string | null | undefined): string;
 /** Return "{count} {word}" with the word pluralized when count != 1. */
 declare function pluralize(count: number, word: string): string;
 
+/**
+ * Date parsing and formatting -- pure functional API.
+ *
+ * The public surface is a set of pure functions. A `CompiledDateFormat`
+ * pre-computes the format structure so repeated parse/format calls (e.g.
+ * on every keystroke) don't re-derive component positions each time. Call
+ * `compileDateFormat` once in a `useMemo` and pass the result to
+ * `parseDate` / `formatDateInput`.
+ *
+ * The parser operates on native `Date` values internally. Widgets and form
+ * data exchange locale-independent ISO 8601 strings -- use
+ * `formatIsoDate` / `parseIsoDate` at the boundary.
+ */
+/**
+ * Pre-compiled date format. Opaque to callers; produced by
+ * {@link compileDateFormat} and consumed by {@link parseDate} and
+ * {@link formatDateInput}.
+ */
+interface CompiledDateFormat {
+    readonly format: string;
+    readonly yearThreshold: number;
+    readonly dayIndex: number;
+    readonly monthIndex: number;
+    readonly yearIndex: number;
+    readonly has2DigitYear: boolean;
+    readonly validSeparators: readonly string[];
+}
+/** Options for {@link compileDateFormat}. */
+interface DateFormatOptions {
+    /**
+     * Component order for parsing and display. Supported tokens: `DD` (day),
+     * `MM` (month), `YYYY` or `YY` (year). Default: `"DD/MM/YYYY"`.
+     */
+    format?: string;
+    /**
+     * Threshold for expanding 2-digit years. If a 2-digit year is greater than
+     * this value it is treated as the prior century, otherwise the current one.
+     * Special cases: `0` always current century, `-1` always prior century.
+     * Default: the current year modulo 100, captured at compile time.
+     */
+    yearThreshold?: number;
+}
+/** Result of {@link parseDate}. */
+interface DateParseResult {
+    /** Normalized display string (formatted per the compiled format), or "" on failure. */
+    value: string;
+    /** Parsed `Date` object, or null on failure. Needed by calendar components. */
+    date: Date | null;
+    /** Error message on failure, or "" on success. */
+    error: string;
+}
+/**
+ * Precision of a partial ISO 8601 date:
+ *   year  -> "YYYY"
+ *   month -> "YYYY-MM"
+ *   day   -> "YYYY-MM-DD"
+ */
+type DatePrecision = "year" | "month" | "day";
+/**
+ * Pre-compile a date format string into an opaque `CompiledDateFormat`.
+ *
+ * Call once per format string (e.g. in `useMemo`) and pass the result to
+ * {@link parseDate} and {@link formatDateInput}.
+ */
+declare function compileDateFormat(options?: DateFormatOptions): CompiledDateFormat;
+/**
+ * Parse a user-entered date string against a compiled format.
+ *
+ * Accepts colon/separator-split and compact numeric input. The shorthands
+ * `"."`, `"t"`, and `"today"` resolve to the current date. Empty input
+ * returns `{ value: "", date: null, error: "" }`.
+ */
+declare function parseDate(input: string, fmt: CompiledDateFormat): DateParseResult;
+/**
+ * Format a `Date` as a display string using the compiled format.
+ * Returns "" for null or invalid dates.
+ */
+declare function formatDateInput(date: Date | null | undefined, fmt: CompiledDateFormat): string;
+/** Whether two dates fall on the same calendar day. */
+declare function isDateEqual(a: Date | null, b: Date | null): boolean;
+/**
+ * Convert a local `Date` to a partial ISO date string at the given precision
+ * (default `"day"`), using local components (no timezone shift).
+ * Returns "" for null or invalid dates.
+ */
+declare function formatIsoDate(date: Date | null | undefined, precision?: DatePrecision): string;
+/**
+ * Parse a partial ISO date string (`YYYY`, `YYYY-MM`, or `YYYY-MM-DD`) into a
+ * local `Date`. Missing month/day default to January/1st. Returns null for
+ * empty or malformed input.
+ */
+declare function parseIsoDate(iso: string | null | undefined): Date | null;
+/**
+ * Detect the precision of a partial ISO date string.
+ * Returns `"day"` for empty, malformed, or full-date input.
+ */
+declare function isoDatePrecision(iso: string | null | undefined): DatePrecision;
+
+/**
+ * Time parsing and formatting -- pure functional API.
+ *
+ * A time-of-day is a zone-free wall-clock value (Temporal.PlainTime): it
+ * carries no date and no timezone. Values are normalized ISO time strings:
+ * `"HH:mm"` (minute granularity) or `"HH:mm:ss"` (second granularity).
+ *
+ * API conventions match dateParser.ts:
+ *   parseTime(input, granularity) -> TimeParseResult { value, error }
+ *   formatIsoTime(h, m, s, granularity) -> string
+ *   normalizeTime(iso, granularity) -> string
+ * An empty or failed result is represented as `value: ""`, not null.
+ */
+/** Granularity of a time value: minutes or seconds. */
+type TimeGranularity = "minute" | "second";
+/** Result of {@link parseTime}. */
+interface TimeParseResult {
+    /** Normalized ISO time string, or "" when parsing failed or input is empty. */
+    value: string;
+    /** Error message on failure, or "" on success. */
+    error: string;
+}
+/**
+ * Format H/M/S integer components as a normalized ISO time string.
+ * This is an internal building block; consumers typically use {@link normalizeTime}.
+ */
+declare function formatIsoTime(hour: number, minute: number, second: number, granularity?: TimeGranularity): string;
+/**
+ * Parse a user-entered time string into a normalized ISO time value.
+ *
+ * Accepts colon-separated (`"9:30"`, `"21:05:00"`) and compact numeric
+ * (`"0930"`, `"213005"`) forms. Missing minutes/seconds default to zero.
+ * The shorthands `"."`, `"n"`, and `"now"` resolve to the current time.
+ * Empty input returns `{ value: "", error: "" }`.
+ */
+declare function parseTime(input: string, granularity?: TimeGranularity): TimeParseResult;
+/**
+ * Normalize an ISO time string (`"HH:mm"` or `"HH:mm:ss"`) to the requested
+ * granularity. Returns "" for empty or malformed input.
+ */
+declare function normalizeTime(iso: string | null | undefined, granularity?: TimeGranularity): string;
+/**
+ * Split a plain wall-clock datetime (`"YYYY-MM-DDTHH:mm[:ss]"`) into its date
+ * (`"YYYY-MM-DD"`) and time (`"HH:mm[:ss]"`) halves. Missing halves return "".
+ */
+declare function splitDateTime(iso: string | null | undefined): {
+    date: string;
+    time: string;
+};
+/**
+ * Join a date (`"YYYY-MM-DD"`) and time (`"HH:mm[:ss]"`) into a plain
+ * wall-clock datetime. Returns "" when the date is missing; a missing time
+ * yields the date alone.
+ */
+declare function joinDateTime(date: string, time: string): string;
+
+/**
+ * Locale-derived date formatting metadata.
+ *
+ * Uses the Intl APIs (no dependency) to derive, for a BCP-47 locale:
+ *   - the day/month/year order and separator, as a DateParser format string
+ *   - localized short weekday labels
+ *   - the first day of the week (0 = Sunday .. 6 = Saturday)
+ *
+ * These drive display and input parsing only; exchanged values stay ISO.
+ */
+
+/** DateParser format string per precision, derived for a locale. */
+interface LocaleDateFormats {
+    year: string;
+    month: string;
+    day: string;
+}
+/** Derive DateParser format strings for each precision in the given locale. */
+declare function getLocaleDateFormats(locale: string): LocaleDateFormats;
+/** Derive the DateParser format for a single precision in the given locale. */
+declare function getLocaleDateFormat(locale: string, precision: DatePrecision): string;
+/**
+ * Localized short weekday labels ordered from the locale's first day of week.
+ * Returns 7 entries, e.g. `["Mon","Tue",...]` or `["Sun","Mon",...]`.
+ */
+declare function getWeekdayLabels(locale: string): string[];
+/** First day of the week for the locale: 0 = Sunday .. 6 = Saturday. */
+declare function getFirstDayOfWeek(locale: string): number;
+
 /**
  * Escapes HTML characters to prevent XSS and rendering issues
  */
@@ -146,4 +329,4 @@ interface PageResult<T> {
  */
 declare function toPageResult<T>(rows: T[]): PageResult<T>;
 
-export { FORM_ITEM_ID_FIELD, JSON_CSS_VARIABLES, type NormalizedError, type OffsetRange, type PageMeta, type PageResult, cn, copyTextToClipboard, devLog, errorLog, escapeHtml, formatDate, formatDateTime, formatDateTimeTz, formatJsonValue, formatNumber, formatNumberCompact, generateId, infoLog, isEqual, normalizeError, pluralize, resolvePointerRanges, snakeCaseToTitleCase, toPageResult, useComposedRefs, warnLog };
+export { type CompiledDateFormat, type DateFormatOptions, type DateParseResult, type DatePrecision, FORM_ITEM_ID_FIELD, JSON_CSS_VARIABLES, type LocaleDateFormats, type NormalizedError, type OffsetRange, type PageMeta, type PageResult, type TimeGranularity, type TimeParseResult, cn, compileDateFormat, copyTextToClipboard, devLog, errorLog, escapeHtml, formatDate, formatDateInput, formatDateTime, formatDateTimeTz, formatIsoDate, formatIsoTime, formatJsonValue, formatNumber, formatNumberCompact, generateId, getFirstDayOfWeek, getLocaleDateFormat, getLocaleDateFormats, getWeekdayLabels, infoLog, isDateEqual, isEqual, isoDatePrecision, joinDateTime, normalizeError, normalizeTime, parseDate, parseIsoDate, parseTime, pluralize, resolvePointerRanges, snakeCaseToTitleCase, splitDateTime, toPageResult, useComposedRefs, warnLog };

package/dist/index.js

@@ -77,6 +77,306 @@ function pluralize(count, word) {
   return `${count} ${word}${count !== 1 ? "s" : ""}`;
 }
 
+// src/dateParser.ts
+var VALID_SEPARATORS = ["/", "-", "."];
+function compileDateFormat(options = {}) {
+  const format = options.format ?? "DD/MM/YYYY";
+  const yearThreshold = options.yearThreshold ?? (/* @__PURE__ */ new Date()).getFullYear() % 100;
+  const parts = format.split(/[^A-Z]+/);
+  const dayIndex = parts.findIndex((p) => p === "DD");
+  const monthIndex = parts.findIndex((p) => p === "MM");
+  const yearIndex = parts.findIndex((p) => p === "YYYY" || p === "YY");
+  const has2DigitYear = yearIndex !== -1 && parts[yearIndex] === "YY";
+  if (dayIndex === -1 && monthIndex === -1 && yearIndex === -1) {
+    throw new Error(
+      "Invalid date format. Must contain at least one of DD, MM, or YYYY/YY."
+    );
+  }
+  return {
+    format,
+    yearThreshold,
+    dayIndex,
+    monthIndex,
+    yearIndex,
+    has2DigitYear,
+    validSeparators: VALID_SEPARATORS
+  };
+}
+function cleanInput(input, fmt) {
+  return input.replace(
+    new RegExp(
+      `[^0-9${fmt.validSeparators.map((s) => "\\" + s).join("")}+-]`,
+      "g"
+    ),
+    ""
+  );
+}
+function expandYear(yearStr, fmt) {
+  const year = parseInt(yearStr, 10);
+  if (yearStr.length >= 4) return year;
+  const refYear = fmt.yearThreshold + Math.floor((/* @__PURE__ */ new Date()).getFullYear() / 100) * 100;
+  const century = Math.floor(refYear / 100) * 100;
+  if (fmt.yearThreshold === 0) return century + year;
+  if (fmt.yearThreshold === -1) return century - 100 + year;
+  return year > fmt.yearThreshold ? century - 100 + year : century + year;
+}
+function parseWithSeparators(input, fmt) {
+  const parts = input.split(
+    new RegExp(`[${fmt.validSeparators.map((s) => "\\" + s).join("")}]`)
+  );
+  const result = {
+    day: null,
+    month: null,
+    year: null
+  };
+  for (let i = 0; i < parts.length; i++) {
+    if (!parts[i]) continue;
+    if (i === fmt.dayIndex) result.day = parseInt(parts[i], 10);
+    else if (i === fmt.monthIndex) result.month = parseInt(parts[i], 10);
+    else if (i === fmt.yearIndex) result.year = expandYear(parts[i], fmt);
+  }
+  return result;
+}
+function parseWithoutSeparators(input, fmt) {
+  const result = {
+    day: null,
+    month: null,
+    year: null
+  };
+  const yearLength = fmt.has2DigitYear ? 2 : 4;
+  const components = [
+    { type: "day", index: fmt.dayIndex, length: 2 },
+    { type: "month", index: fmt.monthIndex, length: 2 },
+    { type: "year", index: fmt.yearIndex, length: yearLength }
+  ].filter((c) => c.index !== -1).sort((a, b) => a.index - b.index);
+  let remaining = input;
+  for (const c of components) {
+    if (!remaining.length) break;
+    const len = Math.min(c.length, remaining.length);
+    const val = remaining.substring(0, len);
+    remaining = remaining.substring(len);
+    if (c.type === "day") result.day = parseInt(val, 10);
+    else if (c.type === "month") result.month = parseInt(val, 10);
+    else if (c.type === "year") result.year = expandYear(val, fmt);
+  }
+  return result;
+}
+function daysInMonth(month, year) {
+  if (month === 2) {
+    const leap = year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+    return leap ? 29 : 28;
+  }
+  return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+function isValidDate(day, month, year) {
+  if (month < 1 || month > 12) return false;
+  if (year < 1900 || year > 2100) return false;
+  if (day < 1 || day > daysInMonth(month, year)) return false;
+  return true;
+}
+function buildDateResult(parsed, fmt) {
+  const today = /* @__PURE__ */ new Date();
+  const day = parsed.day ?? today.getDate();
+  const month = parsed.month ?? today.getMonth() + 1;
+  const year = parsed.year ?? today.getFullYear();
+  if (!isValidDate(day, month, year)) {
+    return { value: "", date: null, error: "Invalid date" };
+  }
+  const date = new Date(year, month - 1, day);
+  return { value: formatDateInput(date, fmt), date, error: "" };
+}
+function parseDate(input, fmt) {
+  if (!input || !input.trim()) return { value: "", date: null, error: "" };
+  if ([".", "t", "today"].includes(input.trim().toLowerCase())) {
+    const today = /* @__PURE__ */ new Date();
+    return { value: formatDateInput(today, fmt), date: today, error: "" };
+  }
+  const cleaned = cleanInput(input, fmt);
+  if (!cleaned) {
+    return { value: "", date: null, error: "Invalid characters in date" };
+  }
+  const hasSeparators = fmt.validSeparators.some((s) => cleaned.includes(s));
+  try {
+    const parsed = hasSeparators ? parseWithSeparators(cleaned, fmt) : parseWithoutSeparators(cleaned, fmt);
+    return buildDateResult(parsed, fmt);
+  } catch (e) {
+    return {
+      value: "",
+      date: null,
+      error: e instanceof Error ? e.message : "Invalid date format"
+    };
+  }
+}
+function formatDateInput(date, fmt) {
+  if (!date || isNaN(date.getTime())) return "";
+  const tokens = {
+    DD: date.getDate().toString().padStart(2, "0"),
+    MM: (date.getMonth() + 1).toString().padStart(2, "0"),
+    YYYY: date.getFullYear().toString(),
+    YY: date.getFullYear().toString().slice(-2)
+  };
+  return fmt.format.replace(/DD|MM|YYYY|YY/g, (m) => tokens[m]);
+}
+function isDateEqual(a, b) {
+  if (!a || !b) return false;
+  return a.getDate() === b.getDate() && a.getMonth() === b.getMonth() && a.getFullYear() === b.getFullYear();
+}
+function formatIsoDate(date, precision = "day") {
+  if (!date || isNaN(date.getTime())) return "";
+  const year = date.getFullYear().toString().padStart(4, "0");
+  if (precision === "year") return year;
+  const month = (date.getMonth() + 1).toString().padStart(2, "0");
+  if (precision === "month") return `${year}-${month}`;
+  const day = date.getDate().toString().padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function parseIsoDate(iso) {
+  if (!iso) return null;
+  const match = iso.match(/^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/);
+  if (!match) return null;
+  const [, year, month, day] = match;
+  const date = new Date(
+    Number(year),
+    month ? Number(month) - 1 : 0,
+    day ? Number(day) : 1
+  );
+  return isNaN(date.getTime()) ? null : date;
+}
+function isoDatePrecision(iso) {
+  if (!iso) return "day";
+  if (/^\d{4}$/.test(iso)) return "year";
+  if (/^\d{4}-\d{2}$/.test(iso)) return "month";
+  return "day";
+}
+
+// src/timeParser.ts
+function splitDigits(digits) {
+  if (digits.length <= 2) return [Number(digits)];
+  if (digits.length <= 4) {
+    return [
+      Number(digits.slice(0, digits.length - 2)),
+      Number(digits.slice(-2))
+    ];
+  }
+  return [
+    Number(digits.slice(0, digits.length - 4)),
+    Number(digits.slice(-4, -2)),
+    Number(digits.slice(-2))
+  ];
+}
+function extractParts(input) {
+  if (input.includes(":")) {
+    const parts = input.split(":");
+    if (parts.length > 3 || parts[parts.length - 1] === "") {
+      return [];
+    }
+    return parts.map((p) => Number(p));
+  }
+  return splitDigits(input);
+}
+function isValidTime(hour, minute, second) {
+  const inRange = (n, max) => Number.isInteger(n) && n >= 0 && n <= max;
+  return inRange(hour, 23) && inRange(minute, 59) && inRange(second, 59);
+}
+function formatIsoTime(hour, minute, second, granularity = "minute") {
+  const hh = hour.toString().padStart(2, "0");
+  const mm = minute.toString().padStart(2, "0");
+  if (granularity === "minute") return `${hh}:${mm}`;
+  const ss = second.toString().padStart(2, "0");
+  return `${hh}:${mm}:${ss}`;
+}
+function parseTime(input, granularity = "minute") {
+  if (!input || !input.trim()) return { value: "", error: "" };
+  if ([".", "n", "now"].includes(input.trim().toLowerCase())) {
+    const now = /* @__PURE__ */ new Date();
+    return {
+      value: formatIsoTime(
+        now.getHours(),
+        now.getMinutes(),
+        now.getSeconds(),
+        granularity
+      ),
+      error: ""
+    };
+  }
+  const cleaned = input.replace(/[^0-9:]/g, "");
+  if (!cleaned) return { value: "", error: "Invalid characters in time" };
+  return parseCleanedTime(cleaned, granularity);
+}
+function parseCleanedTime(cleaned, granularity) {
+  const parts = extractParts(cleaned);
+  if (!parts.length) return { value: "", error: "Invalid time format" };
+  const hour = parts[0] ?? 0;
+  const minute = parts[1] ?? 0;
+  const second = parts[2] ?? 0;
+  if (!isValidTime(hour, minute, second)) {
+    return { value: "", error: "Invalid time" };
+  }
+  return { value: formatIsoTime(hour, minute, second, granularity), error: "" };
+}
+function normalizeTime(iso, granularity = "minute") {
+  if (!iso) return "";
+  return parseTime(iso, granularity).value;
+}
+function splitDateTime(iso) {
+  if (!iso) return { date: "", time: "" };
+  const [date, time] = iso.split("T");
+  return { date: date ?? "", time: time ?? "" };
+}
+function joinDateTime(date, time) {
+  if (!date) return "";
+  return time ? `${date}T${time}` : date;
+}
+
+// src/localeFormat.ts
+function dayFormatFromParts(locale) {
+  const parts = new Intl.DateTimeFormat(locale, {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(new Date(2023, 0, 2));
+  const tokens = [];
+  let separator = "/";
+  for (const part of parts) {
+    if (part.type === "day") tokens.push("DD");
+    else if (part.type === "month") tokens.push("MM");
+    else if (part.type === "year") tokens.push("YYYY");
+    else if (part.type === "literal") {
+      const trimmed = part.value.trim();
+      if (trimmed) separator = trimmed[0];
+    }
+  }
+  if (tokens.length !== 3) return "DD/MM/YYYY";
+  return tokens.join(separator);
+}
+function getLocaleDateFormats(locale) {
+  const day = dayFormatFromParts(locale);
+  const month = day.replace(/DD.|.DD/, "");
+  return { year: "YYYY", month, day };
+}
+function getLocaleDateFormat(locale, precision) {
+  return getLocaleDateFormats(locale)[precision];
+}
+function getWeekdayLabels(locale) {
+  const first = getFirstDayOfWeek(locale);
+  const formatter = new Intl.DateTimeFormat(locale, { weekday: "short" });
+  return Array.from(
+    { length: 7 },
+    (_, i) => formatter.format(new Date(2023, 0, 1 + (first + i) % 7))
+  );
+}
+function getFirstDayOfWeek(locale) {
+  try {
+    const loc = new Intl.Locale(locale);
+    const info = loc.getWeekInfo?.() ?? loc.weekInfo;
+    if (info?.firstDay !== void 0) {
+      return info.firstDay === 7 ? 0 : info.firstDay;
+    }
+  } catch {
+  }
+  return 1;
+}
+
 // src/jsonUtils.ts
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -395,23 +695,39 @@ export {
   FORM_ITEM_ID_FIELD,
   JSON_CSS_VARIABLES,
   cn,
+  compileDateFormat,
   copyTextToClipboard,
   devLog,
   errorLog,
   escapeHtml,
   formatDate,
+  formatDateInput,
   formatDateTime,
   formatDateTimeTz,
+  formatIsoDate,
+  formatIsoTime,
   formatJsonValue,
   formatNumber,
   formatNumberCompact,
   generateId,
+  getFirstDayOfWeek,
+  getLocaleDateFormat,
+  getLocaleDateFormats,
+  getWeekdayLabels,
   infoLog,
+  isDateEqual,
   isEqual,
+  isoDatePrecision,
+  joinDateTime,
   normalizeError,
+  normalizeTime,
+  parseDate,
+  parseIsoDate,
+  parseTime,
   pluralize,
   resolvePointerRanges,
   snakeCaseToTitleCase_default as snakeCaseToTitleCase,
+  splitDateTime,
   toPageResult,
   useComposedRefs,
   warnLog