@eifi1/ui-kit 0.11.0 → 0.13.0

package/src/components/data-table-labels.ts

@@ -69,6 +69,22 @@ export interface DataTableLabels {
   rowCount: (total: number) => string;
   /** The column-settings rail and its heading: "Columns (4/9)". */
   columnsCount: (visible: number, total: number) => string;
+
+  // ---- Empty state, row actions, boolean cells (0.12.0) ----
+
+  /** The body of a table with no rows and no `empty` prop of its own. A sentence, not
+   *  "—": a dash in the only row of a table reads as one row with a missing value. */
+  empty: string;
+  /** The accessible name of the `rowActions` column (its header is visually empty). */
+  actions: string;
+  /** The `kind: "edit"` row action's name — its tooltip and its swipe label. */
+  edit: string;
+  /** The `kind: "delete"` row action's name. */
+  delete: string;
+  /** What {@link BooleanMark} says to a screen reader for `true` / `false` / nothing. */
+  booleanTrue: string;
+  booleanFalse: string;
+  booleanUnset: string;
 }
 
 export const DEFAULT_DATA_TABLE_LABELS: DataTableLabels = {
@@ -120,6 +136,13 @@ export const DEFAULT_DATA_TABLE_LABELS: DataTableLabels = {
   pageRange: (from, to, total) => `${from}–${to} / ${total}`,
   rowCount: (total) => `${total}`,
   columnsCount: (visible, total) => `Columns (${visible}/${total})`,
+  empty: "No entries",
+  actions: "Actions",
+  edit: "Edit",
+  delete: "Delete",
+  booleanTrue: "Yes",
+  booleanFalse: "No",
+  booleanUnset: "Not set",
 };
 
 /**

package/src/components/data-table.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { CSSProperties, ReactNode, TdHTMLAttributes, ThHTMLAttributes } from "react";
 import { createPortal } from "react-dom";
 import {
@@ -8,9 +8,11 @@ import {
   ChevronDown,
   ChevronRight,
   Filter,
+  Pencil,
+  Trash2,
   X,
 } from "lucide-react";
-import { Card, Spinner } from "./ui";
+import { Card, IconButton, Spinner } from "./ui";
 import { cn } from "../lib/cn";
 import {
   defaultFilterState,
@@ -239,8 +241,11 @@ export interface DataTableProps<T> {
    * shareable and bookmarkable. URL params used: `f.<column>`, `sort`, `p`, `ps`.
    * URL state takes precedence over localStorage on initial load. Requires the
    * consuming app to render inside a react-router Router.
+   *
+   * `{ prefix }` namespaces them, for two URL-synced tables on one page:
+   * `urlSync={{ prefix: "inv." }}` uses `inv.f.<column>`, `inv.sort`, `inv.p`, `inv.ps`.
    */
-  urlSync?: boolean;
+  urlSync?: TableUrlSync;
   /**
    * When true (desktop only), the table fills its parent's height and scrolls
    * INTERNALLY, with the header pinned — so the page itself doesn't add a second,
@@ -431,6 +436,98 @@ export interface DataTableProps<T> {
   /** Extra classes for the table's root element (the card, or with `frame={false}`
    *  the plain wrapper). Merged last, so a caller's margin or width wins. */
   className?: string;
+  /**
+   * Per-row actions: an actions column of icon buttons at the row's end on desktop,
+   * and the same actions as swipe actions on a phone card (where the column is not
+   * shown). kastlan's `ResourceListPage` appended this column by hand to every CRUD
+   * list — the edit pencil, the delete bin, a `useConfirm` before the delete, and a
+   * `stopPropagation` on each so a press did not also open the row.
+   *
+   * `kind: "edit"` / `"delete"` bring the icon, the label (`labels.edit` /
+   * `labels.delete`), the tone and the swipe side; any other action states its own
+   * `label` and `icon`. `confirm` is the hook-in for a confirmation: pass the kit's
+   * `useConfirm()` (or anything answering a boolean) and the action runs only on a yes.
+   *
+   *     const confirm = useConfirm();
+   *     rowActions={[
+   *       { kind: "edit", onAction: openEditor },
+   *       { kind: "delete", onAction: (r) => remove(r.id),
+   *         confirm: (r) => confirm({ title: t("delete", { name: r.name }), tone: "danger" }) },
+   *     ]}
+   *
+   * A function receives the row, for actions that differ per row. An explicit
+   * `mobileSwipeActions` wins over the swipes derived from here.
+   */
+  rowActions?: DataTableRowAction<T>[] | ((row: T) => DataTableRowAction<T>[]);
+  /**
+   * The bar above the table — a search field, filter chips, a create button. Inside
+   * the table's frame, above the header, on desktop and phone alike (resource-list
+   * pages set a search box in a `div` above the card, outside the frame it filters).
+   */
+  toolbar?: ReactNode;
+}
+
+/** One entry of {@link DataTableProps.rowActions}. */
+export interface DataTableRowAction<T> {
+  /** A preset: `"edit"` (pencil, `labels.edit`, swipes toward the END) or `"delete"`
+   *  (bin, `labels.delete`, danger tone, swipes toward the START). */
+  kind?: "edit" | "delete";
+  /** The action's name — its tooltip, accessible name and swipe label. Required
+   *  without a `kind`. */
+  label?: string;
+  /** The glyph. Required without a `kind`. */
+  icon?: ReactNode;
+  /** Runs after `confirm` (when given) has said yes. */
+  onAction: (row: T) => void;
+  /** Asked before `onAction`; a `false` (or a promise of one) cancels. */
+  confirm?: (row: T) => boolean | Promise<boolean>;
+  /** Default: `"danger"` for `kind: "delete"`, else `"default"`. */
+  tone?: "default" | "danger";
+  /** Leave the action out for this row. */
+  hidden?: (row: T) => boolean;
+  /** Why the action is locked for this row — the button stays focusable and says so,
+   *  and the row gets no swipe for it. See `IconButton`'s `disabledReason`. */
+  disabledReason?: (row: T) => ReactNode;
+  /** Which way the phone card is dragged to commit it, or `false` for no swipe.
+   *  Default: `"start"` for a danger action, `"end"` otherwise. */
+  swipe?: "start" | "end" | false;
+}
+
+/** The actions column's key. Not a column a caller declares, so it is kept out of the
+ *  column-settings panel. */
+const ROW_ACTIONS_KEY = "__rowActions";
+
+interface ResolvedRowAction<T> {
+  key: string;
+  label: string;
+  icon: ReactNode;
+  tone: "default" | "danger";
+  swipe: "start" | "end" | false;
+  action: DataTableRowAction<T>;
+}
+
+function resolveRowAction<T>(
+  action: DataTableRowAction<T>,
+  index: number,
+  labels: DataTableLabels,
+): ResolvedRowAction<T> {
+  const tone = action.tone ?? (action.kind === "delete" ? "danger" : "default");
+  return {
+    key: action.kind ?? `${index}:${action.label ?? ""}`,
+    label: action.label ?? (action.kind === "edit" ? labels.edit : action.kind === "delete" ? labels.delete : ""),
+    icon:
+      action.icon ??
+      (action.kind === "edit" ? <Pencil /> : action.kind === "delete" ? <Trash2 /> : null),
+    tone,
+    swipe: action.swipe ?? (tone === "danger" ? "start" : "end"),
+    action,
+  };
+}
+
+/** Ask, then act. */
+async function runRowAction<T>(action: DataTableRowAction<T>, row: T): Promise<void> {
+  if (action.confirm && !(await action.confirm(row))) return;
+  action.onAction(row);
 }
 
 /** See {@link DataTableProps.chrome}. */
@@ -516,7 +613,8 @@ function cleanAttrs(
  * header is not a string and whose key is not human-readable is a call site that
  * should pass a string header, and that is visible in what gets announced.
  */
-function columnLabel<T>(col: DataTableColumn<T>): string {
+function columnLabel<T>(col: DataTableColumn<T>, labels?: DataTableLabels): string {
+  if (col.key === ROW_ACTIONS_KEY && labels) return labels.actions;
   return typeof col.header === "string" ? col.header : col.key;
 }
 
@@ -528,6 +626,20 @@ function columnLabel<T>(col: DataTableColumn<T>): string {
 const OWN_CONTROL =
   'a[href],button,input,select,textarea,label,summary,[role="button"],[role="link"],[role="checkbox"],[role="switch"],[role="menuitem"],[role="option"],[contenteditable=""],[contenteditable="true"],[tabindex]:not([tabindex="-1"])';
 
+/**
+ * Whether a click that reached `row`'s handler did not start in the row's own DOM.
+ *
+ * React bubbles an event through the COMPONENT tree, portals included: a popover, a
+ * menu or a dialog a cell (or the expansion under it) opens renders at `<body>` but
+ * still reports its clicks to every React ancestor — the row among them. So a click
+ * in a cell's portalled date picker opened the row it came from, and a page wrapped
+ * such content in `<div onClick={(e) => e.stopPropagation()}>` to stop it (kastlan's
+ * feedback page did, round its comments). The row owns the clicks on the row.
+ */
+function fromOutside(target: EventTarget | null, row: HTMLElement): boolean {
+  return !(target instanceof Node) || !row.contains(target);
+}
+
 /** Whether an event on `row` started on a control nested inside it. */
 function fromOwnControl(target: EventTarget | null, row: HTMLElement): boolean {
   if (!(target instanceof Element)) return false;
@@ -617,9 +729,13 @@ function RowLink({
       // here happens before any descendant can silence the event; `stopPropagation`
       // does not undo a `preventDefault`.
       onClickCapture={(e) => {
+        // A click in a portal a descendant opened is not a click on the link: leave
+        // it (and a link inside it) alone. See `fromOutside`.
+        if (fromOutside(e.target, e.currentTarget)) return;
         if (isPlainLeftClick(e)) e.preventDefault();
       }}
       onClick={(e) => {
+        if (fromOutside(e.target, e.currentTarget)) return;
         if (!isPlainLeftClick(e)) {
           e.stopPropagation();
           return;
@@ -639,12 +755,12 @@ function RowLink({
 
 
 
-import { DEFAULT_PERSIST_PREFIX, useTableState } from "./use-table-state";
+import { DEFAULT_PERSIST_PREFIX, useTableState, type TableUrlSync } from "./use-table-state";
 import { useMobileReveal } from "./use-mobile-reveal";
 
 export function DataTable<T>({
   rows,
-  columns,
+  columns: columnsProp,
   rowKey,
   defaultPageSize = 25,
   onRowClick,
@@ -682,6 +798,8 @@ export function DataTable<T>({
   multiSort: multiSortProp,
   frame = true,
   className,
+  rowActions,
+  toolbar,
 }: DataTableProps<T>) {
   const compact = density === "compact";
   const minimal = chrome === "minimal";
@@ -711,6 +829,74 @@ export function DataTable<T>({
     [labelOverrides, labelsProp],
   );
   const locale = useKitLocale(localeProp);
+
+  // ---- Row actions ----
+  // The actions column is appended to the caller's columns rather than drawn as a
+  // second special case beside the selection column: it then gets the cell padding,
+  // the widths and the phone rules (`mobileHidden`) every other column gets.
+  const rowActionsFor = useCallback(
+    (row: T): ResolvedRowAction<T>[] =>
+      rowActions
+        ? (typeof rowActions === "function" ? rowActions(row) : rowActions)
+            .filter((a) => !a.hidden?.(row))
+            .map((a, i) => resolveRowAction(a, i, labels))
+        : [],
+    [rowActions, labels],
+  );
+  const columns = useMemo<DataTableColumn<T>[]>(
+    () =>
+      rowActions
+        ? [
+            ...columnsProp,
+            {
+              key: ROW_ACTIONS_KEY,
+              header: <span className="sr-only">{labels.actions}</span>,
+              cell: (row) => (
+                <div className="flex items-center justify-end gap-0.5">
+                  {rowActionsFor(row).map((a) => (
+                    <IconButton
+                      key={a.key}
+                      size={density === "compact" ? "2xs" : "xs"}
+                      label={a.label}
+                      tone={a.tone === "danger" ? "danger" : undefined}
+                      disabledReason={a.action.disabledReason?.(row)}
+                      // The row's click handler already skips its own controls; this is for
+                      // the caller who wraps the table in a clickable element of their own.
+                      stopPropagation
+                      onClick={() => void runRowAction(a.action, row)}
+                    >
+                      {a.icon}
+                    </IconButton>
+                  ))}
+                </div>
+              ),
+              className: "w-px whitespace-nowrap text-end",
+              headClassName: "w-px",
+              // On a phone the same actions are the card's swipes.
+              mobileHidden: true,
+              noRowLink: true,
+            },
+          ]
+        : columnsProp,
+    [columnsProp, rowActions, rowActionsFor, labels.actions, density],
+  );
+  const swipesFromActions = (row: T): MobileSwipeActions | null => {
+    const swipes = rowActionsFor(row).filter((a) => a.swipe && !a.action.disabledReason?.(row));
+    if (!swipes.length) return null;
+    const toSwipe = (a: ResolvedRowAction<T>): SwipeAction => ({
+      label: a.label,
+      icon: a.icon,
+      onCommit: () => void runRowAction(a.action, row),
+      className: a.tone === "danger" ? "bg-[var(--danger)]" : "bg-[var(--brand)]",
+      armedClassName: a.tone === "danger" ? "bg-[var(--danger-hover)]" : "bg-[var(--brand-hover)]",
+    });
+    return {
+      start: swipes.filter((a) => a.swipe === "start").map(toSwipe),
+      end: swipes.filter((a) => a.swipe === "end").map(toSwipe),
+    };
+  };
+  const swipeActionsFor = mobileSwipeActions ?? (rowActions ? swipesFromActions : undefined);
+
   // Sorting, filtering and paging all change WHICH rows are on screen without
   // moving focus — the header button the user pressed is still the header button
   // they are on — so there is no other channel to say it on. See use-announce.ts.
@@ -875,7 +1061,7 @@ export function DataTable<T>({
     // criterion BEHIND the existing one, and answering "Sorted by Date" to a click on
     // Name misreports what the click did. The third click drops the column entirely,
     // which is the state a user is most likely to have reached by accident.
-    const name = col ? columnLabel(col) : key;
+    const name = col ? columnLabel(col, labels) : key;
     const entry = next.find((s) => s.key === key);
     announce(
       !entry
@@ -1122,7 +1308,10 @@ export function DataTable<T>({
   const totalCount = columns.length;
   // Spans the full row width including the optional leading selection column.
   const totalColSpan = visibleCount + (selection ? 1 : 0);
-  const columnsCountLabel = labels.columnsCount(visibleCount, totalCount);
+  // The actions column is the table's own, not one the user can hide: out of the count.
+  const columnsCountLabel = rowActions
+    ? labels.columnsCount(visibleCount - 1, totalCount - 1)
+    : labels.columnsCount(visibleCount, totalCount);
   // Match Tailwind's `md` breakpoint: we render either the table or the card
   // list — never both — so we don't double up DOM nodes that screen readers and
   // integration tests would have to disambiguate.
@@ -1252,7 +1441,7 @@ export function DataTable<T>({
     // uses for exactly this, and it points the way the row actually opens: right into
     // a sheet, or down into an inline panel that flips it when expanded.
     const opensDetail = interactive && !!expandedRow;
-    const swipeActions = mobileSwipeActions?.(row);
+    const swipeActions = swipeActionsFor?.(row);
     const swipe = swipeActions ? physicalSwipe(swipeActions, mobileDir) : null;
     // An expanded row never swipes: the editor below it owns the horizontal space,
     // and dragging the header away from its own form reads as a glitch.
@@ -1359,10 +1548,20 @@ export function DataTable<T>({
           {cardInner}
         </RowLink>
       ) : (
+        /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- the handlers are
+           only attached when `interactive`, and then so are role="button", tabIndex 0 and the
+           Enter/Space handler below; the rule cannot follow the conditional role. */
         <div
           role={interactive ? "button" : undefined}
           tabIndex={interactive ? 0 : undefined}
-          onClick={interactive ? () => onRowClick!(row) : undefined}
+          onClick={
+            interactive
+              ? (e) => {
+                  if (fromOutside(e.target, e.currentTarget)) return;
+                  onRowClick!(row);
+                }
+              : undefined
+          }
           onKeyDown={
             interactive
               ? (e) => {
@@ -1445,6 +1644,19 @@ export function DataTable<T>({
           card list for the table wholesale, which would remount a region living
           inside either one. */}
       <span {...regionProps} />
+      {toolbar != null && toolbar !== false && (
+        <div
+          data-table-toolbar=""
+          className={cn(
+            "flex flex-wrap items-center gap-2",
+            frame
+              ? cn("border-b border-[var(--border)]", compact ? "px-2 py-1.5" : "px-3 py-2")
+              : "pb-3",
+          )}
+        >
+          {toolbar}
+        </div>
+      )}
       {!isMdUp && (
       <div ref={mobileRootRef}>
         {/* Mobile filter access (feedback #299): the per-column filter popovers
@@ -1489,7 +1701,7 @@ export function DataTable<T>({
                 compact ? "px-3 py-3 text-xs" : "px-4 py-6 text-sm",
               )}
             >
-              {isLoading ? <LoadingText label={labels.loading} /> : (empty ?? "—")}
+              {isLoading ? <LoadingText label={labels.loading} /> : (empty ?? labels.empty)}
             </li>
           )}
           {/* Endless-scroll sentinel: observed by IntersectionObserver to pull in
@@ -1708,7 +1920,10 @@ export function DataTable<T>({
                         </Popover>
                       )}
                     </div>
-                    {resizable && (
+                    {resizable && col.key !== ROW_ACTIONS_KEY && (
+                    /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- a
+                       pointer-only drag handle for a visual preference (column width); it is
+                       deliberately not a tab stop, and no content or action depends on it. */
                     <span
                       role="separator"
                       aria-orientation="vertical"
@@ -1800,6 +2015,7 @@ export function DataTable<T>({
                             // not also open the row. Cells no longer have to
                             // `stopPropagation` to get that.
                             if (fromOwnControl(e.target, e.currentTarget)) return;
+                            if (fromOutside(e.target, e.currentTarget)) return;
                             // Modifier-clicks anywhere in the row drive
                             // selection instead of expanding it (feedback #289):
                             // Ctrl/Cmd toggles a single row, Shift selects the
@@ -1935,7 +2151,7 @@ export function DataTable<T>({
                 >
                   {/* Nothing is not the same as not-yet: "no results" while the first
                       page is still in flight is a claim the table cannot make. */}
-                  {isLoading ? <LoadingText label={labels.loading} /> : (empty ?? "—")}
+                  {isLoading ? <LoadingText label={labels.loading} /> : (empty ?? labels.empty)}
                 </td>
               </tr>
             )}
@@ -2018,6 +2234,7 @@ export function DataTable<T>({
             </button>
             <div className="flex flex-col gap-0.5">
               {columns.map((col) => {
+                if (col.key === ROW_ACTIONS_KEY) return null;
                 const checked = !hiddenCols.has(col.key);
                 const headerLabel = columnLabel(col);
                 return (

package/src/components/date-picker.tsx

@@ -91,6 +91,8 @@ export interface DateTriggerAttributes {
   "aria-label"?: string;
   "aria-describedby"?: string;
   "aria-invalid"?: true;
+  /** The field's required state — `Field required` hands it down with the id pair. */
+  "aria-required"?: boolean | "true" | "false";
   disabled?: boolean;
   onClick: () => void;
   className: string;
@@ -132,6 +134,7 @@ function DateFieldTrigger({
   padded,
   disabled,
   invalid,
+  required,
   panelId,
   aria,
   renderTrigger,
@@ -153,6 +156,8 @@ function DateFieldTrigger({
   padded: boolean;
   disabled?: boolean;
   invalid?: boolean;
+  /** `aria-required`, on the trigger with the rest of the field's ARIA. */
+  required?: boolean | "true" | "false";
 }) {
   const wasOpen = useRef(false);
   useEffect(() => {
@@ -177,6 +182,7 @@ function DateFieldTrigger({
   // One attribute object, worn either by the kit's own button below or by a caller's
   // (`renderTrigger`) — so a custom trigger cannot quietly fall out of step with the
   // naming and state this one announces.
+  const isInvalid = Boolean(invalid) || aria["aria-invalid"] === true || aria["aria-invalid"] === "true";
   const attrs: DateTriggerAttributes = {
     ref: triggerRef,
     type: "button",
@@ -209,14 +215,15 @@ function DateFieldTrigger({
     "aria-haspopup": "dialog",
     "aria-controls": panelId,
     "aria-expanded": open,
-    "aria-invalid":
-      invalid || aria["aria-invalid"] === true || aria["aria-invalid"] === "true" || undefined,
+    "aria-invalid": isInvalid || undefined,
+    "aria-required": required,
     className: cn(
       FIELD_TRIGGER,
       "pe-9",
       padded && FIELD_FLOATING_PAD,
       disabled && "cursor-not-allowed opacity-50",
-      invalid && FIELD_INVALID,
+      // An `aria-invalid` from a Field spread paints too, as on Input and AmountInput.
+      isInvalid && FIELD_INVALID,
     ),
   };
   if (renderTrigger) return <CustomTrigger render={renderTrigger} attrs={attrs} valueId={valueId} />;
@@ -279,6 +286,10 @@ function DateField({
   sheetBackCloses = true,
   renderTrigger,
   children,
+  // The trigger's, not the wrapper's: `Field`'s render-prop spreads it with the id
+  // pair, and a required date read as optional while it sat on the role-less div.
+  // Taken here rather than in `splitTriggerAria`, which MonthPicker shares.
+  "aria-required": ariaRequired,
   ...rest
 }: Omit<ComponentPropsWithoutRef<"div">, "children"> & {
   triggerText: string;
@@ -393,6 +404,7 @@ function DateField({
       padded={label !== undefined}
       disabled={disabled}
       invalid={invalid}
+      required={ariaRequired}
       renderTrigger={renderTrigger}
     />
   );
@@ -577,6 +589,9 @@ export function DatePicker({
   clearLabel,
   disabled,
   invalid,
+  // Named so it reaches the field (and so its trigger) when a step/today row is the
+  // root and takes the rest of the caller's props.
+  "aria-required": ariaRequired,
   ...rest
 }: DatePickerProps) {
   const locale = useKitLocale(localeProp);
@@ -593,6 +608,7 @@ export function DatePicker({
       // With step/today buttons the flex row is the root and takes the caller's props —
       // except the ones that name the field, which still belong on its trigger.
       {...(wrapped ? triggerAria : rest)}
+      aria-required={ariaRequired}
       label={label}
       clearable={clearable}
       clearLabel={text.clear}

package/src/components/description-list.tsx

@@ -1,8 +1,20 @@
 import { createContext, useContext } from "react";
 import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
 import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
 import { FieldHint } from "./ui";
 
+/** The words a {@link DescriptionList} renders on its own behalf. */
+export interface DescriptionListLabels {
+  /** What an item with no value shows (see {@link DescriptionItemProps.placeholder}).
+   *  Default "—", an em dash. */
+  empty: string;
+}
+
+export const DEFAULT_DESCRIPTION_LIST_LABELS: DescriptionListLabels = {
+  empty: "—",
+};
+
 export type DescriptionListLayout = "rows" | "cards" | "stacked";
 export type DescriptionListDensity = "comfortable" | "compact" | "tight";
 /** How many columns a `stacked` or `cards` list may use. */
@@ -14,6 +26,7 @@ interface ListContextValue {
   prose: boolean;
   density: DescriptionListDensity;
   columns: DescriptionListColumns;
+  placeholder?: ReactNode;
 }
 
 const ListContext = createContext<ListContextValue>({
@@ -103,6 +116,9 @@ export interface DescriptionListProps extends ComponentPropsWithoutRef<"dl"> {
    * all would not be an improvement. Per item: {@link DescriptionItemProps.prose}.
    */
   prose?: boolean;
+  /** What an item with no value shows, for every item that does not set its own —
+   *  see {@link DescriptionItemProps.placeholder}. */
+  placeholder?: ReactNode;
 }
 
 /**
@@ -129,6 +145,7 @@ export function DescriptionList({
   density = "comfortable",
   minCardWidth = "10rem",
   columns,
+  placeholder,
   className,
   style,
   ...rest
@@ -147,7 +164,7 @@ export function DescriptionList({
   const grid: CSSProperties | undefined = cards
     ? { gridTemplateColumns: `repeat(auto-fill, minmax(min(100%, ${track}), 1fr))` }
     : undefined;
-  const ctx: ListContextValue = { layout, numeric, prose, density, columns: columns ?? 2 };
+  const ctx: ListContextValue = { layout, numeric, prose, density, columns: columns ?? 2, placeholder };
   const text = density === "tight" ? "text-[11px] leading-4" : density === "compact" ? "text-xs" : "text-sm";
 
   if (stacked) {
@@ -215,6 +232,20 @@ export interface DescriptionItemProps extends Omit<ComponentPropsWithoutRef<"div
    * because a card grid's column count is not known to CSS ahead of layout.
    */
   span?: number | "full";
+  /**
+   * Shown in place of a value that is not there — `children` of `null`, `undefined`,
+   * `false` or `""` (a `0` is a value and is shown). Default: the list's own
+   * `placeholder`, else `descriptionList.empty` from the provider, else "—". `null`
+   * shows nothing, as an empty detail did before. kastlan's DetailField put its
+   * `EMPTY_VALUE` into every one of its call sites' values by hand.
+   *
+   * Drawn in the muted ink, so an absent value does not read as a value of "—".
+   */
+  placeholder?: ReactNode;
+}
+
+function isEmptyValue(node: ReactNode): boolean {
+  return node === undefined || node === null || node === false || node === "";
 }
 
 const ROW_PAD: Record<DescriptionListDensity, string> = {
@@ -236,11 +267,23 @@ export function DescriptionItem({
   numeric: numericProp,
   prose: proseProp,
   span,
+  placeholder: placeholderProp,
   detailClassName,
   className,
   ...rest
 }: DescriptionItemProps) {
-  const { layout, numeric: listNumeric, prose: listProse, density, columns } = useContext(ListContext);
+  const {
+    layout,
+    numeric: listNumeric,
+    prose: listProse,
+    density,
+    columns,
+    placeholder: listPlaceholder,
+  } = useContext(ListContext);
+  const labels = useKitLabels("descriptionList", DEFAULT_DESCRIPTION_LIST_LABELS);
+  const empty = isEmptyValue(children);
+  const placeholder =
+    placeholderProp !== undefined ? placeholderProp : listPlaceholder !== undefined ? listPlaceholder : labels.empty;
   const numeric = numericProp ?? listNumeric;
   const prose = proseProp ?? listProse;
   const cards = layout === "cards";
@@ -277,7 +320,13 @@ export function DescriptionItem({
         detailClassName,
       )}
     >
-      {children}
+      {empty && !isEmptyValue(placeholder) ? (
+        <span data-slot="description-empty" className="font-normal text-[var(--text-muted)]">
+          {placeholder}
+        </span>
+      ) : (
+        children
+      )}
     </dd>
   );