@repraze/kernelkit 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/vite/index.js

@@ -0,0 +1,242 @@
+/// <reference types="node" />
+/**
+ * Vite plugins shared by the suite's sites (Node-side: no React, nothing here reaches the browser).
+ *
+ * ```ts
+ * import {docsMetaPlugin, faviconPlugin, spaFallback, suiteSourceConditions, themeScriptPlugin} from "@repraze/kernelkit/vite";
+ * ```
+ *
+ * `vite` is only imported for its types; `typescript` is loaded lazily by docsMetaPlugin / extractFunction.
+ */
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { copyFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { themeScript } from "../provider/theme.js";
+/**
+ * Inline the kit's pre-paint theme script into index.html, so the stored mode, contrast, accent and radius
+ * apply before first paint. Replaces the marker comment, or goes first in <head> when there is none.
+ */
+export function themeScriptPlugin({ storageKey, defaults, marker = "<!-- kernelkit:theme-script -->", prelude, }) {
+    const source = [prelude, themeScript({ storageKey, defaults })].filter(Boolean).join("\n");
+    return {
+        name: "kernelkit-theme-script",
+        transformIndexHtml: (html) => html.includes(marker)
+            ? html.replace(marker, `<script>${source}</script>`)
+            : { html, tags: [{ tag: "script", children: source, injectTo: "head-prepend" }] },
+    };
+}
+// ─── favicon ────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Serve (dev) and emit (build) `favicon.svg` from the brand mark's SVG, so the icon never drifts from the
+ * logo. Link it with `href="%BASE_URL%favicon.svg"` so it works under a Pages base path.
+ */
+export function faviconPlugin(svg, fileName = "favicon.svg") {
+    const source = typeof svg === "function" ? svg() : svg;
+    return {
+        name: "kernelkit-favicon",
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.url?.split("?")[0]?.endsWith(`/${fileName}`)) {
+                    res.setHeader("Content-Type", "image/svg+xml");
+                    res.end(source);
+                    return;
+                }
+                next();
+            });
+        },
+        generateBundle() {
+            this.emitFile({ type: "asset", fileName, source });
+        },
+    };
+}
+// ─── SPA fallback ───────────────────────────────────────────────────────────────────────────────
+/** GitHub Pages has no SPA rewrites: copy index.html to 404.html so deep links load the app. */
+export function spaFallback() {
+    return {
+        name: "kernelkit-spa-fallback",
+        apply: "build",
+        async writeBundle({ dir }) {
+            if (dir) {
+                await copyFile(join(dir, "index.html"), join(dir, "404.html"));
+            }
+        },
+    };
+}
+// ─── linked suite packages ──────────────────────────────────────────────────────────────────────
+/** Is `node_modules/<name>` a symlink (npm link, a workspace), looking up from `root`? */
+function isLinked(name, root) {
+    for (let dir = resolve(root);; dir = dirname(dir)) {
+        try {
+            return lstatSync(join(dir, "node_modules", name)).isSymbolicLink();
+        }
+        catch {
+            // not installed here: look in the parent
+        }
+        if (dirname(dir) === dir) {
+            return false;
+        }
+    }
+}
+const DEDUPE = ["react", "react-dom", "@base-ui/react", "cmdk", "lucide-react"];
+/**
+ * For each suite package (`@repraze/kernelkit`…) that is symlinked into node_modules (`npm link`, a
+ * workspace): serve it from its TypeScript sources (its `@repraze/source` exports condition), unbundled,
+ * so edits there hot-reload; dedupe React-context packages, since a linked package sits outside this tree.
+ * Installed from npm: nothing changes, its built dist is used and pre-bundled like any dependency.
+ */
+export function suiteSourceConditions(packages, options = {}) {
+    const { dedupe = DEDUPE, condition = "@repraze/source" } = options;
+    return {
+        name: "kernelkit-suite-source-conditions",
+        enforce: "pre",
+        config(config) {
+            const linked = packages.filter((name) => isLinked(name, config.root ?? process.cwd()));
+            if (!linked.length) {
+                return undefined;
+            }
+            return {
+                resolve: { conditions: [condition, ...DEFAULT_CLIENT_CONDITIONS], dedupe },
+                optimizeDeps: { exclude: linked },
+            };
+        },
+    };
+}
+/** Vite's `defaultClientConditions`, inlined so this module needs no runtime import of vite. */
+const DEFAULT_CLIENT_CONDITIONS = ["module", "browser", "development|production"];
+// ─── docs manifest and demo sources ─────────────────────────────────────────────────────────────
+const require = createRequire(import.meta.url);
+let typescript;
+/** TypeScript, loaded on first use (the sites already have it): only docs sites pay for it. */
+const ts = () => (typescript ??= require("typescript"));
+/** Static value of a string/number expression: literals, no-substitution templates, "a" + "b". */
+function literal(node) {
+    const t = ts();
+    if (t.isStringLiteral(node) || t.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    if (t.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    if (t.isParenthesizedExpression(node)) {
+        return literal(node.expression);
+    }
+    if (t.isBinaryExpression(node) && node.operatorToken.kind === t.SyntaxKind.PlusToken) {
+        const a = literal(node.left);
+        const b = literal(node.right);
+        return a !== undefined && b !== undefined ? `${a}${b}` : undefined;
+    }
+    return undefined;
+}
+/** A docs page's manifest entry, read from its `defineDoc({...})` call without running it. */
+export function readDocMeta(file, slug, source = readFileSync(file, "utf8")) {
+    const t = ts();
+    const sf = t.createSourceFile(file, source, t.ScriptTarget.Latest, true);
+    let meta;
+    const visit = (node) => {
+        if (!meta &&
+            t.isCallExpression(node) &&
+            t.isIdentifier(node.expression) &&
+            node.expression.text === "defineDoc" &&
+            node.arguments[0] &&
+            t.isObjectLiteralExpression(node.arguments[0])) {
+            const props = {};
+            for (const p of node.arguments[0].properties) {
+                if (t.isPropertyAssignment(p) && t.isIdentifier(p.name)) {
+                    props[p.name.text] = literal(p.initializer);
+                }
+            }
+            if (typeof props.title !== "string" || typeof props.category !== "string") {
+                throw new Error(`${file}: defineDoc needs literal "title" and "category" (read at build time)`);
+            }
+            meta = {
+                slug,
+                title: props.title,
+                category: props.category,
+                description: typeof props.description === "string" ? props.description : "",
+                ...(typeof props.order === "number" ? { order: props.order } : {}),
+            };
+        }
+        t.forEachChild(node, visit);
+    };
+    visit(sf);
+    if (!meta) {
+        throw new Error(`${file}: no defineDoc({...}) call found`);
+    }
+    return meta;
+}
+/** Each top-level function or const of a file, by name, as written (without `export `). */
+export function extractFunctions(source, fileName = "doc.tsx") {
+    const t = ts();
+    const sf = t.createSourceFile(fileName, source, t.ScriptTarget.Latest, true, t.ScriptKind.TSX);
+    const out = {};
+    const text = (node) => source.slice(node.getStart(sf), node.getEnd()).replace(/^export /, "");
+    for (const statement of sf.statements) {
+        if (t.isFunctionDeclaration(statement) && statement.name) {
+            out[statement.name.text] = text(statement);
+        }
+        else if (t.isVariableStatement(statement)) {
+            for (const decl of statement.declarationList.declarations) {
+                if (t.isIdentifier(decl.name)) {
+                    out[decl.name.text] = text(statement);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * A demo's own source: its declaration from `export function Name` (or `export const Name`) to its
+ * closing brace, parsed with TypeScript, so code after it (a `Notes()` helper, constants) stays out.
+ */
+export function extractFunction(source, name) {
+    return extractFunctions(source)[name] ?? "";
+}
+const META_ID = "virtual:docs-meta";
+const META_RESOLVED = `\0${META_ID}`;
+const SOURCES_QUERY = "demo-sources";
+/**
+ * The docs build step, for `@repraze/kernelkit/docs`:
+ * - `virtual:docs-meta`: title, category, description and order of every page in `docsDir`, read
+ *   statically from its `defineDoc({...})` call, so the nav and search don't pull every page's demos into
+ *   the main bundle;
+ * - `<page>.tsx?demo-sources`: `{functions}`, each demo's own source for its Code tab (see extractFunction).
+ *
+ * Types: add `@repraze/kernelkit/vite/client` to the site's tsconfig `types`.
+ */
+export function docsMetaPlugin(docsDir) {
+    const dir = resolve(docsDir);
+    return {
+        name: "kernelkit-docs-meta",
+        enforce: "pre",
+        resolveId: (id) => (id === META_ID ? META_RESOLVED : undefined),
+        load(id) {
+            if (id === META_RESOLVED) {
+                const files = readdirSync(dir).filter((f) => f.endsWith(".tsx"));
+                const metas = files.map((f) => {
+                    const file = join(dir, f);
+                    this.addWatchFile(file);
+                    return readDocMeta(file, f.replace(/\.tsx$/, ""));
+                });
+                return `export default ${JSON.stringify(metas)};`;
+            }
+            const [file = "", query = ""] = id.split("?");
+            if (query.split("&").includes(SOURCES_QUERY)) {
+                this.addWatchFile(file);
+                const functions = extractFunctions(readFileSync(file, "utf8"), file);
+                return { code: `export default ${JSON.stringify({ functions })};`, moduleType: "js" };
+            }
+            return undefined;
+        },
+        // a docs page added, removed or retitled → refresh the manifest
+        handleHotUpdate({ file, server }) {
+            if (file.startsWith(dir)) {
+                const mod = server.moduleGraph.getModuleById(META_RESOLVED);
+                if (mod) {
+                    server.moduleGraph.invalidateModule(mod);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@repraze/kernelkit",
-    "version": "0.1.0-alpha.3",
+    "version": "0.1.0-alpha.5",
     "description": "Modern, techy React components: every shadcn component on Base UI, Tailwind v4 and cva, themed by TermiColor.",
     "keywords": [
         "react",
@@ -56,7 +56,26 @@
             "types": "./dist/provider/theme.d.ts",
             "default": "./dist/provider/theme.js"
         },
+        "./docs": {
+            "@repraze/source": "./src/docs/index.ts",
+            "types": "./dist/docs/index.d.ts",
+            "default": "./dist/docs/index.js"
+        },
+        "./site": {
+            "@repraze/source": "./src/site/index.ts",
+            "types": "./dist/site/index.d.ts",
+            "default": "./dist/site/index.js"
+        },
+        "./vite": {
+            "@repraze/source": "./src/vite/index.ts",
+            "types": "./dist/vite/index.d.ts",
+            "default": "./dist/vite/index.js"
+        },
+        "./vite/client": {
+            "types": "./src/vite/client.d.ts"
+        },
         "./styles.css": "./src/styles/kernelkit.css",
+        "./site.css": "./src/styles/site.css",
         "./package.json": "./package.json"
     },
     "files": [
@@ -83,7 +102,11 @@
         "input-otp": "^1.5.0",
         "react-resizable-panels": "^4.19.1",
         "@tanstack/react-virtual": "^3.14.26",
-        "@shadcn/react": "^0.3.1"
+        "@shadcn/react": "^0.3.1",
+        "@fontsource-variable/geist": "^5.2.0",
+        "@fontsource-variable/jetbrains-mono": "^5.2.0",
+        "typescript": ">=5.0",
+        "vite": ">=7.0"
     },
     "peerDependenciesMeta": {
         "recharts": {
@@ -115,6 +138,18 @@
         },
         "@shadcn/react": {
             "optional": true
+        },
+        "@fontsource-variable/geist": {
+            "optional": true
+        },
+        "@fontsource-variable/jetbrains-mono": {
+            "optional": true
+        },
+        "typescript": {
+            "optional": true
+        },
+        "vite": {
+            "optional": true
         }
     },
     "dependencies": {
@@ -141,6 +176,7 @@
         "input-otp": "^1.5.0",
         "react-resizable-panels": "^4.19.1",
         "@tanstack/react-virtual": "^3.14.26",
-        "@shadcn/react": "^0.3.1"
+        "@shadcn/react": "^0.3.1",
+        "vite": "^8.3.6"
     }
 }

package/src/components/alert-dialog.tsx

@@ -93,7 +93,10 @@ function AlertDialogMedia({
             data-color={color}
             className={cn(
                 "mb-2 inline-flex size-10 items-center justify-center rounded-lg border border-border bg-muted sm:group-data-[size=default]/alert-dialog-content:row-span-2 *:[svg:not([class*='size-'])]:size-5",
-                color && [colorVariants[color], "border-(--c)/40 bg-(--c-tint) text-foreground *:[svg]:text-(--c)"],
+                color && [
+                    colorVariants[color],
+                    "border-(--c)/40 bg-(--c-tint) text-foreground *:[svg]:text-(--c-soft-text)",
+                ],
                 className,
             )}
             {...props}

package/src/components/alert.tsx

@@ -17,8 +17,8 @@ const alertCva = cva(
         variants: {
             color: colorVariants,
             variant: {
-                soft: [statusSurface.soft, "text-foreground *:[svg]:text-(--c)"],
-                outline: [statusSurface.outline, "text-card-foreground *:[svg]:text-(--c)"],
+                soft: [statusSurface.soft, "text-foreground *:[svg]:text-(--c-text)"],
+                outline: [statusSurface.outline, "text-card-foreground *:[svg]:text-(--c-text)"],
             },
         },
         compoundVariants: [
@@ -73,7 +73,7 @@ function AlertTitle({className, ...props}: React.ComponentProps<"div">) {
             data-slot="alert-title"
             className={cn(
                 heading,
-                "group-has-[>svg]/alert:col-start-2 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-(--c)",
+                "group-has-[>svg]/alert:col-start-2 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-(--c-text)",
                 className,
             )}
             {...props}

package/src/components/badge.tsx

@@ -25,7 +25,7 @@ const badgeCva = cva(
             color: colorVariants,
             variant: {
                 solid: "bg-(--c-fill) text-(--c-fill-fg) [a]:hover:bg-(--c-fill)/85",
-                soft: "bg-(--c)/12 text-(--c) dark:bg-(--c)/20 [a]:hover:bg-(--c)/20 dark:[a]:hover:bg-(--c)/30",
+                soft: "bg-(--c)/12 text-(--c-soft-text) dark:bg-(--c)/20 [a]:hover:bg-(--c)/20 dark:[a]:hover:bg-(--c)/30",
                 outline: "border-border text-foreground [a]:hover:bg-hover",
                 ghost: "text-foreground [a]:hover:bg-hover",
                 link: "text-(--c) underline-offset-4 hover:underline",

package/src/components/button.tsx

@@ -27,7 +27,7 @@ const buttonCva = cva(
             color: colorVariants,
             variant: {
                 solid: "bg-(--c-fill) text-(--c-fill-fg) hover:bg-(--c-fill)/85 aria-expanded:bg-(--c-fill)/85",
-                soft: "bg-(--c)/12 text-(--c) hover:bg-(--c)/20 aria-expanded:bg-(--c)/20 dark:bg-(--c)/20 dark:hover:bg-(--c)/30",
+                soft: "bg-(--c)/12 text-(--c-soft-text) hover:bg-(--c)/20 aria-expanded:bg-(--c)/20 dark:bg-(--c)/20 dark:hover:bg-(--c)/30",
                 outline: "border-input bg-transparent hover:bg-hover aria-expanded:bg-hover",
                 ghost: "text-foreground hover:bg-hover aria-expanded:bg-hover",
                 link: "text-(--c) underline-offset-4 hover:underline",

package/src/components/calendar.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import {Button, buttonVariants} from "@repraze/kernelkit/components/button";
+import {useLocale, weekStart} from "@repraze/kernelkit/components/locale";
 import {cn} from "cn";
 import {ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon} from "lucide-react";
 import * as React from "react";
@@ -13,6 +14,37 @@ import {type DayButton, DayPicker, getDefaultClassNames, type Locale} from "reac
  * - today: primary dot under the number + medium weight
  * - outside days: muted text; disabled: muted text + line-through
  */
+/** DayPicker props minus `locale`, keeping the `mode` union intact (a plain Omit would collapse it). */
+type CalendarBaseProps =
+    React.ComponentProps<typeof DayPicker> extends infer P ? (P extends unknown ? Omit<P, "locale"> : never) : never;
+
+/** DayPicker formatters from Intl: the caption, weekday names, day numbers (native digits) and dropdowns. */
+function intlFormatters(locale: string) {
+    try {
+        const caption = new Intl.DateTimeFormat(locale, {month: "long", year: "numeric"});
+        // "short" is the full name in some languages (Arabic): fall back to "narrow" when it won't fit a cell
+        const short = new Intl.DateTimeFormat(locale, {weekday: "short"});
+        const long = Array.from({length: 7}, (_, i) => short.format(new Date(2000, 0, 2 + i))).some(
+            (d) => d.length > 4,
+        );
+        const weekday = long ? new Intl.DateTimeFormat(locale, {weekday: "narrow"}) : short;
+        const day = new Intl.DateTimeFormat(locale, {day: "numeric"});
+        const month = new Intl.DateTimeFormat(locale, {month: "short"});
+        const year = new Intl.DateTimeFormat(locale, {year: "numeric"});
+        return {
+            formatCaption: (date: Date) => caption.format(date),
+            formatWeekdayName: (date: Date) => weekday.format(date),
+            // the day part only: ja formats "14日", the grid wants "14" (native digits kept: "١٤" in ar-EG)
+            formatDay: (date: Date) =>
+                day.formatToParts(date).find((p) => p.type === "day")?.value ?? String(date.getDate()),
+            formatMonthDropdown: (date: Date) => month.format(date),
+            formatYearDropdown: (date: Date) => year.format(date),
+        };
+    } catch {
+        return {};
+    }
+}
+
 function Calendar({
     className,
     classNames,
@@ -22,11 +54,20 @@ function Calendar({
     locale,
     formatters,
     components,
+    weekStartsOn,
     ...props
-}: React.ComponentProps<typeof DayPicker> & {
+}: CalendarBaseProps & {
     buttonVariant?: React.ComponentProps<typeof Button>["variant"];
+    /**
+     * A BCP 47 tag (`"fr-FR"`) or nothing: month and weekday names, digits and the first day of the week
+     * come from `Intl` (prop › LocaleProvider › browser). A date-fns `Locale` object uses date-fns instead.
+     */
+    locale?: Partial<Locale> | string;
 }) {
     const defaultClassNames = getDefaultClassNames();
+    const dateFnsLocale = typeof locale === "object" ? locale : undefined;
+    const tag = useLocale(typeof locale === "string" ? locale : undefined);
+    const intl = React.useMemo(() => (dateFnsLocale ? null : intlFormatters(tag)), [dateFnsLocale, tag]);
 
     return (
         <DayPicker
@@ -38,9 +79,12 @@ function Calendar({
                 className,
             )}
             captionLayout={captionLayout}
-            locale={locale}
+            locale={dateFnsLocale}
+            lang={dateFnsLocale ? undefined : tag}
+            weekStartsOn={weekStartsOn ?? (dateFnsLocale ? undefined : weekStart(tag))}
             formatters={{
-                formatMonthDropdown: (date) => date.toLocaleString(locale?.code, {month: "short"}),
+                formatMonthDropdown: (date) => date.toLocaleString(dateFnsLocale?.code ?? tag, {month: "short"}),
+                ...intl,
                 ...formatters,
             }}
             classNames={{
@@ -128,7 +172,7 @@ function Calendar({
 
                     return <ChevronDownIcon className={cn("size-4", className)} {...props} />;
                 },
-                DayButton: ({...props}) => <CalendarDayButton locale={locale} {...props} />,
+                DayButton: ({...props}) => <CalendarDayButton locale={dateFnsLocale} {...props} />,
                 WeekNumber: ({children, ...props}) => {
                     return (
                         <td {...props}>

package/src/components/callout.tsx

@@ -41,10 +41,10 @@ const calloutVariants = cva(
 );
 
 const calloutHeader =
-    "flex min-h-8 w-full items-center gap-1.5 py-1.5 pr-3 pl-4 text-left text-xs text-(--c) group-data-[color=neutral]/callout:text-muted-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5";
+    "flex min-h-8 w-full items-center gap-1.5 py-1.5 pr-3 pl-4 text-left text-xs text-(--c-text) group-data-[color=neutral]/callout:text-muted-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5";
 
 const calloutBody =
-    "py-2 pr-3 pl-4 text-sm leading-relaxed [&_a]:text-(--c) [&_a]:underline [&_a]:underline-offset-3 group-data-[color=neutral]/callout:[&_a]:text-foreground [&_p:not(:last-child)]:mb-2 border-(--callout-line)";
+    "py-2 pr-3 pl-4 text-sm leading-relaxed [&_a]:text-(--c-text) [&_a]:underline [&_a]:underline-offset-3 group-data-[color=neutral]/callout:[&_a]:text-foreground [&_p:not(:last-child)]:mb-2 border-(--callout-line)";
 
 interface CalloutProps extends Omit<React.ComponentProps<"div">, "color" | "title"> {
     /** Status or hue of the indicator, header and border. */

package/src/components/combobox.tsx

@@ -229,7 +229,7 @@ function ComboboxChip({
         <ComboboxPrimitive.Chip
             data-slot="combobox-chip"
             className={cn(
-                "flex h-5.5 w-fit items-center justify-center gap-1 rounded-md border border-border bg-secondary px-1.5 text-xs font-medium whitespace-nowrap text-secondary-foreground has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50 has-data-[slot=combobox-chip-remove]:pr-0 outline-none focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50",
+                "flex h-5.5 w-fit items-center justify-center gap-1 rounded-md border border-border bg-foreground/10 px-1.5 text-xs font-medium whitespace-nowrap text-foreground hc:bg-transparent has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50 has-data-[slot=combobox-chip-remove]:pr-0 outline-none focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50",
                 className,
             )}
             {...props}

package/src/components/date-picker.tsx

@@ -2,6 +2,7 @@
 
 import {Button} from "@repraze/kernelkit/components/button";
 import {Calendar} from "@repraze/kernelkit/components/calendar";
+import {useLocale} from "@repraze/kernelkit/components/locale";
 import {Popover, PopoverContent, PopoverTrigger} from "@repraze/kernelkit/components/popover";
 import {cn} from "cn";
 import {format as formatDate} from "date-fns";
@@ -14,8 +15,13 @@ type CalendarProps = React.ComponentProps<typeof Calendar>;
 interface DatePickerBaseProps {
     /** Trigger text when nothing is picked. */
     placeholder?: React.ReactNode;
-    /** date-fns format string for the trigger label. */
-    format?: string;
+    /**
+     * Trigger label: `Intl.DateTimeFormat` options (default `{dateStyle: "long"}`, `"medium"` for ranges), a
+     * function, or a date-fns pattern string.
+     */
+    format?: DateFormat;
+    /** BCP 47 tag for the label and the calendar; defaults to LocaleProvider › browser. */
+    locale?: string;
     size?: "sm" | "default" | "lg";
     disabled?: boolean;
     "aria-invalid"?: boolean;
@@ -27,6 +33,27 @@ interface DatePickerBaseProps {
     align?: "start" | "center" | "end";
 }
 
+type DateFormat = Intl.DateTimeFormatOptions | string | ((date: Date) => string);
+
+/** One date in the trigger. */
+function formatOne(date: Date, format: DateFormat, locale: string) {
+    if (typeof format === "function") {
+        return format(date);
+    }
+    if (typeof format === "string") {
+        return formatDate(date, format);
+    }
+    return new Intl.DateTimeFormat(locale, format).format(date);
+}
+
+/** A range in the trigger: Intl's formatRange shares what both ends have in common ("Nov 14 – 20, 2026"). */
+function formatRange(from: Date, to: Date, format: DateFormat, locale: string) {
+    if (typeof format === "object") {
+        return new Intl.DateTimeFormat(locale, format).formatRange(from, to);
+    }
+    return `${formatOne(from, format, locale)} – ${formatOne(to, format, locale)}`;
+}
+
 function useControllable<T>(value: T | undefined, defaultValue: T | undefined, onChange?: (value: T) => void) {
     const [inner, setInner] = React.useState(defaultValue);
     const controlled = value !== undefined;
@@ -59,7 +86,8 @@ function DatePickerTrigger({
                     variant="outline"
                     size={size}
                     className={cn(
-                        "w-60 justify-start text-left font-normal data-empty:text-muted-foreground data-popup-open:bg-hover [&>svg]:text-muted-foreground",
+                        // a field like Select's trigger, not an outline button: it sits beside inputs and TimeInput
+                        "w-60 justify-start bg-field text-start font-normal hover:bg-field-hover aria-expanded:bg-field-hover data-empty:text-muted-foreground data-popup-open:bg-field-hover [&>svg]:text-muted-foreground",
                         className,
                     )}
                     {...props}
@@ -84,7 +112,8 @@ function DatePicker({
     defaultValue = null,
     onValueChange,
     placeholder = "Pick a date",
-    format = "PPP",
+    format = {dateStyle: "long"},
+    locale: localeProp,
     calendarProps,
     align = "start",
     className,
@@ -92,17 +121,19 @@ function DatePicker({
 }: DatePickerProps) {
     const [open, setOpen] = React.useState(false);
     const [date, setDate] = useControllable<Date | null>(value, defaultValue, onValueChange);
+    const locale = useLocale(localeProp);
 
     return (
         <Popover open={open} onOpenChange={setOpen}>
             <DatePickerTrigger
-                label={date ? formatDate(date, format) : undefined}
+                label={date ? formatOne(date, format, locale) : undefined}
                 placeholder={placeholder}
                 className={className}
                 {...trigger}
             />
             <PopoverContent data-slot="date-picker-content" className="w-auto p-0" align={align}>
                 <Calendar
+                    locale={locale}
                     {...calendarProps}
                     mode="single"
                     selected={date ?? undefined}
@@ -131,7 +162,8 @@ function DateRangePicker({
     defaultValue = null,
     onValueChange,
     placeholder = "Pick a date range",
-    format = "LLL d, y",
+    format = {dateStyle: "medium"},
+    locale: localeProp,
     numberOfMonths = 2,
     calendarProps,
     align = "start",
@@ -139,10 +171,11 @@ function DateRangePicker({
     ...trigger
 }: DateRangePickerProps) {
     const [range, setRange] = useControllable<DateRange | null>(value, defaultValue, onValueChange);
+    const locale = useLocale(localeProp);
     const label = range?.from
         ? range.to
-            ? `${formatDate(range.from, format)} – ${formatDate(range.to, format)}`
-            : formatDate(range.from, format)
+            ? formatRange(range.from, range.to, format, locale)
+            : formatOne(range.from, format, locale)
         : undefined;
 
     return (
@@ -150,6 +183,7 @@ function DateRangePicker({
             <DatePickerTrigger label={label} placeholder={placeholder} className={cn("w-72", className)} {...trigger} />
             <PopoverContent data-slot="date-picker-content" className="w-auto p-0" align={align}>
                 <Calendar
+                    locale={locale}
                     {...calendarProps}
                     mode="range"
                     numberOfMonths={numberOfMonths}
@@ -163,4 +197,4 @@ function DateRangePicker({
 }
 
 export {DatePicker, DatePickerTrigger, DateRangePicker};
-export type {DatePickerProps, DateRangePickerProps};
+export type {DateFormat, DatePickerProps, DateRangePickerProps};