@eifi1/ui-kit 0.9.0 → 0.11.0

package/src/components/chip.tsx

@@ -1,6 +1,6 @@
 import { forwardRef, useId, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, KeyboardEvent, MouseEvent, ReactElement, ReactNode, Ref } from "react";
-import { X } from "lucide-react";
+import { Check, X } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
@@ -30,9 +30,22 @@ export type ChipTone =
   | "success"
   | "info"
   | "income"
-  | "expense";
-/** `lg` is the 44px touch target (`min-h-11`) a phone surface wants; `md` is ~28px. */
-export type ChipSize = "sm" | "md" | "lg";
+  | "expense"
+  | ChipHue;
+/**
+ * Categorical hues (0.10.0): colour that says "a different value" and nothing more —
+ * kastlan's status-badge.tsx paints ~15 enums in 9 Tailwind hues by hand. Four of those
+ * nine are semantic and already tones (green = `success`, yellow = `warning`, red =
+ * `danger`, gray = `neutral`); these five are the rest, each a `--hue-*` token triple
+ * in tokens.css with a light and a dark value. Use a semantic tone when the value HAS a
+ * meaning (overdue is `danger`), a hue when it only needs telling apart (sent vs
+ * accepted vs invoiced).
+ */
+export type ChipHue = "blue" | "indigo" | "purple" | "teal" | "orange";
+/** `lg` is the 44px touch target (`min-h-11`) a phone surface wants; `md` is ~28px.
+ *  `xs` (0.10.0) is 11px type at `px-1.5` — keksdose's goal markers and budget-cell
+ *  badges, which sit inside a figure's line and must not make it taller. */
+export type ChipSize = "xs" | "sm" | "md" | "lg";
 /**
  * How much of the tone the chip wears.
  *
@@ -43,8 +56,12 @@ export type ChipSize = "sm" | "md" | "lg";
  * - `solid`: the tone as a fill under contrasting text — the "count" pill (unread
  *   messages, open tasks). It centres its content and sets figures tabular, so a
  *   one-digit count is a round dot and "9" → "10" does not jiggle the row.
+ * - `dot` (0.10.0): no pill at all — a dot in the tone's colour before plain text, for
+ *   a status in a dense list or a table column where eight tinted pills in a column
+ *   would outshout the figures beside them (kastlan's unit picker already draws its
+ *   UnitStatus this way, from a separate `dotColor` map).
  */
-export type ChipVariant = "soft" | "outline" | "solid";
+export type ChipVariant = "soft" | "outline" | "solid" | "dot";
 /** `pill` (default) is fully rounded; `square` has the small radius of a field or a
  *  button — for a chip that sits in a table cell or beside square controls. */
 export type ChipShape = "pill" | "square";
@@ -86,6 +103,28 @@ const TONE: Record<ChipTone, { idle: string; selected: string }> = {
     idle: "border-current/40 bg-[var(--bg-surface-2)] text-[var(--money-expense)]",
     selected: "border-current bg-[var(--bg-active)] text-[var(--money-expense)]",
   },
+  // The categorical hues: the `info` recipe with its own token triple, so a hue chip
+  // and a status chip in one row carry the same weight.
+  blue: {
+    idle: "border-[var(--hue-blue-border)] bg-[var(--hue-blue-bg)] text-[var(--hue-blue)]",
+    selected: "border-[var(--hue-blue)] bg-[var(--hue-blue-bg)] text-[var(--hue-blue)]",
+  },
+  indigo: {
+    idle: "border-[var(--hue-indigo-border)] bg-[var(--hue-indigo-bg)] text-[var(--hue-indigo)]",
+    selected: "border-[var(--hue-indigo)] bg-[var(--hue-indigo-bg)] text-[var(--hue-indigo)]",
+  },
+  purple: {
+    idle: "border-[var(--hue-purple-border)] bg-[var(--hue-purple-bg)] text-[var(--hue-purple)]",
+    selected: "border-[var(--hue-purple)] bg-[var(--hue-purple-bg)] text-[var(--hue-purple)]",
+  },
+  teal: {
+    idle: "border-[var(--hue-teal-border)] bg-[var(--hue-teal-bg)] text-[var(--hue-teal)]",
+    selected: "border-[var(--hue-teal)] bg-[var(--hue-teal-bg)] text-[var(--hue-teal)]",
+  },
+  orange: {
+    idle: "border-[var(--hue-orange-border)] bg-[var(--hue-orange-bg)] text-[var(--hue-orange)]",
+    selected: "border-[var(--hue-orange)] bg-[var(--hue-orange-bg)] text-[var(--hue-orange)]",
+  },
 };
 
 // `outline` idle looks: the tone's border and text, the surface left to whatever the
@@ -100,6 +139,11 @@ const OUTLINE: Record<ChipTone, string> = {
   info: "border-[var(--info-border)] bg-transparent text-[var(--info)]",
   income: "border-current/60 bg-transparent text-[var(--money-income)]",
   expense: "border-current/60 bg-transparent text-[var(--money-expense)]",
+  blue: "border-[var(--hue-blue-border)] bg-transparent text-[var(--hue-blue)]",
+  indigo: "border-[var(--hue-indigo-border)] bg-transparent text-[var(--hue-indigo)]",
+  purple: "border-[var(--hue-purple-border)] bg-transparent text-[var(--hue-purple)]",
+  teal: "border-[var(--hue-teal-border)] bg-transparent text-[var(--hue-teal)]",
+  orange: "border-[var(--hue-orange-border)] bg-transparent text-[var(--hue-orange)]",
 };
 
 // `solid`: the fill under its contrast pair. Only brand and danger have a declared
@@ -116,12 +160,40 @@ const SOLID: Record<ChipTone, string> = {
   info: "border-transparent bg-[var(--info)] text-[var(--text-inverse)]",
   income: "border-transparent bg-[var(--money-income)] text-[var(--text-inverse)]",
   expense: "border-transparent bg-[var(--money-expense)] text-[var(--text-inverse)]",
+  blue: "border-transparent bg-[var(--hue-blue)] text-[var(--text-inverse)]",
+  indigo: "border-transparent bg-[var(--hue-indigo)] text-[var(--text-inverse)]",
+  purple: "border-transparent bg-[var(--hue-purple)] text-[var(--text-inverse)]",
+  teal: "border-transparent bg-[var(--hue-teal)] text-[var(--text-inverse)]",
+  orange: "border-transparent bg-[var(--hue-orange)] text-[var(--text-inverse)]",
+};
+
+/** `dot`: the fill of the dot itself — the tone's strongest colour, which is the one
+ *  chosen to read on the page surface in both themes. Neutral takes the muted ink: a
+ *  grey dot is "no particular state", not a darker black. */
+const DOT: Record<ChipTone, string> = {
+  neutral: "bg-[var(--text-muted)]",
+  brand: "bg-[var(--brand)]",
+  danger: "bg-[var(--danger)]",
+  warning: "bg-[var(--warning)]",
+  success: "bg-[var(--success)]",
+  info: "bg-[var(--info)]",
+  income: "bg-[var(--money-income)]",
+  expense: "bg-[var(--money-expense)]",
+  blue: "bg-[var(--hue-blue)]",
+  indigo: "bg-[var(--hue-indigo)]",
+  purple: "bg-[var(--hue-purple)]",
+  teal: "bg-[var(--hue-teal)]",
+  orange: "bg-[var(--hue-orange)]",
 };
 
+/** Per size: the dot's diameter. */
+const DOT_SIZE: Record<ChipSize, string> = { xs: "size-1.5", sm: "size-2", md: "size-2", lg: "size-2.5" };
+
 /** The status-badge type (`caps`): a size step down, heavier and tracked, because
  *  capitals at body size shout and capitals untracked run together. Per size, so it
  *  replaces the size's own `text-*` through tailwind-merge. */
 const CAPS: Record<ChipSize, string> = {
+  xs: "text-[10px] font-semibold uppercase tracking-wider",
   sm: "text-[10px] font-semibold uppercase tracking-wider",
   md: "text-[11px] font-semibold uppercase tracking-wider",
   lg: "text-xs font-semibold uppercase tracking-wider",
@@ -129,6 +201,13 @@ const CAPS: Record<ChipSize, string> = {
 
 function surfaceOf(tone: ChipTone, variant: ChipVariant, selected: boolean | undefined): string {
   const palette = TONE[tone];
+  if (variant === "dot") {
+    // No surface and no border colour: the dot carries the tone, the text stays ink.
+    // The border goes transparent rather than away, so a dot chip lines up with a pill.
+    return selected
+      ? "border-transparent bg-transparent font-medium text-[var(--text-primary)]"
+      : "border-transparent bg-transparent text-[var(--text-secondary)]";
+  }
   if (variant === "solid") {
     // A solid chip is already the strongest look there is, so "on" is a ring round it.
     return cn(SOLID[tone], selected && "ring-2 ring-[var(--border-strong)] ring-offset-1 ring-offset-[var(--bg-surface)]");
@@ -172,6 +251,13 @@ const SIZE: Record<
   ChipSize,
   { body: string; split: string; tail: string; icon: string; remove: string }
 > = {
+  xs: {
+    body: "gap-1 px-1.5 py-0 text-[11px] leading-4",
+    split: "gap-1 ps-1.5 pe-0.5 py-0 text-[11px] leading-4",
+    tail: "pe-1",
+    icon: "size-3",
+    remove: "size-2.5",
+  },
   sm: {
     body: "gap-1 px-2 py-0.5 text-xs",
     split: "gap-1 ps-2 pe-1 py-0.5 text-xs",
@@ -238,6 +324,16 @@ interface ChipBaseProps {
    * it — "+ Outflow" in green next to an inflow (keksdose #417).
    */
   selected?: boolean;
+  /**
+   * Checkbox mode (0.10.0), for a toggle chip (`onClick` + `selected`): a small box
+   * at the start that shows a tick when `selected`, and the button reports
+   * `role="checkbox"` + `aria-checked` instead of `aria-pressed`. For a set of
+   * include/exclude choices where "on" must read as TICKED, not merely tinted —
+   * keksdose's add-group-card (the "which categories come along" pills), which put a
+   * real `<Checkbox>` inside a `<label>` pill by hand. The box is drawn in both
+   * states so ticking one never shifts its label.
+   */
+  checkbox?: boolean;
   /** Renders a dismiss affordance. Works alongside `href`/`onClick` — see the note below. */
   onRemove?: () => void;
   /** Accessible name for the dismiss button. Default: `common.remove` from the
@@ -341,6 +437,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
     caps = false,
     icon: Icon,
     selected,
+    checkbox = false,
     href,
     renderLink,
     onClick,
@@ -362,7 +459,9 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
   const interactive = !!href || !!onClick;
   // One radius for every rounded piece — the pill, the body inside a split pill, the ×
   // — so a square chip has no round focus ring inside it.
-  const radius = shape === "square" ? (size === "sm" ? "rounded" : "rounded-md") : "rounded-full";
+  const radius =
+    shape === "square" ? (size === "sm" || size === "xs" ? "rounded" : "rounded-md") : "rounded-full";
+  const dot = variant === "dot";
   const type = cn(caps && CAPS[size], variant === "solid" && "justify-center tabular-nums");
   const surface = cn(
     surfaceOf(tone, variant, selected),
@@ -375,11 +474,29 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
     radius,
     surface,
     interactive && !disabled && "cursor-pointer hover:brightness-[0.97] dark:hover:brightness-110",
+    // An inert dot chip is text in a column: no inset, so it aligns with the header.
+    dot && !interactive && "px-0",
     className,
   );
 
+  // The checkbox box, only on the toggle shape it has meaning on.
+  const isCheckbox = checkbox && !!onClick && !href;
   const body = (
     <>
+      {isCheckbox && (
+        <span
+          aria-hidden
+          data-chip-check=""
+          className={cn(
+            "flex shrink-0 items-center justify-center rounded-sm border",
+            s.icon,
+            selected ? "border-current bg-current/15" : "border-current/50",
+          )}
+        >
+          {selected && <Check className="size-full" strokeWidth={3} />}
+        </span>
+      )}
+      {dot && <span aria-hidden data-chip-dot="" className={cn("shrink-0 rounded-full", DOT_SIZE[size], DOT[tone])} />}
       {Icon && <Icon className={cn(s.icon, "shrink-0")} aria-hidden />}
       <span className="min-w-0 truncate">{children}</span>
     </>
@@ -485,7 +602,11 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
         // Only when `selected` is PASSED: a chip with `onClick` and no `selected` is an
         // action button (it does something), not a toggle (it is on or off), and
         // announcing it "not pressed" would claim a state it does not have.
-        aria-pressed={selected}
+        // A checkbox chip says "checked", not "pressed" — the same state in the words
+        // of the control it looks like.
+        role={isCheckbox ? "checkbox" : undefined}
+        aria-pressed={isCheckbox ? undefined : selected}
+        aria-checked={isCheckbox ? !!selected : undefined}
         className={remove ? inner : look}
         {...rest}
       >

package/src/components/choice-card.tsx

@@ -1,5 +1,5 @@
 import { createContext, forwardRef, useCallback, useContext, useEffect, useId, useRef } from "react";
-import type { ChangeEvent, ComponentType, InputHTMLAttributes, ReactNode } from "react";
+import type { ButtonHTMLAttributes, ChangeEvent, ComponentType, InputHTMLAttributes, ReactNode } from "react";
 import { Check, Minus } from "lucide-react";
 import { cn } from "../lib/cn";
 import { assignRef, hasMessage, mergeDescribedBy } from "./choice-parts";
@@ -218,6 +218,102 @@ export const ChoiceCard = forwardRef<HTMLInputElement, ChoiceCardProps>(function
 });
 ChoiceCard.displayName = "ChoiceCard";
 
+/* ── ActionCard ──────────────────────────────────────────────────────────── */
+
+/** The colour of {@link ActionCardProps.meta}. */
+export type ActionCardMetaTone = "muted" | "warning" | "danger" | "info" | "success";
+
+const META_TONE: Record<ActionCardMetaTone, string> = {
+  muted: "text-[var(--text-muted)]",
+  warning: "text-[var(--warning)]",
+  danger: "text-[var(--danger)]",
+  info: "text-[var(--info)]",
+  success: "text-[var(--success)]",
+};
+
+export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "title"> {
+  /** What the card does — the button's accessible name. */
+  title: ReactNode;
+  /** A line or two on what it means. Attached with `aria-describedby`. */
+  description?: ReactNode;
+  /**
+   * What it costs, or what else to know — a third line, said as prose and not as fine
+   * print (keksdose's custody choice: both options are legitimate and neither is free,
+   * so a card listing only benefits would be selling rather than explaining). Attached
+   * with `aria-describedby` after the description.
+   */
+  meta?: ReactNode;
+  /** The meta line's colour. Default `muted`; keksdose's cost line is `warning`. */
+  metaTone?: ActionCardMetaTone;
+  /** A Lucide icon (or any component taking a `className`), shown at the card's start. */
+  icon?: ChoiceCardProps["icon"];
+}
+
+/**
+ * A {@link ChoiceCard} that ACTS rather than holds a state: a `<button>` with the
+ * card's icon, title and description, plus a `meta` line, that runs `onClick` the
+ * moment it is pressed. keksdose's privacy enrolment (privacy-enroll-dialog:345,
+ * `CustodyOption`) offers two custody modes this way — picking one IS the next step,
+ * so there is no checked state to show and no "Continue" to press after it.
+ *
+ * A separate component rather than `ChoiceCard as="button"`: a ChoiceCard is an
+ * `<input>` (its ref, its `checked`, its form value), and a button shares none of it.
+ * Named by the title alone and described by the rest, so a screen reader hears
+ * "Keep the key yourself, button" and then the explanation, not one long name.
+ */
+export const ActionCard = forwardRef<HTMLButtonElement, ActionCardProps>(function ActionCard(
+  { title, description, meta, metaTone = "muted", icon: Icon, className, id, type = "button", ...rest },
+  ref,
+) {
+  const generated = useId();
+  const baseId = id ?? generated;
+  const titleId = `${baseId}-title`;
+  const descriptionId = `${baseId}-description`;
+  const metaId = `${baseId}-meta`;
+  const showDescription = hasMessage(description);
+  const showMeta = hasMessage(meta);
+  return (
+    <button
+      ref={ref}
+      id={id}
+      type={type}
+      {...rest}
+      aria-labelledby={rest["aria-labelledby"] ?? titleId}
+      aria-describedby={mergeDescribedBy(
+        rest["aria-describedby"],
+        showDescription && descriptionId,
+        showMeta && metaId,
+      )}
+      className={cn(
+        "flex w-full items-start gap-3 rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] p-3 text-start shadow-sm transition-colors",
+        "hover:border-[var(--brand)] hover:bg-[var(--bg-hover)]",
+        // The outline, as on ChoiceCard: the card is what the eye is on.
+        "focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
+        "disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:border-[var(--border)] disabled:hover:bg-[var(--bg-surface)]",
+        className,
+      )}
+    >
+      {Icon && <Icon aria-hidden className="mt-0.5 size-5 shrink-0 text-[var(--text-secondary)]" />}
+      <span className="min-w-0 flex-1 space-y-1">
+        <span id={titleId} className="block text-sm font-medium leading-5 text-[var(--text-primary)]">
+          {title}
+        </span>
+        {showDescription && (
+          <span id={descriptionId} className="block text-sm text-[var(--text-secondary)]">
+            {description}
+          </span>
+        )}
+        {showMeta && (
+          <span id={metaId} className={cn("block text-sm", META_TONE[metaTone])}>
+            {meta}
+          </span>
+        )}
+      </span>
+    </button>
+  );
+});
+ActionCard.displayName = "ActionCard";
+
 /* ── ChoiceCardGroup ─────────────────────────────────────────────────────── */
 
 export interface ChoiceCardOption<T extends string> {

package/src/components/copy-button.tsx

@@ -6,7 +6,7 @@ import { useAnnounce } from "../hooks/use-announce";
 import { useCopyToClipboard } from "../hooks/use-copy-to-clipboard";
 import type { CopyState } from "../hooks/use-copy-to-clipboard";
 import { Button, IconButton } from "./ui";
-import type { ButtonVariant, IconButtonSize } from "./ui";
+import type { ButtonSize, ButtonTone, ButtonVariant, IconButtonSize, IconButtonTone } from "./ui";
 import { Tooltip } from "./tooltip";
 import type { TooltipSide } from "./tooltip";
 
@@ -43,8 +43,17 @@ export interface CopyButtonProps
   label?: string;
   /** The button's own look. Default: `ghost` for the icon, `secondary` for the label. */
   buttonVariant?: ButtonVariant;
-  /** Icon variant only. */
-  size?: IconButtonSize;
+  /** The icon variant's IconButton size (default `sm`). The `label` variant takes a
+   *  Button size, `sm` or `md` — passed only when given, so an existing label button
+   *  keeps its look (keksdose budget-share-card and jobs-panel wanted the compact one). */
+  size?: IconButtonSize | ButtonSize;
+  /** The icon variant's IconButton tone (e.g. `muted`, so a row of copy icons is no
+   *  heavier than the row's other actions); in the `label` variant a Button tone,
+   *  which applies to `link` / `ghost`. The copied / failed colour still wins. */
+  tone?: IconButtonTone | ButtonTone;
+  /** Keep the click and Enter/Space from reaching a clickable row around the button,
+   *  as IconButton's own `stopPropagation` does (keksdose feedback-page, users-panel). */
+  stopPropagation?: boolean;
   /** Icon variant only: where the result tooltip opens. */
   tooltipSide?: TooltipSide;
   /** Pass through to the tooltip — needed inside a scroll container (see Tooltip). */
@@ -80,7 +89,9 @@ export function CopyButton({
   variant = "icon",
   label,
   buttonVariant,
-  size = "sm",
+  size,
+  tone,
+  stopPropagation,
   tooltipSide = "top",
   tooltipPortal = false,
   resetAfter = 2000,
@@ -123,8 +134,17 @@ export function CopyButton({
           {...rest}
           disabled={disabled}
           variant={buttonVariant ?? "secondary"}
+          size={size === "sm" || size === "md" ? size : undefined}
+          tone={tone === "default" || tone === "muted" || tone === "danger" ? tone : undefined}
           data-state={state}
-          onClick={onClick}
+          onClick={(e) => {
+            if (stopPropagation) e.stopPropagation();
+            void onClick();
+          }}
+          onKeyDown={(e) => {
+            if (stopPropagation && (e.key === "Enter" || e.key === " ")) e.stopPropagation();
+            rest.onKeyDown?.(e);
+          }}
           className={className}
         >
           <Icon aria-hidden className={cn("size-4 shrink-0", iconTone)} />
@@ -144,9 +164,11 @@ export function CopyButton({
           disabled={disabled}
           aria-label={idleText}
           variant={buttonVariant ?? "ghost"}
-          size={size}
+          size={(size ?? "sm") as IconButtonSize}
+          tone={tone as IconButtonTone | undefined}
+          stopPropagation={stopPropagation}
           data-state={state}
-          onClick={onClick}
+          onClick={() => void onClick()}
           className={cn(iconTone, className)}
         >
           <Icon aria-hidden />

package/src/components/data-table.tsx

@@ -1427,6 +1427,11 @@ export function DataTable<T>({
       // density (`group-data-[density=compact]/table:…`) without being told twice.
       data-density={density}
       data-frame={frame ? undefined : "none"}
+      // The frame clips (`overflow-clip`), so it is a clipping container for a
+      // Tooltip's auto-portal — said as an attribute as well, because jsdom computes no
+      // classes and a table-cell tooltip must portal under test just as it does in the
+      // browser (see `CLIPS_ATTRIBUTE`). The bare root clips nothing and is not marked.
+      data-clips={frame ? "" : undefined}
       className={cn(
         "group/table",
         frame ? "overflow-clip" : "min-w-0",
@@ -1535,6 +1540,8 @@ export function DataTable<T>({
               other half of the `w-0 min-w-full` fix on the expansion cell below
               (feedback #104: "expanding an item resizes the columns"). */}
           <div
+            // The scroller: marked for the Tooltip's auto-portal (see the root above).
+            data-clips=""
             className={cn("overflow-auto [scrollbar-gutter:stable]", fillHeight && "flex-1 min-h-0")}
             style={fillHeight ? undefined : { maxHeight: maxBodyHeight }}
           >

package/src/components/date-picker.tsx

@@ -770,6 +770,27 @@ export interface DateRangePickerProps extends DatePickerBaseProps {
    * would overwrite the sheet's history marker.
    */
   sheetBackCloses?: boolean;
+  /**
+   * With `commit="apply"`: a line above the calendar saying what Apply would commit —
+   * keksdose's report range writes "Custom · 1 Mar 2026 – …" there
+   * (report-range-field.tsx), the one place a preset armed and then nudged by a day is
+   * seen to have become "Custom", and a half-made range to still lack its end. Called
+   * with the DRAFT on every change, in the popover and the phone sheet alike; `preset`
+   * is the preset the column marks for it (none once a day was picked by hand), `to` is
+   * `""` until the second click. The line is a polite live region, so a screen reader
+   * hears the draft change as the calendar is used.
+   *
+   * Ignored in `"immediate"` mode, where there is no draft: every click is the value.
+   */
+  renderDraftSummary?: (draft: DateRangeDraftSummary) => ReactNode;
+}
+
+/** What {@link DateRangePickerProps.renderDraftSummary} is called with. */
+export interface DateRangeDraftSummary {
+  from: string;
+  to: string;
+  /** The preset the column marks for the draft, if any. */
+  preset: DateRangePickerPreset | undefined;
 }
 
 /** What {@link DateRangePickerProps.renderTrigger} is called with. */
@@ -889,6 +910,7 @@ function RangePanel({
   commitRange,
   calendarProps,
   labels,
+  renderDraftSummary,
 }: {
   from: string;
   to: string;
@@ -903,6 +925,7 @@ function RangePanel({
   commitRange: (from: string, to: string, presetId: string | undefined) => void;
   calendarProps: Pick<MiniCalendarProps, "locale" | "min" | "max" | "labels">;
   labels: DatePickerLabels;
+  renderDraftSummary?: DateRangePickerProps["renderDraftSummary"];
 }) {
   const drafting = commit === "apply";
   const [draft, setDraft] = useState<RangeDraft>({
@@ -917,7 +940,12 @@ function RangePanel({
     : -1;
   const complete = Boolean(draft.from && draft.to);
 
-  const calendar = (
+  const summary =
+    drafting && renderDraftSummary
+      ? renderDraftSummary({ from: draft.from, to: draft.to, preset: presets?.[marked] })
+      : null;
+
+  const picker = (
     <MiniCalendar
       {...calendarProps}
       focusOnOpen
@@ -934,6 +962,24 @@ function RangePanel({
       }}
     />
   );
+  // The summary heads the CALENDAR's column, not the panel: beside a preset column it
+  // reads as the calendar's caption, and in the sheet it sits between the presets and
+  // the month it describes. `null` renders no line — a caller may opt out per draft —
+  // but keeps the wrapper, so the calendar is not remounted (and its month and focus
+  // lost) when a line comes or goes.
+  const calendar =
+    drafting && renderDraftSummary ? (
+      <div className="flex flex-col gap-2">
+        {summary != null && (
+          <div aria-live="polite" data-draft-summary="" className="text-xs text-[var(--text-muted)]">
+            {summary}
+          </div>
+        )}
+        {picker}
+      </div>
+    ) : (
+      picker
+    );
 
   const body =
     presets && presets.length > 0 ? (
@@ -1006,6 +1052,7 @@ export function DateRangePicker({
   commit = "immediate",
   renderTrigger,
   sheetBackCloses,
+  renderDraftSummary,
   calendarLabels,
   label,
   clearable,
@@ -1082,6 +1129,7 @@ export function DateRangePicker({
           commitRange={commitRange}
           calendarProps={{ locale, min, max, labels: calendarLabels }}
           labels={text}
+          renderDraftSummary={renderDraftSummary}
         />
       )}
     </DateField>