@petrarca/sonnet-core 0.5.0 → 0.7.0

package/README.md

@@ -1,28 +1,28 @@
 # @petrarca/sonnet-core
 
-Foundation utilities for the Petrarca Sonnet component library. Leaf package —
-all other Sonnet packages depend on it.
-
-## Entry points
-
-| Import | What |
-|---|---|
-| `@petrarca/sonnet-core` | `cn`, `isEqual`, `formatDateTime`, `normalizeError`, logging |
-| `@petrarca/sonnet-core/schema` | JSON Schema types, resolution, validation, diffing |
-| `@petrarca/sonnet-core/search` | Filter expression types (`FilterExpr`, `buildListParams`) |
-| `@petrarca/sonnet-core/hooks` | React hooks (see below) |
-| `@petrarca/sonnet-core/entityOptions` | Entity option fetcher context for async select/autocomplete |
-
-## Hooks
-
-| Hook | Purpose |
-|---|---|
-| `useClipboard` | Copy text to clipboard with copied-state timeout |
-| `useDisclosure` | Boolean open/close/toggle state |
-| `useFormState` | Generic form state with dirty tracking |
-| `useEntityOptions` | Async entity fetching for select/autocomplete components |
-| `useResizablePanel` | Drag-to-resize panel width |
-| `useTreeExpansion` | Expand/collapse state for `TreeView` components |
+The foundation of the Petrarca Sonnet component library: schema handling,
+filter expressions, React hooks and formatting helpers, with no components
+attached. Every other `@petrarca/sonnet-*` package depends on it.
+
+## What it provides
+
+**A JSON Schema toolkit.** The `JsonSchema` and `UISchema` types that the rest
+of the workspace agrees on, plus `$ref` and conditional resolution, validation
+through Ajv, visibility rules and form diffing.
+
+**A Zod bridge.** Author a schema in Zod, carry the `x-ui-*` presentation hints
+on `.meta()`, and convert once to the JSON Schema the renderers read.
+
+**Filter expressions.** A serializable AST for search and faceted filtering,
+and the helpers that turn it into list query parameters.
+
+**Component configuration.** An app-wide default-props provider and locale
+resolution, so a behavioural prop can be set once for a whole application
+instead of at every call site.
+
+**Hooks and utilities.** Clipboard, disclosure, form state, tree expansion,
+resizable panels and async entity options, alongside date, time, number, id,
+error and class-merging helpers.
 
 ## Install
 
@@ -30,6 +30,45 @@ all other Sonnet packages depend on it.
 pnpm add @petrarca/sonnet-core
 ```
 
+| Peer | Range | Needed for |
+|---|---|---|
+| `react` | `>=19` | The `./hooks`, `./config` and `./entityOptions` subpaths |
+| `@tanstack/react-query` | `>=5` | `useEntityOptions` only; optional otherwise |
+
+Ajv, Zod, `nanoid`, `clsx`, `tailwind-merge` and `class-variance-authority`
+arrive as regular dependencies. There is nothing else to install.
+
+## Usage
+
+The package is six entry points, and the root deliberately re-exports none of
+the other five: a caller who wants `formatDate` should not pay for Ajv, and one
+who wants the filter AST should not pull in React.
+
+```ts
+import { formatDate, generateId } from "@petrarca/sonnet-core";
+import { validateFormData, type JsonSchema } from "@petrarca/sonnet-core/schema";
+import { buildListParams } from "@petrarca/sonnet-core/search";
+import { useDisclosure } from "@petrarca/sonnet-core/hooks";
+import { FetcherContext } from "@petrarca/sonnet-core/entityOptions";
+import { SonnetConfigProvider } from "@petrarca/sonnet-core/config";
+```
+
+Which symbol lives in which subpath, and what each one costs to import, is in
+the usage guides:
+[the schema toolkit](docs/usage/schema-toolkit.md),
+[schemas from Zod](docs/usage/zod-schemas.md),
+[search filters](docs/usage/search-filters.md),
+[component config](docs/usage/component-config.md) and
+[hooks and utilities](docs/usage/hooks-and-utilities.md).
+
+## Documentation
+
+- [Usage guides](docs/usage/index.md) -- task-oriented, for consumers.
+- [Design docs](docs/design/index.md) -- what belongs in this package and why
+  it is split into six subpaths.
+- [Workspace documentation](../../docs/README.md) -- how the packages layer, the
+  shared schema extension contract, and the architecture decision records.
+
 ## License
 
-See [LICENSE.md](../../LICENSE.md).
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).

package/dist/config/index.d.ts

@@ -28,8 +28,53 @@ import React__default from 'react';
  */
 interface SonnetComponentDefaults {
 }
-/** Cross-cutting global settings. Extend via declaration merging as needed. */
+/**
+ * When a form reveals a field's validation error.
+ *
+ * - `onSubmit` (default) -- quiet until the first save attempt, then reveal
+ *   all. Matches the prior art: rjsf performs no live validation unless
+ *   `liveValidate` is opted into.
+ * - `onTouched` -- a field reveals its error once it has been touched (focused
+ *   then blurred), and every invalid field reveals on a save attempt. Gives
+ *   earlier feedback, at the cost of an error appearing mid-interaction, which
+ *   grows the field and shifts whatever sits below it.
+ * - `always` -- every invalid field shows its error immediately.
+ *
+ * This governs display only. Validity is always computed regardless.
+ */
+type ValidationDisplay = "onTouched" | "always" | "onSubmit";
+/**
+ * Whether a form's save action is available while the form is invalid.
+ *
+ * - `reveal` (default) -- Save stays enabled; pressing it on an invalid form
+ *   reveals every field's error and does not submit. The button always
+ *   explains why it did not save.
+ * - `disable` -- Save is disabled while invalid. Simpler, but a disabled
+ *   button gives no reason, and it cannot trigger the save-attempt reveal.
+ */
+type SaveWhenInvalid = "reveal" | "disable";
+/**
+ * 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;
+    /**
+     * App-wide default for when forms reveal validation errors. A form may
+     * override it with its own `validationDisplay` prop. Defaults to `onSubmit`.
+     */
+    validationDisplay?: ValidationDisplay;
+    /**
+     * App-wide default for whether Save is available on an invalid form. A form
+     * may override it with its own `saveWhenInvalid` prop. Defaults to `reveal`.
+     */
+    saveWhenInvalid?: SaveWhenInvalid;
 }
 /** The full app-wide configuration object held by SonnetConfigProvider. */
 interface SonnetConfig {
@@ -75,4 +120,31 @@ 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;
+
+/**
+ * useGlobalSetting -- resolve one SonnetGlobalConfig field.
+ *
+ * Resolution order: explicit override (a component's own prop) > provider
+ * global (SonnetConfigProvider) > the caller's fallback. This is the shared
+ * shape behind useLocale, useValidationDisplay and useSaveWhenInvalid: a house
+ * default set once at the root, overridable per instance.
+ */
+
+declare function useGlobalSetting<K extends keyof SonnetGlobalConfig>(key: K, override: SonnetGlobalConfig[K], fallback: NonNullable<SonnetGlobalConfig[K]>): NonNullable<SonnetGlobalConfig[K]>;
+/** Resolve when a form reveals validation errors. Defaults to `"onSubmit"`. */
+declare function useValidationDisplay(override?: SonnetGlobalConfig["validationDisplay"]): NonNullable<SonnetGlobalConfig["validationDisplay"]>;
+/** Resolve whether Save is available on an invalid form. Defaults to `"reveal"`. */
+declare function useSaveWhenInvalid(override?: SonnetGlobalConfig["saveWhenInvalid"]): NonNullable<SonnetGlobalConfig["saveWhenInvalid"]>;
+
+export { type SaveWhenInvalid, type SonnetComponentDefaults, type SonnetConfig, SonnetConfigContext, SonnetConfigProvider, type SonnetConfigProviderProps, type SonnetGlobalConfig, type ValidationDisplay, getBrowserLocale, useComponentDefaults, useGlobalSetting, useLocale, useSaveWhenInvalid, useValidationDisplay };

package/dist/config/index.js

@@ -55,9 +55,40 @@ 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();
+}
+
+// src/config/useGlobalSetting.ts
+import { useContext as useContext4 } from "react";
+function useGlobalSetting(key, override, fallback) {
+  const config = useContext4(SonnetConfigContext);
+  return override ?? config.globals?.[key] ?? fallback;
+}
+function useValidationDisplay(override) {
+  return useGlobalSetting("validationDisplay", override, "onSubmit");
+}
+function useSaveWhenInvalid(override) {
+  return useGlobalSetting("saveWhenInvalid", override, "reveal");
+}
 export {
   SonnetConfigContext,
   SonnetConfigProvider,
-  useComponentDefaults
+  getBrowserLocale,
+  useComponentDefaults,
+  useGlobalSetting,
+  useLocale,
+  useSaveWhenInvalid,
+  useValidationDisplay
 };
 //# 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","../../src/config/useGlobalSetting.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","/**\n * useGlobalSetting -- resolve one SonnetGlobalConfig field.\n *\n * Resolution order: explicit override (a component's own prop) > provider\n * global (SonnetConfigProvider) > the caller's fallback. This is the shared\n * shape behind useLocale, useValidationDisplay and useSaveWhenInvalid: a house\n * default set once at the root, overridable per instance.\n */\n\nimport { useContext } from \"react\";\nimport { SonnetConfigContext } from \"./SonnetConfigContext\";\nimport type { SonnetGlobalConfig } from \"./types\";\n\nexport function useGlobalSetting<K extends keyof SonnetGlobalConfig>(\n  key: K,\n  override: SonnetGlobalConfig[K],\n  fallback: NonNullable<SonnetGlobalConfig[K]>,\n): NonNullable<SonnetGlobalConfig[K]> {\n  const config = useContext(SonnetConfigContext);\n  return override ?? config.globals?.[key] ?? fallback;\n}\n\n/** Resolve when a form reveals validation errors. Defaults to `\"onSubmit\"`. */\nexport function useValidationDisplay(\n  override?: SonnetGlobalConfig[\"validationDisplay\"],\n): NonNullable<SonnetGlobalConfig[\"validationDisplay\"]> {\n  return useGlobalSetting(\"validationDisplay\", override, \"onSubmit\");\n}\n\n/** Resolve whether Save is available on an invalid form. Defaults to `\"reveal\"`. */\nexport function useSaveWhenInvalid(\n  override?: SonnetGlobalConfig[\"saveWhenInvalid\"],\n): NonNullable<SonnetGlobalConfig[\"saveWhenInvalid\"]> {\n  return useGlobalSetting(\"saveWhenInvalid\", override, \"reveal\");\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;;;ACdA,SAAS,cAAAC,mBAAkB;AAIpB,SAAS,iBACd,KACA,UACA,UACoC;AACpC,QAAM,SAASC,YAAW,mBAAmB;AAC7C,SAAO,YAAY,OAAO,UAAU,GAAG,KAAK;AAC9C;AAGO,SAAS,qBACd,UACsD;AACtD,SAAO,iBAAiB,qBAAqB,UAAU,UAAU;AACnE;AAGO,SAAS,mBACd,UACoD;AACpD,SAAO,iBAAiB,mBAAmB,UAAU,QAAQ;AAC/D;","names":["useContext","useMemo","useContext","useMemo","useContext","useContext","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 };