@djangocfg/ui-core 2.1.512 → 2.1.514

package/README.md

@@ -51,17 +51,19 @@ import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 | Group | Examples |
 |---|---|
 | `components/data/` | Avatar · Badge · Card · Table · BalancedText · Skeleton |
-| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form |
+| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form · DateField · TimeField · DateTimeField |
 | `components/feedback/` | Alert · Toast · Banner · Progress · Spinner |
 | `components/overlay/` | Dialog · Drawer · Popover · Tooltip · HoverCard · Sheet · ContextMenu · DropdownMenu |
 | `components/navigation/` | Sidebar · Tabs · Breadcrumb · Pagination · NavigationMenu · Command · Disclosure |
 | `components/layout/` | Container · Grid · Stack · Separator · ScrollArea · Sticky |
 | `components/select/` | Combobox · MultiSelect |
 | `components/effects/` | Glass · Marquee · Backdrop |
-| `components/specialized/` | Accordion · Collapsible · Toggle · Calendar · DatePicker |
+| `components/specialized/` | Accordion · Collapsible · Toggle · Calendar · DatePicker (legacy — prefer forms/DateField) |
 | `components/boundary/` | ErrorBoundary |
 
-Imports stay flat — group folders are organisational.
+Imports stay flat — group folders are organisational. Native-engine date/time
+fields (`DateField` / `TimeField` / `DateTimeField`) have their own reference in
+[`forms/datetime-field/README.md`](src/components/forms/datetime-field/README.md).
 
 ## Hooks (`/hooks`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.512",
+  "version": "2.1.514",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -128,7 +128,7 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.512",
+    "@djangocfg/i18n": "^2.1.514",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -206,8 +206,8 @@
     "@chenglou/pretext": "^0.0.8"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.512",
-    "@djangocfg/typescript-config": "^2.1.512",
+    "@djangocfg/i18n": "^2.1.514",
+    "@djangocfg/typescript-config": "^2.1.514",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/components/data/calendar/calendar.tsx

@@ -1,12 +1,19 @@
 "use client"
 
+import { enUS, ko, ru, type Locale } from 'date-fns/locale';
 import { ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
 import * as React from 'react';
 import { DayButton, DayPicker, getDefaultClassNames } from 'react-day-picker';
 
+import { useLocaleOptional } from '@djangocfg/i18n';
 import { cn } from '../../../lib/utils';
 import { Button, buttonVariants } from '../../forms/button';
 
+/** App locale code → date-fns Locale for react-day-picker (month/weekday
+ *  names). `useLocaleOptional` returns null with no I18nProvider, so the
+ *  calendar still works standalone (falls back to English). */
+const DATE_FNS_LOCALES: Record<string, Locale> = { en: enUS, ru, ko };
+
 function Calendar({
   className,
   classNames,
@@ -15,17 +22,27 @@ function Calendar({
   buttonVariant = "ghost",
   formatters,
   components,
+  locale,
   ...props
 }: React.ComponentProps<typeof DayPicker> & {
   buttonVariant?: React.ComponentProps<typeof Button>["variant"]
 }) {
   const defaultClassNames = getDefaultClassNames()
 
+  // Localize month/weekday names from the app locale. An explicit `locale` prop
+  // still wins (the caller can override), and a bare calendar with no provider
+  // falls back to English.
+  const appLocale = useLocaleOptional()
+  const resolvedLocale = locale ?? (appLocale ? DATE_FNS_LOCALES[appLocale] : undefined)
+
   return (
     <DayPicker
       showOutsideDays={showOutsideDays}
+      locale={resolvedLocale}
+      // Cell size: compact by default (fits a narrow popover); roomier on ≥sm
+      // so the desktop popover isn't cramped.
       className={cn(
-        "bg-background group/calendar p-3 [--cell-size:2rem] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
+        "bg-background group/calendar p-3 [--cell-size:1.75rem] sm:[--cell-size:2.25rem] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
         String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
         String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
         className
@@ -96,17 +113,27 @@ function Calendar({
           defaultClassNames.week_number
         ),
         day: cn(
-          "group/day relative aspect-square h-full w-full select-none p-0 text-center [&:first-child[data-selected=true]_button]:rounded-l-md [&:last-child[data-selected=true]_button]:rounded-r-md",
+          // Range end-caps use `rounded-lg` to MATCH the single-day / today
+          // radius (`rounded-lg` on the button). Previously these were
+          // `rounded-l-md`/`rounded-r-md`, which stamped a 6px radius onto just
+          // the left OR right corners of a cell — so today/selected days at a
+          // row edge came out asymmetric (sharp one side, round the other).
+          "group/day relative aspect-square h-full w-full select-none p-0 text-center [&:first-child[data-selected=true]_button]:rounded-l-lg [&:last-child[data-selected=true]_button]:rounded-r-lg",
           defaultClassNames.day
         ),
         range_start: cn(
-          "bg-accent rounded-l-md",
+          "bg-accent rounded-l-lg",
           defaultClassNames.range_start
         ),
         range_middle: cn("rounded-none", defaultClassNames.range_middle),
-        range_end: cn("bg-accent rounded-r-md", defaultClassNames.range_end),
+        range_end: cn("bg-accent rounded-r-lg", defaultClassNames.range_end),
         today: cn(
-          "bg-accent text-accent-foreground rounded-md data-[selected=true]:rounded-none",
+          // "Today" ring only when NOT the selected day — otherwise the accent
+          // panel bled out behind the primary selection and `rounded-none`
+          // squared off one cell, so a selected "today" looked lop-sided vs
+          // other selected days. When selected, the selection styles own the
+          // cell entirely (full `rounded-md`, primary fill).
+          "rounded-lg data-[selected=true]:bg-transparent data-[selected=true]:text-inherit data-[selected=false]:bg-accent data-[selected=false]:text-accent-foreground",
           defaultClassNames.today
         ),
         outside: cn(
@@ -197,7 +224,12 @@ function CalendarDayButton({
       data-range-end={modifiers.range_end}
       data-range-middle={modifiers.range_middle}
       className={cn(
-        "data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring flex aspect-square h-auto w-full min-w-[--cell-size] flex-col gap-1 font-normal leading-none data-[range-end=true]:rounded-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-1 [&>span]:text-xs [&>span]:opacity-70",
+        "data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring",
+        // Centered content + a radius that scales with the (now larger) cell so
+        // the selected day reads as a rounded square, not a hard box.
+        "flex aspect-square h-auto w-full min-w-[--cell-size] flex-col items-center justify-center gap-1 rounded-lg font-normal leading-none",
+        "data-[range-end=true]:rounded-lg data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-lg",
+        "group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-1 [&>span]:text-xs [&>span]:opacity-70",
         defaultClassNames.day,
         className
       )}

package/src/components/data/table/index.tsx

@@ -47,6 +47,9 @@ const TableHeader = React.forwardRef<
   HTMLTableSectionElement,
   React.HTMLAttributes<HTMLTableSectionElement> & { sticky?: boolean }
 >(({ className, sticky = false, ...props }, ref) => (
+  // The header band KEEPS `--border`: it divides labels from data, which is a
+  // structural edge rather than one row from the next. Frame and header are
+  // the two strong lines; everything between rows is quieter.
   // Tinted header band with a solid bottom border so the column labels
   // separate clearly from the body in both light and dark.
   // When `sticky`, the band must be fully opaque (solid `bg-muted`, not the
@@ -104,7 +107,11 @@ const TableRow = React.forwardRef<
   <tr
     ref={ref}
     className={cn(
-      "border-b border-border transition-colors hover:bg-muted/50 data-[state=selected]:bg-accent",
+      // `--divider`, not `--border`. A row separator lives INSIDE the panel, so
+      // it must read as weaker than the frame around it; both drawing
+      // `--border` made five internal lines shout as loudly as the one edge,
+      // and the table read as a grid of boxes rather than a list.
+      "border-b border-divider transition-colors hover:bg-muted/50 data-[state=selected]:bg-accent",
       className
     )}
     {...props}

package/src/components/forms/checkbox/index.tsx

@@ -14,7 +14,9 @@ const Checkbox = React.forwardRef<
   <CheckboxPrimitive.Root
     ref={ref}
     className={cn(
-      "peer h-[1.125rem] w-[1.125rem] shrink-0 rounded-[4px] border border-input bg-background shadow-none",
+      // `select-none`: the box itself is a click target, and a drag that starts
+      // on it must not paint a text selection across the row it lives in.
+      "peer h-[1.125rem] w-[1.125rem] shrink-0 select-none rounded-[4px] border border-input bg-background shadow-none",
       "transition-colors duration-150",
       "focus-visible:border-ring focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
       "disabled:cursor-not-allowed disabled:opacity-40",

package/src/components/forms/datetime-field/README.md

@@ -0,0 +1,80 @@
+# Date/time fields
+
+`DateField` · `TimeField` · `DateTimeField` — native-engine, token-skinned
+date/time inputs.
+
+The browser's `<input type="date|time|datetime-local">` **is** the input engine:
+segmented keyboard entry, locale-aware order, 12/24-hour by locale, arrow
+increment, and the OS wheel on touch — all for free. This layer adds the
+token-styled box, a leading icon, and (for date fields) a calendar popover for
+mouse users. Values are ISO strings, so there's no timezone ambiguity at the
+boundary.
+
+| Component | `value` / `onChange` | Popover |
+|---|---|---|
+| `TimeField` | `"HH:mm"` (24h; `"HH:mm:ss"` when `step` < 60) | none — pure native segments |
+| `DateField` | `"YYYY-MM-DD"` | `Calendar` (mouse; touch → OS wheel) |
+| `DateTimeField` | `"YYYY-MM-DDTHH:mm"` | `Calendar` + a native `<input type="time">` |
+
+## Props
+
+**Shared:**
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` / `defaultValue` | `string` | Controlled / uncontrolled (ISO, see table). |
+| `onChange` | `(value: string) => void` | Emits the ISO string. |
+| `disabled` | `boolean` | |
+| `invalid` | `boolean` | Wires `aria-invalid` + destructive border. Usually driven by the `Field` / `Form` layer. |
+| `min` / `max` | `string` | Native bounds, same ISO shape as the value. |
+| `name` / `id` | `string` | The native input **is** the form control — no hidden-input shim. `id` lets an external `<label htmlFor>` bind to the real control. |
+| `className` | `string` | Applied to the field shell. |
+| `aria-label` | `string` | |
+
+**`TimeField` only:** `step?: number` — native `step` in seconds (`60` → HH:mm;
+smaller exposes a seconds segment; controls arrow increment).
+
+**`DateField` / `DateTimeField` only:**
+
+- `align?: 'start' | 'center' | 'end'` — popover alignment (default `'start'`,
+  which keeps it under the field's left edge; Radix auto-flips on collision).
+- `showPopover?: boolean` — default **AUTO**: shown on fine-pointer (mouse)
+  devices, hidden on coarse-pointer (touch) ones, where tapping the field opens
+  the OS date/time wheel — a better target than a mouse-first grid. Pass an
+  explicit `true` / `false` to force it. (`DateField`'s popover is the calendar;
+  `DateTimeField`'s is the calendar + a native time input.)
+
+## Behaviour notes
+
+- **AM/PM vs 24-hour is the browser's call**, from the user's OS locale. We never
+  render our own time picker, so there's nothing to force or to desync. The wire
+  value is always 24h `HH:mm`.
+- **Calendar localization**: month/weekday names come from the app locale via
+  `useLocaleOptional()` (`@djangocfg/i18n`) → date-fns locale. A bare calendar
+  with no `I18nProvider` falls back to English.
+- **Local-safe dates**: `date-time-utils.ts` parses/formats `YYYY-MM-DD`
+  manually (not via `new Date(str)` / `toISOString()`), so the calendar day never
+  shifts by timezone.
+- **Popover fit**: `collisionPadding` keeps it off the viewport/modal edge; there
+  is deliberately **no** `maxHeight` cap (that used the trigger-to-viewport gap
+  and clipped the calendar when the field sat low) — Radix's default
+  `avoidCollisions` flips the short popover above the field instead. A Popover
+  inside a Dialog can additionally be handed a `collisionBoundary` by the caller.
+- **Native chrome**: the browser's own clock/calendar glyph and spin buttons are
+  suppressed via `.native-datetime-input` in
+  `styles/css/utilities/datetime-field.css`; `.native-datetime-input--center`
+  centers a value's segments cross-engine.
+
+## Migration
+
+The old click-only `TimePicker` / `DatePicker` stay exported as back-compat
+aliases (zero consumer churn). Prefer these `*Field` components. `DateRangePicker`
+is unchanged (still the react-day-picker range grid).
+
+## Files
+
+- `native-field-shell.tsx` — the shared token-styled box (surface, focus ring,
+  icon slot, invalid/disabled).
+- `date-field.tsx` / `time-field.tsx` / `date-time-field.tsx` — the three fields.
+- `popover-chevron.tsx` — the leading `IconTrigger` + trailing `PopoverChevron`.
+- `date-time-utils.ts` — local-safe ISO ↔ `Date` helpers.

package/src/components/forms/datetime-field/date-field.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+/**
+ * DateField — native `<input type="date">` engine + our skin + optional
+ * `Calendar` popover. Type the date, or click the chevron to pick from the grid.
+ * Wire value is `YYYY-MM-DD` (native semantics, timezone-less).
+ *
+ * Replaces the click-only `DatePicker` (kept as a back-compat alias).
+ */
+
+import { CalendarIcon } from 'lucide-react';
+import * as React from 'react';
+
+import { useIsTouch } from '../../../hooks/media';
+import { Popover, PopoverContent, PopoverTrigger } from '../../overlay/popover';
+import { Calendar } from '../../data/calendar/calendar';
+import { formatDateString, parseDateString } from './date-time-utils';
+import { NativeFieldShell, NATIVE_FIELD_INPUT_CLASS } from './native-field-shell';
+import { IconTrigger, PopoverChevron } from './popover-chevron';
+
+export interface DateFieldProps {
+  /** Value as `YYYY-MM-DD`. Controlled. */
+  value?: string;
+  /** Uncontrolled initial value. */
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  disabled?: boolean;
+  /** Invalid state — usually driven by the `Field` / `Form` layer. */
+  invalid?: boolean;
+  /** Native min/max (`YYYY-MM-DD`); also bound the calendar grid. */
+  min?: string;
+  max?: string;
+  /**
+   * Show the calendar chevron + grid.
+   *
+   * Default `undefined` = AUTO: shown on fine-pointer (mouse) devices, hidden on
+   * coarse-pointer (touch) ones, which get the OS date wheel from the native
+   * input instead — a bigger, better tap target than our mouse-first grid. Pass
+   * an explicit `true`/`false` to force it.
+   */
+  showPopover?: boolean;
+  /** Form field name — the native input IS the form control. */
+  name?: string;
+  /**
+   * DOM id for the native control, so an external `<label htmlFor>` binds to
+   * the field a user actually focuses. Without it a caller replacing a bare
+   * `<input id=…>` with this component silently breaks its own label: the
+   * text still renders, but clicking it focuses nothing.
+   */
+  id?: string;
+
+  className?: string;
+  align?: 'start' | 'center' | 'end';
+  'aria-label'?: string;
+}
+
+export const DateField = React.forwardRef<HTMLInputElement, DateFieldProps>(
+  (
+    {
+      value: controlledValue,
+      defaultValue,
+      onChange,
+      disabled = false,
+      invalid = false,
+      min,
+      max,
+      showPopover,
+      name,
+      id,
+      className,
+      align = 'start',
+      'aria-label': ariaLabel,
+    },
+    ref,
+  ) => {
+    const isControlled = controlledValue !== undefined;
+    const [internal, setInternal] = React.useState(defaultValue ?? '');
+    const value = isControlled ? controlledValue : internal;
+
+    const [open, setOpen] = React.useState(false);
+
+    // AUTO popover — see the showPopover prop doc. Touch → OS date wheel.
+    const isTouch = useIsTouch();
+    const withPopover = showPopover ?? !isTouch;
+
+    const commit = React.useCallback(
+      (next: string) => {
+        if (!isControlled) setInternal(next);
+        onChange?.(next);
+      },
+      [isControlled, onChange],
+    );
+
+    const selected = parseDateString(value);
+    const fromDate = min ? parseDateString(min) : undefined;
+    const toDate = max ? parseDateString(max) : undefined;
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <NativeFieldShell
+          icon={
+            withPopover ? (
+              <PopoverTrigger asChild>
+                <IconTrigger disabled={disabled} label="Open calendar">
+                  <CalendarIcon aria-hidden />
+                </IconTrigger>
+              </PopoverTrigger>
+            ) : (
+              <CalendarIcon aria-hidden />
+            )
+          }
+          iconOpensPopover={withPopover}
+          invalid={invalid}
+          disabled={disabled}
+          className={className}
+          popoverTrigger={
+            withPopover ? (
+              <PopoverTrigger asChild>
+                <PopoverChevron disabled={disabled} label="Open calendar" />
+              </PopoverTrigger>
+            ) : null
+          }
+        >
+          <input
+            ref={ref}
+            type="date"
+            className={NATIVE_FIELD_INPUT_CLASS}
+            value={value}
+            onChange={(e) => commit(e.target.value)}
+            disabled={disabled}
+            min={min}
+            max={max}
+            name={name}
+            id={id}
+            aria-label={ariaLabel}
+            aria-invalid={invalid || undefined}
+          />
+        </NativeFieldShell>
+        {withPopover ? (
+          <PopoverContent
+            // Short popover (calendar only) → no height cap; let Radix flip it
+            // above the field when there's no room below, rather than clipping.
+            className="w-auto p-0"
+            align={align}
+            collisionPadding={12}
+          >
+            <Calendar
+              mode="single"
+              selected={selected}
+              onSelect={(date) => {
+                commit(date ? formatDateString(date) : '');
+                setOpen(false);
+              }}
+              disabled={disabled}
+              fromDate={fromDate}
+              toDate={toDate}
+              initialFocus
+            />
+          </PopoverContent>
+        ) : null}
+      </Popover>
+    );
+  },
+);
+DateField.displayName = 'DateField';

package/src/components/forms/datetime-field/date-time-field.tsx

@@ -0,0 +1,214 @@
+'use client';
+
+/**
+ * DateTimeField — the combined date+time field that ui-core was missing. Native
+ * `<input type="datetime-local">` engine + our skin; the popover pairs the
+ * `Calendar` grid with the time columns so a scheduler UI is one control, not a
+ * hand-wired DatePicker + TimePicker.
+ *
+ * Wire value is `YYYY-MM-DDTHH:mm` (native `datetime-local` semantics,
+ * timezone-less wall-clock).
+ */
+
+import { CalendarClock, Clock } from 'lucide-react';
+import * as React from 'react';
+
+import { cn } from '../../../lib/utils';
+import { useIsTouch } from '../../../hooks/media';
+import { Popover, PopoverContent, PopoverTrigger } from '../../overlay/popover';
+import { Calendar } from '../../data/calendar/calendar';
+import {
+  formatDateString,
+  joinDateTime,
+  parseDateString,
+  splitDateTime,
+} from './date-time-utils';
+import { NativeFieldShell, NATIVE_FIELD_INPUT_CLASS } from './native-field-shell';
+import { IconTrigger, PopoverChevron } from './popover-chevron';
+
+export interface DateTimeFieldProps {
+  /** Value as `YYYY-MM-DDTHH:mm`. Controlled. */
+  value?: string;
+  /** Uncontrolled initial value. */
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  disabled?: boolean;
+  /** Invalid state — usually driven by the `Field` / `Form` layer. */
+  invalid?: boolean;
+  /** Native min/max (`YYYY-MM-DDTHH:mm`). */
+  min?: string;
+  max?: string;
+  /**
+   * Show the popover chevron + combined calendar/time picker.
+   *
+   * Default `undefined` = AUTO: shown on fine-pointer (mouse) devices, hidden on
+   * coarse-pointer (touch) ones. On touch the native `datetime-local` input
+   * opens the OS date+time wheel — a better tap target than our tall combined
+   * grid, which is also the hardest of the three to fit on a small screen. Pass
+   * an explicit `true`/`false` to force it.
+   */
+  showPopover?: boolean;
+  /** Form field name — the native input IS the form control. */
+  name?: string;
+  /**
+   * DOM id for the native control, so an external `<label htmlFor>` binds to
+   * the field a user actually focuses. Without it a caller replacing a bare
+   * `<input id=…>` with this component silently breaks its own label: the
+   * text still renders, but clicking it focuses nothing.
+   */
+  id?: string;
+
+  className?: string;
+  align?: 'start' | 'center' | 'end';
+  'aria-label'?: string;
+}
+
+export const DateTimeField = React.forwardRef<HTMLInputElement, DateTimeFieldProps>(
+  (
+    {
+      value: controlledValue,
+      defaultValue,
+      onChange,
+      disabled = false,
+      invalid = false,
+      min,
+      max,
+      showPopover,
+      name,
+      id,
+      className,
+      align = 'start',
+      'aria-label': ariaLabel,
+    },
+    ref,
+  ) => {
+    const isControlled = controlledValue !== undefined;
+    const [internal, setInternal] = React.useState(defaultValue ?? '');
+    const value = isControlled ? controlledValue : internal;
+
+    const [open, setOpen] = React.useState(false);
+
+    // AUTO popover — see the showPopover prop doc. Touch → OS date+time wheel.
+    const isTouch = useIsTouch();
+    const withPopover = showPopover ?? !isTouch;
+
+    const commit = React.useCallback(
+      (next: string) => {
+        if (!isControlled) setInternal(next);
+        onChange?.(next);
+      },
+      [isControlled, onChange],
+    );
+
+    const { date, time } = splitDateTime(value);
+    const selected = parseDateString(date);
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <NativeFieldShell
+          icon={
+            withPopover ? (
+              <PopoverTrigger asChild>
+                <IconTrigger disabled={disabled} label="Open date & time picker">
+                  <CalendarClock aria-hidden />
+                </IconTrigger>
+              </PopoverTrigger>
+            ) : (
+              <CalendarClock aria-hidden />
+            )
+          }
+          iconOpensPopover={withPopover}
+          invalid={invalid}
+          disabled={disabled}
+          className={className}
+          popoverTrigger={
+            withPopover ? (
+              <PopoverTrigger asChild>
+                <PopoverChevron disabled={disabled} label="Open date & time picker" />
+              </PopoverTrigger>
+            ) : null
+          }
+        >
+          <input
+            ref={ref}
+            type="datetime-local"
+            className={NATIVE_FIELD_INPUT_CLASS}
+            value={value}
+            onChange={(e) => commit(e.target.value)}
+            disabled={disabled}
+            min={min}
+            max={max}
+            name={name}
+            id={id}
+            aria-label={ariaLabel}
+            aria-invalid={invalid || undefined}
+          />
+        </NativeFieldShell>
+        {withPopover ? (
+          // The official shadcn-2026 shape: the popover holds ONLY the calendar
+          // (date), and time is a small NATIVE `<input type="time">` beneath it.
+          // No scroll columns — those were the source of the pill/height/width
+          // churn. `align="start"` (not `align` default center) is what stops
+          // the popover sliding off the right edge on a narrow surface; Radix
+          // still auto-flips on collision. `w-auto p-0` sizes to the calendar.
+          <PopoverContent
+            // `w-auto` sizes to the calendar; `align="start"` keeps it under the
+            // left edge so it doesn't slide off-screen. NO `maxHeight` cap here:
+            // the calendar + time input is a SHORT popover, and
+            // `--radix-popover-content-available-height` is the gap from the
+            // trigger to the viewport edge — when the field sits low on screen
+            // that gap is tiny, so the cap was CLIPPING the calendar (and the
+            // time row under it). Instead we let Radix's default avoidCollisions
+            // flip the whole popover ABOVE the field when there's no room below.
+            // `collisionPadding` just keeps it off the very edge.
+            className="w-auto p-0"
+            align="start"
+            collisionPadding={12}
+          >
+            <Calendar
+              mode="single"
+              selected={selected}
+              onSelect={(picked) => {
+                // Keep the time; swap the date. Default to 00:00 on a first pick
+                // of an empty field so the result is a valid datetime.
+                const nextDate = picked ? formatDateString(picked) : '';
+                commit(joinDateTime(nextDate, time || '00:00'));
+              }}
+              disabled={disabled}
+              initialFocus
+            />
+            {/* Time row: a full, comfortable field — not a cramped chip. The
+              * label + clock icon sit left; the native time input fills the
+              * rest at the same height as the main field (h-10) so it's an easy
+              * tap/click target and reads as a real input. */}
+            <div className="flex items-center gap-2 border-t p-3">
+              <Clock className="size-4 shrink-0 text-muted-foreground" aria-hidden />
+              <span className="text-sm font-medium text-muted-foreground">Time</span>
+              <input
+                type="time"
+                aria-label="Time"
+                // Explicit width, not min-w on a flex — a native `<input>` is a
+                // replaced element and won't reliably grow to a flex min-width,
+                // which is why the earlier `min-w-[8rem]` did nothing. A fixed
+                // width + centered segments gives the value real breathing room.
+                style={{ width: '8.5rem' }}
+                className={cn(
+                  // `--center` variant centers the native segments (see
+                  // datetime-field.css); it sets its own display/justify.
+                  'native-datetime-input native-datetime-input--center ml-auto h-10 rounded-[var(--radius)]',
+                  'border border-border bg-input px-4 text-base tabular-nums text-foreground shadow-sm md:text-sm',
+                  'focus-visible:border-ring focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+                  'disabled:cursor-not-allowed disabled:opacity-50',
+                )}
+                value={time}
+                onChange={(e) => commit(joinDateTime(date, e.target.value))}
+                disabled={disabled}
+              />
+            </div>
+          </PopoverContent>
+        ) : null}
+      </Popover>
+    );
+  },
+);
+DateTimeField.displayName = 'DateTimeField';