najm-kit 2.11.13 → 2.11.15

package/dist/{NajmUIProvider-DTyRrukg.d.ts → NajmUIProvider-BwL5HFIV.d.ts}

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default from 'react';
-import { e as NajmMode, a as NajmDesignConfig } from './design-types-Rkpt8Pg1.js';
+import { b as NajmMode, N as NajmDesignConfig } from './design-types-DffH_9XC.js';
 import { b as NTablePaginationLabels, N as NajmTranslate } from './paginationLabels-dZLSNxfo.js';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';

package/dist/adapters/app.d.ts

@@ -3,11 +3,11 @@ import { Translations } from 'najm-i18n';
 import { F as FormDevToolsOptions, N as NBrandingInput } from '../NNotFoundState-CgU76llk.js';
 export { a as NEmptyState, b as NEmptyStateProps, c as NErrorState, d as NErrorStateProps, e as NFeedbackSurface, f as NForbiddenState, g as NForbiddenStateProps, h as NLoadingState, i as NLoadingStateProps, j as NNotFoundState, k as NNotFoundStateProps } from '../NNotFoundState-CgU76llk.js';
 import { NajmNextUIProviderProps } from './next.js';
-export { D as DEFAULT_FEEDBACK_KEY_PREFIX, F as FeedbackKey, N as NFeedbackDefaults, a as NFeedbackLabelKeys, b as NFeedbackLabels } from '../NajmUIProvider-DTyRrukg.js';
+export { D as DEFAULT_FEEDBACK_KEY_PREFIX, F as FeedbackKey, N as NFeedbackDefaults, a as NFeedbackLabelKeys, b as NFeedbackLabels } from '../NajmUIProvider-BwL5HFIV.js';
 import 'zod';
 import 'lucide-react';
 import 'next/image';
-import '../design-types-Rkpt8Pg1.js';
+import '../design-types-DffH_9XC.js';
 import '../paginationLabels-dZLSNxfo.js';
 import 'class-variance-authority/types';
 import 'class-variance-authority';

package/dist/adapters/next.d.ts

@@ -1,7 +1,7 @@
 import React__default from 'react';
 import { ImageProps } from 'next/image';
-import { c as NajmUIProviderProps } from '../NajmUIProvider-DTyRrukg.js';
-import '../design-types-Rkpt8Pg1.js';
+import { c as NajmUIProviderProps } from '../NajmUIProvider-BwL5HFIV.js';
+import '../design-types-DffH_9XC.js';
 import '../paginationLabels-dZLSNxfo.js';
 import 'class-variance-authority/types';
 import 'class-variance-authority';

package/dist/chunk-XGIYOEWD.mjs

@@ -0,0 +1,28 @@
+// src/lib/timeZones.ts
+var NAJM_TIME_ZONES = [
+  "UTC",
+  "Atlantic/Azores",
+  "America/Los_Angeles",
+  "America/Denver",
+  "America/Chicago",
+  "America/New_York",
+  "America/Sao_Paulo",
+  "Pacific/Honolulu",
+  "Europe/London",
+  "Europe/Paris",
+  "Africa/Casablanca",
+  "Africa/Tunis",
+  "Africa/Cairo",
+  "Africa/Nairobi",
+  "Asia/Riyadh",
+  "Asia/Dubai",
+  "Asia/Kolkata",
+  "Asia/Bangkok",
+  "Asia/Shanghai",
+  "Asia/Tokyo",
+  "Australia/Sydney",
+  "Pacific/Auckland"
+];
+var NAJM_DEFAULT_TIME_ZONE = "UTC";
+
+export { NAJM_DEFAULT_TIME_ZONE, NAJM_TIME_ZONES };

package/dist/{design-config-D_x1GCu3.d.ts → design-config-CL9vqqQ9.d.ts}

@@ -1,4 +1,4 @@
-import { a as NajmDesignConfig, d as NajmVariantStyle } from './design-types-Rkpt8Pg1.js';
+import { N as NajmDesignConfig, a as NajmVariantStyle } from './design-types-DffH_9XC.js';
 
 /** Keeps authored TypeScript design objects type-checked without changing them. */
 declare function defineNajmDesignConfig(config: NajmDesignConfig): NajmDesignConfig;

package/dist/{design-types-Rkpt8Pg1.d.ts → design-types-DffH_9XC.d.ts}

@@ -156,4 +156,4 @@ declare const NAJM_COMPONENT_NAMES: readonly NajmComponentName[];
 declare const RADIUS_VALUE_MAP: Record<string, string>;
 declare function resolveRadiusValue(radius: NajmComponentRadius | undefined): string | undefined;
 
-export { type NajmComponentThemeConfig as N, RADIUS_VALUE_MAP as R, type NajmDesignConfig as a, type NajmLayoutConfig as b, type NajmTypographyConfig as c, type NajmVariantStyle as d, type NajmMode as e, type NajmThemeProviderProps as f, type NajmAppearance as g, type NajmThemeConfig as h, type NajmAccent as i, type NajmThemeTokens as j, type NajmPreset as k, type NajmComponentName as l, type NajmComponentStyleConfig as m, type NajmResponsiveBreakpoint as n, type NajmResponsiveValue as o, NAJM_COMPONENT_NAMES as p, type NajmComponentRadius as q, type NajmDensity as r, type NajmSlotStyle as s, resolveRadiusValue as t };
+export { type NajmDesignConfig as N, RADIUS_VALUE_MAP as R, type NajmVariantStyle as a, type NajmMode as b, type NajmComponentThemeConfig as c, type NajmLayoutConfig as d, type NajmTypographyConfig as e, type NajmThemeProviderProps as f, type NajmAppearance as g, type NajmThemeConfig as h, type NajmAccent as i, type NajmThemeTokens as j, type NajmPreset as k, type NajmComponentName as l, type NajmComponentStyleConfig as m, type NajmResponsiveBreakpoint as n, type NajmResponsiveValue as o, NAJM_COMPONENT_NAMES as p, type NajmComponentRadius as q, type NajmDensity as r, type NajmSlotStyle as s, resolveRadiusValue as t };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as React$1 from 'react';
 import React__default, { RefObject, ReactNode, ComponentType, InputHTMLAttributes, Ref, ImgHTMLAttributes, CSSProperties, MouseEvent, MouseEventHandler } from 'react';
-import { a as NajmDesignConfig, f as NajmThemeProviderProps, g as NajmAppearance, e as NajmMode, h as NajmThemeConfig, i as NajmAccent, j as NajmThemeTokens, k as NajmPreset, l as NajmComponentName, m as NajmComponentStyleConfig, N as NajmComponentThemeConfig, c as NajmTypographyConfig, b as NajmLayoutConfig, n as NajmResponsiveBreakpoint, o as NajmResponsiveValue } from './design-types-Rkpt8Pg1.js';
-export { p as NAJM_COMPONENT_NAMES, q as NajmComponentRadius, r as NajmDensity, s as NajmSlotStyle, d as NajmVariantStyle, R as RADIUS_VALUE_MAP, t as resolveRadiusValue } from './design-types-Rkpt8Pg1.js';
-import { d as NTableToolbarLabels, e as NIconSource, B as BadgeColor, f as BadgeShape } from './NajmUIProvider-DTyRrukg.js';
-export { g as Badge, h as BadgeIcon, i as BadgeLook, j as BadgeProps, k as BadgeSize, l as BadgeVariant, D as DEFAULT_FEEDBACK_KEY_PREFIX, m as DEFAULT_TIME_ZONE, F as FeedbackKey, n as NBadge, o as NBadgeDefaults, p as NBadgeLook, q as NBadgeProps, N as NFeedbackDefaults, a as NFeedbackLabelKeys, b as NFeedbackLabels, r as NIcon, s as NIconProps, t as NTableDefaults, u as NTableDefaultsProvider, v as NajmPreferencesContextValue, w as NajmPreferencesProvider, x as NajmPreferencesProviderProps, y as NajmUIProvider, c as NajmUIProviderProps, z as badgeColorVariants, A as badgeVariants, C as useDocumentDirection, E as useNTableDefaults, G as useNajmPreferencesContext, H as useNajmTheme, I as useNajmTimeZone, J as useResolvedToolbarLabels } from './NajmUIProvider-DTyRrukg.js';
+import { N as NajmDesignConfig, f as NajmThemeProviderProps, g as NajmAppearance, b as NajmMode, h as NajmThemeConfig, i as NajmAccent, j as NajmThemeTokens, k as NajmPreset, l as NajmComponentName, m as NajmComponentStyleConfig, c as NajmComponentThemeConfig, e as NajmTypographyConfig, d as NajmLayoutConfig, n as NajmResponsiveBreakpoint, o as NajmResponsiveValue } from './design-types-DffH_9XC.js';
+export { p as NAJM_COMPONENT_NAMES, q as NajmComponentRadius, r as NajmDensity, s as NajmSlotStyle, a as NajmVariantStyle, R as RADIUS_VALUE_MAP, t as resolveRadiusValue } from './design-types-DffH_9XC.js';
+import { d as NTableToolbarLabels, e as NIconSource, B as BadgeColor, f as BadgeShape } from './NajmUIProvider-BwL5HFIV.js';
+export { g as Badge, h as BadgeIcon, i as BadgeLook, j as BadgeProps, k as BadgeSize, l as BadgeVariant, D as DEFAULT_FEEDBACK_KEY_PREFIX, m as DEFAULT_TIME_ZONE, F as FeedbackKey, n as NBadge, o as NBadgeDefaults, p as NBadgeLook, q as NBadgeProps, N as NFeedbackDefaults, a as NFeedbackLabelKeys, b as NFeedbackLabels, r as NIcon, s as NIconProps, t as NTableDefaults, u as NTableDefaultsProvider, v as NajmPreferencesContextValue, w as NajmPreferencesProvider, x as NajmPreferencesProviderProps, y as NajmUIProvider, c as NajmUIProviderProps, z as badgeColorVariants, A as badgeVariants, C as useDocumentDirection, E as useNTableDefaults, G as useNajmPreferencesContext, H as useNajmTheme, I as useNajmTimeZone, J as useResolvedToolbarLabels } from './NajmUIProvider-BwL5HFIV.js';
 import { N as NajmTranslate, c as NTablePaginationVariant, b as NTablePaginationLabels, a as NTableCardPagination } from './paginationLabels-dZLSNxfo.js';
 export { D as DEFAULT_PAGINATION_KEY_PREFIX, d as NTableInfinitePagination, e as NTableLoadMorePagination, f as buildPaginationLabels } from './paginationLabels-dZLSNxfo.js';
-export { d as defineNajmDesignConfig, p as parseNajmDesignConfig, r as resolveVariantAlias, s as stringifyNajmDesignConfig } from './design-config-D_x1GCu3.js';
+export { d as defineNajmDesignConfig, p as parseNajmDesignConfig, r as resolveVariantAlias, s as stringifyNajmDesignConfig } from './design-config-CL9vqqQ9.js';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as LabelPrimitive from '@radix-ui/react-label';

package/dist/index.mjs

@@ -15,6 +15,7 @@ import './chunk-F5KXJCCJ.mjs';
 import { humanizeToken } from './chunk-JABLSOQN.mjs';
 export { DEFAULT_PLACEHOLDER, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, formatRelativeTime, formatTime, humanizeToken, localDateInput, slugify } from './chunk-JABLSOQN.mjs';
 export { DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, cleanQuery, createOffsetPagination, fetchOffsetPage, getPageIndex } from './chunk-2NX2VKS2.mjs';
+import { NAJM_TIME_ZONES } from './chunk-XGIYOEWD.mjs';
 import { resolveRadiusValue, resolveVariantAlias, parseNajmDesignConfig } from './chunk-TFHWLE7N.mjs';
 export { NAJM_COMPONENT_NAMES, RADIUS_VALUE_MAP, defineNajmDesignConfig, defineNajmThemeConfig, parseNajmDesignConfig, parseNajmThemeConfig, resolveRadiusValue, resolveVariantAlias, stringifyNajmDesignConfig, stringifyNajmThemeConfig } from './chunk-TFHWLE7N.mjs';
 import * as React66 from 'react';
@@ -28,7 +29,7 @@ import { HexColorPicker } from 'react-colorful';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 import { converter, parse, formatHsl, formatRgb, formatHex } from 'culori';
 import * as CollapsiblePrimitive from '@radix-ui/react-collapsible';
-import { Command as Command$1 } from 'cmdk';
+import { Command as Command$1, defaultFilter } from 'cmdk';
 import * as SheetPrimitive from '@radix-ui/react-dialog';
 import { create } from 'zustand';
 import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
@@ -4563,21 +4564,39 @@ var ComboboxInput = ({ placeholder = "Select...", searchPlaceholder = "Search...
   const displayLabel = selectedItem?.label ?? (allowFreeText && value ? value : "");
   const shouldDisplayIcon = Boolean(icon) && showIcon && !value;
   const iconProps = getIconColorProps(iconColor, "h-4 w-4");
+  const [activeItem, setActiveItem] = useState(selectedItem?.label ?? normalizedItems[0]?.label ?? "");
   const trimmedQuery = query.trim();
   const queryMatchesItem = trimmedQuery !== "" && normalizedItems.some((i) => i.value === trimmedQuery || i.label.toLowerCase() === trimmedQuery.toLowerCase());
   const showFreeTextOption = allowFreeText && trimmedQuery !== "" && !queryMatchesItem;
+  const rankItems = (search) => normalizedItems.map((item, index) => ({
+    index,
+    item,
+    score: shouldFilter ? defaultFilter(item.label, search.trim(), [item.value, item.label]) : 1
+  })).filter(({ score }) => score > 0).sort((left, right) => right.score - left.score || left.index - right.index);
   const commit = (next) => {
     onChange(next);
+    setActiveItem(normalizedItems.find((item) => item.value === next)?.label ?? "");
     setOpen(false);
     setQuery("");
     onSearchChange?.("");
   };
   const updateQuery = (next) => {
+    setActiveItem(rankItems(next)[0]?.item.label ?? "");
     setQuery(next);
     onSearchChange?.(next);
   };
+  const updateActiveItem = (next) => {
+    const nextItem = normalizedItems.find((item) => item.label === next);
+    if (trimmedQuery !== "" && shouldFilter && (!nextItem || defaultFilter(nextItem.label, trimmedQuery, [nextItem.value, nextItem.label]) <= 0)) {
+      return;
+    }
+    setActiveItem(next);
+  };
   return /* @__PURE__ */ jsxs(Popover, { open, onOpenChange: (o) => {
     setOpen(o);
+    if (o) {
+      setActiveItem(selectedItem?.label ?? normalizedItems[0]?.label ?? "");
+    }
     if (!o) {
       setQuery("");
       onSearchChange?.("");
@@ -4595,6 +4614,11 @@ var ComboboxInput = ({ placeholder = "Select...", searchPlaceholder = "Search...
         "aria-label": ariaLabel,
         tabIndex: disabled ? -1 : 0,
         "aria-expanded": open,
+        onKeyDown: (event) => {
+          if (disabled || event.key !== "Enter" && event.key !== " ") return;
+          event.preventDefault();
+          setOpen(true);
+        },
         className: cn(
           "cursor-pointer outline-none data-[state=open]:border-ring",
           className
@@ -4620,38 +4644,69 @@ var ComboboxInput = ({ placeholder = "Select...", searchPlaceholder = "Search...
           pointerDismissedRef.current = false;
           triggerRef.current?.blur();
         },
-        children: /* @__PURE__ */ jsxs(Command, { shouldFilter, children: [
-          /* @__PURE__ */ jsx(
-            CommandInput,
-            {
-              placeholder: searchPlaceholder,
-              className: "h-9",
-              value: query,
-              onValueChange: updateQuery,
-              onKeyDown: (e) => {
-                if (e.key === "Enter" && showFreeTextOption) {
-                  e.preventDefault();
-                  commit(trimmedQuery);
+        children: /* @__PURE__ */ jsxs(
+          Command,
+          {
+            shouldFilter,
+            value: activeItem,
+            onValueChange: updateActiveItem,
+            children: [
+              /* @__PURE__ */ jsx(
+                CommandInput,
+                {
+                  placeholder: searchPlaceholder,
+                  className: "h-9",
+                  value: query,
+                  onValueChange: updateQuery,
+                  onKeyDown: (e) => {
+                    const rankedItems = rankItems(trimmedQuery);
+                    if (trimmedQuery !== "" && rankedItems.length > 0 && ["ArrowDown", "ArrowUp", "Home", "End"].includes(e.key)) {
+                      e.preventDefault();
+                      e.stopPropagation();
+                      const currentIndex = rankedItems.findIndex(({ item }) => item.label === activeItem);
+                      const nextIndex = e.key === "Home" ? 0 : e.key === "End" ? rankedItems.length - 1 : e.key === "ArrowDown" ? Math.min(currentIndex + 1, rankedItems.length - 1) : Math.max(currentIndex < 0 ? 0 : currentIndex - 1, 0);
+                      setActiveItem(rankedItems[nextIndex]?.item.label ?? "");
+                      return;
+                    }
+                    if (e.key !== "Enter") return;
+                    if (showFreeTextOption) {
+                      e.preventDefault();
+                      commit(trimmedQuery);
+                      return;
+                    }
+                    if (trimmedQuery !== "") {
+                      const activeMatch = normalizedItems.find((item) => item.label === activeItem);
+                      const nextItem = activeMatch && defaultFilter(
+                        activeMatch.label,
+                        trimmedQuery,
+                        [activeMatch.value, activeMatch.label]
+                      ) > 0 ? activeMatch : rankedItems[0]?.item;
+                      if (nextItem) {
+                        e.preventDefault();
+                        commit(nextItem.value);
+                      }
+                    }
+                  }
                 }
-              }
-            }
-          ),
-          /* @__PURE__ */ jsxs(CommandList, { children: [
-            /* @__PURE__ */ jsx(CommandEmpty, { children: loading ? loadingMessage : emptyMessage }),
-            /* @__PURE__ */ jsxs(CommandGroup, { children: [
-              showFreeTextOption && /* @__PURE__ */ jsxs(CommandItem, { value: trimmedQuery, onSelect: () => commit(trimmedQuery), className: "cursor-pointer", children: [
-                /* @__PURE__ */ jsx(Check, { className: "mr-2 h-4 w-4 opacity-0" }),
-                'Use "',
-                trimmedQuery,
-                '"'
-              ] }, "__free_text__"),
-              normalizedItems.map((item) => /* @__PURE__ */ jsxs(CommandItem, { value: item.label, keywords: [item.value, item.label], onSelect: () => commit(value === item.value ? "" : item.value), className: "cursor-pointer", children: [
-                /* @__PURE__ */ jsx(Check, { className: cn("mr-2 h-4 w-4", value === item.value ? "opacity-100" : "opacity-0") }),
-                item.label
-              ] }, item.value))
-            ] })
-          ] })
-        ] })
+              ),
+              /* @__PURE__ */ jsxs(CommandList, { children: [
+                /* @__PURE__ */ jsx(CommandEmpty, { children: loading ? loadingMessage : emptyMessage }),
+                /* @__PURE__ */ jsxs(CommandGroup, { children: [
+                  showFreeTextOption && /* @__PURE__ */ jsxs(CommandItem, { value: trimmedQuery, onSelect: () => commit(trimmedQuery), className: "cursor-pointer", children: [
+                    /* @__PURE__ */ jsx(Check, { className: "mr-2 h-4 w-4 opacity-0" }),
+                    'Use "',
+                    trimmedQuery,
+                    '"'
+                  ] }, "__free_text__"),
+                  normalizedItems.map((item) => /* @__PURE__ */ jsxs(CommandItem, { value: item.label, keywords: [item.value, item.label], onSelect: () => commit(value === item.value ? "" : item.value), className: "cursor-pointer", children: [
+                    /* @__PURE__ */ jsx(Check, { className: cn("mr-2 h-4 w-4", value === item.value ? "opacity-100" : "opacity-0") }),
+                    item.label
+                  ] }, item.value))
+                ] })
+              ] })
+            ]
+          }
+        )
       }
     )
   ] });
@@ -6206,30 +6261,6 @@ var TimeInput = React66__default.forwardRef(({ value = "", onChange, placeholder
   ] });
 });
 TimeInput.displayName = "TimeInput";
-var timeZoneValues = [
-  "UTC",
-  "Atlantic/Azores",
-  "America/Los_Angeles",
-  "America/Denver",
-  "America/Chicago",
-  "America/New_York",
-  "America/Sao_Paulo",
-  "Pacific/Honolulu",
-  "Europe/London",
-  "Europe/Paris",
-  "Africa/Casablanca",
-  "Africa/Tunis",
-  "Africa/Cairo",
-  "Africa/Nairobi",
-  "Asia/Riyadh",
-  "Asia/Dubai",
-  "Asia/Kolkata",
-  "Asia/Bangkok",
-  "Asia/Shanghai",
-  "Asia/Tokyo",
-  "Australia/Sydney",
-  "Pacific/Auckland"
-];
 var timeZoneFormatter = new Intl.DateTimeFormat("en-US", {
   timeZone: "UTC",
   timeZoneName: "longOffset"
@@ -6241,7 +6272,7 @@ function getTimeZoneLabel(timeZone) {
   }).formatToParts(/* @__PURE__ */ new Date()).find((part) => part.type === "timeZoneName")?.value ?? "GMT";
   return `${timeZone} (${offset})`;
 }
-var timeZones = timeZoneValues.map((value) => ({
+var timeZones = NAJM_TIME_ZONES.map((value) => ({
   value,
   label: getTimeZoneLabel(value)
 }));

package/dist/server/index.d.ts

@@ -1,3 +1,160 @@
-export { U as UiBootstrapConfig, a as UiBootstrapDiagnostic, b as UiBootstrapFailureReason, c as UiBootstrapFetcher, d as UiBootstrapLoader, e as UiBootstrapResource, f as UiBootstrapResources, g as UiBootstrapSnapshot, h as UiBootstrapValue, i as createUiBootstrapLoader } from '../uiBootstrap-Ci6K5j5t.js';
-export { d as defineNajmDesignConfig, p as parseNajmDesignConfig, s as stringifyNajmDesignConfig } from '../design-config-D_x1GCu3.js';
-export { N as NajmComponentThemeConfig, a as NajmDesignConfig, b as NajmLayoutConfig, c as NajmTypographyConfig } from '../design-types-Rkpt8Pg1.js';
+export { b as UiBootstrapConfig, c as UiBootstrapDiagnostic, d as UiBootstrapFailureReason, e as UiBootstrapFetcher, h as UiBootstrapLoader, f as UiBootstrapResource, U as UiBootstrapResources, a as UiBootstrapSnapshot, g as UiBootstrapValue, i as createUiBootstrapLoader } from '../uiBootstrap-C66AFCo_.js';
+import { b as NajmMode } from '../design-types-DffH_9XC.js';
+export { c as NajmComponentThemeConfig, N as NajmDesignConfig, d as NajmLayoutConfig, e as NajmTypographyConfig } from '../design-types-DffH_9XC.js';
+export { d as defineNajmDesignConfig, p as parseNajmDesignConfig, s as stringifyNajmDesignConfig } from '../design-config-CL9vqqQ9.js';
+
+/**
+ * IANA zone identifiers offered by `TimeZoneInput` and accepted by the default
+ * preference handlers.
+ *
+ * Broad enough to cover the regions Najm applications ship to, deliberately
+ * not the full IANA database — a 400-entry combobox is not a usable control,
+ * and every entry here is a value the server contract must keep accepting.
+ * Each one is verified against `Intl.DateTimeFormat` in the package tests, so
+ * a typo cannot be published.
+ */
+declare const NAJM_TIME_ZONES: readonly ["UTC", "Atlantic/Azores", "America/Los_Angeles", "America/Denver", "America/Chicago", "America/New_York", "America/Sao_Paulo", "Pacific/Honolulu", "Europe/London", "Europe/Paris", "Africa/Casablanca", "Africa/Tunis", "Africa/Cairo", "Africa/Nairobi", "Asia/Riyadh", "Asia/Dubai", "Asia/Kolkata", "Asia/Bangkok", "Asia/Shanghai", "Asia/Tokyo", "Australia/Sydney", "Pacific/Auckland"];
+/** One of the canonical zones. Applications with a custom list infer their own. */
+type NajmTimeZone = (typeof NAJM_TIME_ZONES)[number];
+/** The zone assumed when an application configures none. */
+declare const NAJM_DEFAULT_TIME_ZONE: NajmTimeZone;
+
+/**
+ * The part of an i18n definition this contract needs.
+ *
+ * Structural on purpose: `najm-i18n` is an *optional* peer of this package, and
+ * a preference handler must not be the reason a consumer has to install it. A
+ * `najm-i18n` definition satisfies this shape as it is.
+ */
+interface NajmPreferenceI18n<Language extends string = string> {
+    readonly supportedLanguages: readonly Language[];
+    readonly defaultLanguage: Language;
+    normalizeLanguage(value: unknown): Language;
+}
+/** Cookie names, one per preference. */
+interface NajmPreferenceCookieNames {
+    language: string;
+    theme: string;
+    timeZone: string;
+}
+/**
+ * Cookie attributes, applied to all three.
+ *
+ * `httpOnly` is the default because nothing in the browser reads these back —
+ * the client provider holds the value it just set, and the server reads the
+ * cookie. `secure` is left unset by default rather than `true`: these cookies
+ * must survive `http://localhost`, and a deployment terminating TLS at the
+ * edge sees no difference. Applications serving only HTTPS should set it.
+ */
+interface NajmPreferenceCookieOptions {
+    httpOnly: boolean;
+    maxAge: number;
+    path: string;
+    sameSite: "lax" | "strict" | "none";
+    secure?: boolean;
+    domain?: string;
+}
+/**
+ * Anything shaped like Next's cookie store.
+ *
+ * Structural rather than an import: this file must stay free of `next`, and a
+ * test can pass `{ get: (name) => ... }` without building a request.
+ */
+interface NajmCookieReader {
+    get(name: string): {
+        value: string;
+    } | undefined;
+}
+interface NajmPreferenceSnapshot<Language extends string = string, TimeZone extends string = NajmTimeZone> {
+    language: Language;
+    theme: NajmMode;
+    timeZone: TimeZone;
+}
+interface NajmPreferenceResolveOptions {
+    /**
+     * Used only when the language cookie is absent or holds an unsupported
+     * value — a signed-in user's stored language, typically. Never overrides a
+     * valid cookie: the cookie is what the user last chose in this browser.
+     */
+    languageFallback?: unknown;
+}
+/** A route handler, ready to `export const POST = ...`. */
+type NajmPreferenceHandler = (request: Request) => Promise<Response>;
+interface NajmPreferenceHandlers {
+    /** Reads `{ language }`. */
+    language: NajmPreferenceHandler;
+    /** Reads `{ theme }`. */
+    theme: NajmPreferenceHandler;
+    /** Reads `{ timeZone }`. */
+    timeZone: NajmPreferenceHandler;
+}
+interface NajmPreferencesConfig<Language extends string = string, TimeZone extends string = NajmTimeZone> {
+    /** The application's catalog definition. The one required field. */
+    i18n: NajmPreferenceI18n<Language>;
+    /**
+     * Zones this application accepts. Defaults to the canonical list that
+     * `TimeZoneInput` offers.
+     *
+     * Pass this *only* alongside a matching `items` on the input. Two lists that
+     * disagree is the bug the shared default exists to prevent.
+     */
+    timeZones?: readonly TimeZone[];
+    /**
+     * Defaults to `UTC`, or to the first configured zone if `UTC` is not in it.
+     *
+     * `NoInfer` so this field cannot narrow `TimeZone`. Without it, an
+     * application that names `Africa/Casablanca` and takes the canonical list
+     * gets a definition typed as accepting *only* Casablanca — the opposite of
+     * what it configured, and a type error at every other zone downstream.
+     */
+    defaultTimeZone?: NoInfer<TimeZone>;
+    /** Defaults to `light`. */
+    defaultTheme?: NajmMode;
+    /** Merged over the `najm-ui-*` defaults, per key. */
+    cookieNames?: Partial<NajmPreferenceCookieNames>;
+    /** Merged over the secure defaults, per key. */
+    cookieOptions?: Partial<NajmPreferenceCookieOptions>;
+    /** Body field names, if this application's client posts something else. */
+    fields?: Partial<Record<"language" | "theme" | "timeZone", string>>;
+    /** Rejection messages, per preference. The defaults are generic and safe. */
+    messages?: Partial<Record<"language" | "theme" | "timeZone", string>>;
+}
+interface NajmPreferences<Language extends string = string, TimeZone extends string = NajmTimeZone> {
+    readonly cookieNames: Readonly<NajmPreferenceCookieNames>;
+    readonly cookieOptions: Readonly<NajmPreferenceCookieOptions>;
+    readonly timeZones: readonly TimeZone[];
+    readonly defaultTimeZone: TimeZone;
+    readonly defaultTheme: NajmMode;
+    readonly defaultLanguage: Language;
+    /** Every preference for this request, resolved from cookies. */
+    resolve(cookies: NajmCookieReader, options?: NajmPreferenceResolveOptions): NajmPreferenceSnapshot<Language, TimeZone>;
+    handlers: NajmPreferenceHandlers;
+}
+/** The language of a configured definition, so applications alias nothing. */
+type NajmPreferenceLanguage<P> = P extends NajmPreferences<infer Language, string> ? Language : never;
+/** The time zone of a configured definition. */
+type NajmPreferenceTimeZone<P> = P extends NajmPreferences<string, infer TimeZone> ? TimeZone : never;
+/**
+ * Configures the preference contract for one application.
+ *
+ * @example Zero configuration beyond the catalog
+ * ```ts
+ * export const preferences = defineNajmPreferences({ i18n: appI18n });
+ * ```
+ *
+ * @example An application with published cookie names to keep
+ * ```ts
+ * export const preferences = defineNajmPreferences({
+ *   i18n: appI18n,
+ *   defaultTimeZone: "Africa/Casablanca",
+ *   cookieNames: {
+ *     language: "app-ui-language",
+ *     theme: "app-ui-theme",
+ *     timeZone: "app-ui-timezone",
+ *   },
+ * });
+ * ```
+ */
+declare function defineNajmPreferences<Language extends string, const TimeZone extends string = NajmTimeZone>(config: NajmPreferencesConfig<Language, TimeZone>): NajmPreferences<Language, TimeZone>;
+
+export { NAJM_DEFAULT_TIME_ZONE, NAJM_TIME_ZONES, type NajmCookieReader, NajmMode, type NajmPreferenceCookieNames, type NajmPreferenceCookieOptions, type NajmPreferenceHandler, type NajmPreferenceHandlers, type NajmPreferenceI18n, type NajmPreferenceLanguage, type NajmPreferenceResolveOptions, type NajmPreferenceSnapshot, type NajmPreferenceTimeZone, type NajmPreferences, type NajmPreferencesConfig, type NajmTimeZone, defineNajmPreferences };

package/dist/server/index.mjs

@@ -1,2 +1,131 @@
 export { createUiBootstrapLoader } from '../chunk-7H6NFBQT.mjs';
+import { NAJM_TIME_ZONES, NAJM_DEFAULT_TIME_ZONE } from '../chunk-XGIYOEWD.mjs';
+export { NAJM_DEFAULT_TIME_ZONE, NAJM_TIME_ZONES } from '../chunk-XGIYOEWD.mjs';
 export { defineNajmDesignConfig, parseNajmDesignConfig, stringifyNajmDesignConfig } from '../chunk-TFHWLE7N.mjs';
+
+// src/server/preferences.ts
+var THEME_MODES = ["light", "dark"];
+var DEFAULT_THEME = "light";
+var ONE_YEAR_IN_SECONDS = 60 * 60 * 24 * 365;
+var DEFAULT_COOKIE_NAMES = {
+  language: "najm-ui-language",
+  theme: "najm-ui-theme",
+  timeZone: "najm-ui-timezone"
+};
+var DEFAULT_COOKIE_OPTIONS = {
+  httpOnly: true,
+  maxAge: ONE_YEAR_IN_SECONDS,
+  path: "/",
+  sameSite: "lax"
+};
+var COOKIE_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+var COOKIE_VALUE_PATTERN = /^[A-Za-z0-9!#$%&'()*+\-./:<=>?@[\]^_`|~]*$/;
+function serializeCookie(name, value, options) {
+  if (!COOKIE_NAME_PATTERN.test(name) || !COOKIE_VALUE_PATTERN.test(value)) {
+    throw new Error("najm-kit/server: refusing to serialize an unsafe preference cookie");
+  }
+  const parts = [`${name}=${value}`, `Path=${options.path}`, `Max-Age=${options.maxAge}`];
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (options.httpOnly) parts.push("HttpOnly");
+  if (options.secure) parts.push("Secure");
+  parts.push(`SameSite=${options.sameSite[0].toUpperCase()}${options.sameSite.slice(1)}`);
+  return parts.join("; ");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+async function readField(request, field) {
+  const body = await request.json().catch(() => null);
+  return isRecord(body) ? body[field] : void 0;
+}
+function rejection(message) {
+  return Response.json({ message }, { status: 400 });
+}
+function accepted(field, value, cookie) {
+  return Response.json({ [field]: value }, { headers: { "Set-Cookie": cookie } });
+}
+function defineNajmPreferences(config) {
+  const { i18n } = config;
+  const timeZones = Object.freeze([
+    ...config.timeZones ?? NAJM_TIME_ZONES
+  ]);
+  if (timeZones.length === 0) {
+    throw new Error("najm-kit/server: `timeZones` must list at least one zone");
+  }
+  const timeZoneSet = new Set(timeZones);
+  const fallbackTimeZone = timeZoneSet.has(NAJM_DEFAULT_TIME_ZONE) ? NAJM_DEFAULT_TIME_ZONE : timeZones[0];
+  const defaultTimeZone = config.defaultTimeZone ?? fallbackTimeZone;
+  if (!timeZoneSet.has(defaultTimeZone)) {
+    throw new Error(
+      `najm-kit/server: default time zone "${defaultTimeZone}" is not one of the configured zones`
+    );
+  }
+  const defaultTheme = config.defaultTheme ?? DEFAULT_THEME;
+  if (!THEME_MODES.includes(defaultTheme)) {
+    throw new Error(`najm-kit/server: default theme "${defaultTheme}" is not a supported mode`);
+  }
+  const cookieNames = Object.freeze({ ...DEFAULT_COOKIE_NAMES, ...config.cookieNames });
+  const cookieOptions = Object.freeze({ ...DEFAULT_COOKIE_OPTIONS, ...config.cookieOptions });
+  const fields = {
+    language: config.fields?.language ?? "language",
+    theme: config.fields?.theme ?? "theme",
+    timeZone: config.fields?.timeZone ?? "timeZone"
+  };
+  const messages = {
+    language: config.messages?.language ?? "Unsupported language.",
+    theme: config.messages?.theme ?? "Unsupported theme.",
+    timeZone: config.messages?.timeZone ?? "Unsupported time zone."
+  };
+  const isTheme = (value) => typeof value === "string" && THEME_MODES.includes(value);
+  const isTimeZone = (value) => typeof value === "string" && timeZoneSet.has(value);
+  const isLanguage = (value) => typeof value === "string" && i18n.supportedLanguages.includes(value);
+  function resolve(cookies, options = {}) {
+    const languageCookie = cookies.get(cookieNames.language)?.value;
+    const language = isLanguage(languageCookie) ? languageCookie : i18n.normalizeLanguage(options.languageFallback);
+    const themeCookie = cookies.get(cookieNames.theme)?.value;
+    const timeZoneCookie = cookies.get(cookieNames.timeZone)?.value;
+    return {
+      language,
+      theme: isTheme(themeCookie) ? themeCookie : defaultTheme,
+      timeZone: isTimeZone(timeZoneCookie) ? timeZoneCookie : defaultTimeZone
+    };
+  }
+  const handlers = {
+    async language(request) {
+      const value = await readField(request, fields.language);
+      if (!isLanguage(value)) return rejection(messages.language);
+      const language = i18n.normalizeLanguage(value);
+      return accepted(
+        fields.language,
+        language,
+        serializeCookie(cookieNames.language, language, cookieOptions)
+      );
+    },
+    async theme(request) {
+      const value = await readField(request, fields.theme);
+      if (!isTheme(value)) return rejection(messages.theme);
+      return accepted(fields.theme, value, serializeCookie(cookieNames.theme, value, cookieOptions));
+    },
+    async timeZone(request) {
+      const value = await readField(request, fields.timeZone);
+      if (!isTimeZone(value)) return rejection(messages.timeZone);
+      return accepted(
+        fields.timeZone,
+        value,
+        serializeCookie(cookieNames.timeZone, value, cookieOptions)
+      );
+    }
+  };
+  return Object.freeze({
+    cookieNames,
+    cookieOptions,
+    timeZones,
+    defaultTimeZone,
+    defaultTheme,
+    defaultLanguage: i18n.defaultLanguage,
+    resolve,
+    handlers: Object.freeze(handlers)
+  });
+}
+
+export { defineNajmPreferences };

package/dist/server/react.d.ts

@@ -1,5 +1,5 @@
-import { f as UiBootstrapResources, g as UiBootstrapSnapshot, U as UiBootstrapConfig } from '../uiBootstrap-Ci6K5j5t.js';
-export { a as UiBootstrapDiagnostic, b as UiBootstrapFailureReason, c as UiBootstrapFetcher, e as UiBootstrapResource, h as UiBootstrapValue } from '../uiBootstrap-Ci6K5j5t.js';
+import { U as UiBootstrapResources, a as UiBootstrapSnapshot, b as UiBootstrapConfig } from '../uiBootstrap-C66AFCo_.js';
+export { c as UiBootstrapDiagnostic, d as UiBootstrapFailureReason, e as UiBootstrapFetcher, f as UiBootstrapResource, g as UiBootstrapValue } from '../uiBootstrap-C66AFCo_.js';
 
 interface ReactServerUiBootstrap<R extends UiBootstrapResources> {
     /** Every resource for this request, resolved once and shared. */

package/dist/theme.css

@@ -317,10 +317,10 @@ input:autofill {
   overflow-x: auto;
   scrollbar-width: none;
 }
-.najm-overlay-scroll-x::-webkit-scrollbar {
-  display: none;
-}
-
+.najm-overlay-scroll-x::-webkit-scrollbar {
+  display: none;
+}
+
 /* Responsive table actions stay discoverable on touch and tablet layouts.
    Fine-pointer desktops may keep the quieter hover/focus reveal treatment. */
 .ntable-card-action {
@@ -377,7 +377,7 @@ input:autofill {
   .nimage-input-compact-overlay:focus-visible {
     opacity: 1;
   }
-}
+}
 
 /* OverlayScrollbars theme used by the <NajmScroll> component — a thin,
    translucent slate bar that floats over content with no reserved space.