@eifi1/ui-kit 0.10.0 → 0.12.0

package/src/components/line-items.tsx

@@ -0,0 +1,385 @@
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, CSSProperties, KeyboardEvent, Key, ReactNode } from "react";
+import { Plus, Trash2 } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Button, IconButton } from "./ui";
+
+/** The words {@link LineItems} renders on its own behalf. Row numbers are 1-based. */
+export interface LineItemsLabels {
+  /** The dashed add button. */
+  add: string;
+  /** The remove button's name for one row. */
+  remove: (row: number) => string;
+  /** Its name while it waits for the second press (`confirmRemove`). */
+  confirmRemove: (row: number) => string;
+  /** A row's group name, when the caller gives no `rowLabel`. */
+  row: (row: number) => string;
+  /** The name a cell's field should carry: the column, and which row. */
+  cell: (column: string, row: number) => string;
+  /** The totals row's label, and its group name. */
+  totals: string;
+}
+
+export const DEFAULT_LINE_ITEMS_LABELS: LineItemsLabels = {
+  add: "Add row",
+  remove: (row) => `Remove row ${row}`,
+  confirmRemove: (row) => `Remove row ${row}? Press again to confirm`,
+  row: (row) => `Row ${row}`,
+  cell: (column, row) => `${column}, row ${row}`,
+  totals: "Total",
+};
+
+/** What a column's `render` receives for one row. */
+export interface LineItemCellContext<T> {
+  item: T;
+  /** 0-based. */
+  index: number;
+  /** The accessible name for the cell's field — "Debit, row 2". The header is
+   *  hidden from assistive tech (each row repeats it), so the field has to carry it:
+   *  `<Input aria-label={label} … />`. */
+  label: string;
+}
+
+export interface LineItemsColumn<T> {
+  /** Stable id: the React key, and the key into `totals`. */
+  key: string;
+  /** The column header (and the small label over the cell once the rows stack). */
+  header: ReactNode;
+  /** The column's name for {@link LineItemCellContext.label}, when `header` is not a
+   *  string. */
+  label?: string;
+  /** The grid track once the rows are wide enough to be a table. Default
+   *  `minmax(0,1fr)`; `"7rem"` for an amount. */
+  width?: string;
+  /** `end` for figures: the header and the totals cell end-align with the field. */
+  align?: "start" | "end";
+  render: (ctx: LineItemCellContext<T>) => ReactNode;
+}
+
+export interface LineItemsProps<T> extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  items: readonly T[];
+  columns: readonly LineItemsColumn<T>[];
+  /** The row's React key. Default: the item's `id` (react-hook-form's `useFieldArray`
+   *  `fields` carry one), else its index. */
+  getKey?: (item: T, index: number) => Key;
+  /** Append a row. Omitted: no add button. The first field of the new row is focused. */
+  onAdd?: () => void;
+  /** Remove the row at `index`. Omitted: no remove buttons. */
+  onRemove?: (index: number) => void;
+  /** Remove is disabled at or below this many rows (a journal entry needs two).
+   *  Default 0. */
+  minItems?: number;
+  /** Add is disabled at this many rows. */
+  maxItems?: number;
+  /**
+   * Ask before a row goes:
+   *  - `true`: the remove button asks for a second press — it fills red and its name
+   *    becomes `lineItems.confirmRemove`; Escape, or leaving it, calls it off.
+   *  - a function: called with the row, and the row goes only if it answers `true`
+   *    (`(item, i) => confirm({ title: … , tone: "danger" })` with `useConfirm`).
+   */
+  confirmRemove?: boolean | ((item: T, index: number) => boolean | Promise<boolean>);
+  /** The add button's text. Default `lineItems.add`. */
+  addLabel?: ReactNode;
+  /** A row's group name ("Line 2"). Default `lineItems.row`. */
+  rowLabel?: (index: number, item: T) => string;
+  /** A totals row under the lines, one entry per column `key`. The first column
+   *  without an entry carries {@link totalsLabel}. Omitted: no totals row. */
+  totals?: Partial<Record<string, ReactNode>>;
+  /** Default `lineItems.totals`, "Total". */
+  totalsLabel?: ReactNode;
+  /** Shown in place of the rows when there are none. */
+  empty?: ReactNode;
+  /** A message about the list as a whole ("The entry does not balance"). */
+  error?: ReactNode;
+  /** Disables add and remove (the fields are the caller's to disable). */
+  disabled?: boolean;
+  labels?: Partial<LineItemsLabels>;
+}
+
+const REMOVE_TRACK = "2.25rem";
+const FOCUSABLE =
+  "input:not([disabled]):not([type=hidden]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex='-1'])";
+
+function defaultKey(item: unknown, index: number): Key {
+  if (typeof item === "object" && item !== null && "id" in item) {
+    const id = (item as { id: unknown }).id;
+    if (typeof id === "string" || typeof id === "number") return id;
+  }
+  return index;
+}
+
+function hasContent(node: ReactNode): boolean {
+  return node !== undefined && node !== null && node !== false && node !== "";
+}
+
+type PendingFocus = { kind: "added" } | { kind: "removed"; index: number };
+
+/**
+ * An editable list of lines — journal entry lines, lease components, invoice
+ * positions, budget rows: column headers, a row of fields per item, a remove button
+ * per row, a dashed "add" button under them, and an optional totals row.
+ *
+ * Presentation only: the rows are the caller's `items` and the fields are the
+ * caller's, rendered per column. So it works over plain state —
+ *
+ * ```tsx
+ * <LineItems items={lines} columns={cols} onAdd={() => setLines([...lines, blank()])}
+ *   onRemove={(i) => setLines(lines.filter((_, j) => j !== i))} minItems={2} />
+ * ```
+ *
+ * — and over react-hook-form's `useFieldArray` alike (`items={fields}`, `onAdd={() =>
+ * append(blank())}`, `onRemove={remove}`), for which `@eifi1/ui-kit/rhf` has
+ * `RhfLineItems`.
+ *
+ * On a wide pane the rows are a grid under the headers; on a narrow one (a container
+ * query, so a dialog stacks where it is cramped) each row stacks its fields, each
+ * under a small copy of its header. The headers are `aria-hidden`: every row is a
+ * named group and every field is named by `render`'s `label` ("Debit, row 2"), which
+ * is what a screen reader needs — a header row it would read once, out of context.
+ *
+ * Keyboard: after Add, focus lands in the new row's first field; after a remove, on
+ * the row that took its place (else the add button). Ctrl/⌘+Enter in any row adds a
+ * row.
+ */
+export function LineItems<T>({
+  items,
+  columns,
+  getKey = defaultKey,
+  onAdd,
+  onRemove,
+  minItems = 0,
+  maxItems,
+  confirmRemove,
+  addLabel,
+  rowLabel,
+  totals,
+  totalsLabel,
+  empty,
+  error,
+  disabled = false,
+  labels: labelsProp,
+  className,
+  style,
+  ...rest
+}: LineItemsProps<T>) {
+  const labels = useKitLabels("lineItems", DEFAULT_LINE_ITEMS_LABELS, labelsProp);
+  const rowRefs = useRef<Array<HTMLDivElement | null>>([]);
+  const addRef = useRef<HTMLButtonElement>(null);
+  const pendingFocus = useRef<PendingFocus | null>(null);
+  const [confirmingAt, setConfirming] = useState<number | null>(null);
+  // A confirm waiting on a row that has since gone is void.
+  const confirming = confirmingAt !== null && confirmingAt < items.length ? confirmingAt : null;
+
+  const tracks = [...columns.map((c) => c.width ?? "minmax(0,1fr)"), ...(onRemove ? [REMOVE_TRACK] : [])];
+  const gridStyle = { "--line-items-cols": tracks.join(" ") } as CSSProperties;
+  const canAdd = Boolean(onAdd) && !disabled && (maxItems === undefined || items.length < maxItems);
+  const canRemove = Boolean(onRemove) && !disabled && items.length > minItems;
+  const hasError = hasContent(error);
+
+
+  // Focus after the list has re-rendered with the new rows — a layout effect, so the
+  // caret is where it belongs before paint.
+  useLayoutEffect(() => {
+    const pending = pendingFocus.current;
+    if (!pending) return;
+    pendingFocus.current = null;
+    if (pending.kind === "added") {
+      const row = rowRefs.current[items.length - 1];
+      row?.querySelector<HTMLElement>(FOCUSABLE)?.focus();
+      return;
+    }
+    const row = rowRefs.current[Math.min(pending.index, items.length - 1)];
+    const target =
+      row?.querySelector<HTMLElement>("[data-line-items-remove]:not([disabled])") ??
+      row?.querySelector<HTMLElement>(FOCUSABLE) ??
+      addRef.current;
+    target?.focus();
+  }, [items.length]);
+
+  const add = useCallback(() => {
+    if (!canAdd || !onAdd) return;
+    pendingFocus.current = { kind: "added" };
+    onAdd();
+  }, [canAdd, onAdd]);
+
+  const removeAt = async (index: number) => {
+    if (!canRemove || !onRemove) return;
+    if (confirmRemove === true && confirming !== index) {
+      setConfirming(index);
+      return;
+    }
+    if (typeof confirmRemove === "function") {
+      const ok = await confirmRemove(items[index], index);
+      if (!ok) return;
+    }
+    setConfirming(null);
+    pendingFocus.current = { kind: "removed", index };
+    onRemove(index);
+  };
+
+  const onRowKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key === "Enter" && (e.ctrlKey || e.metaKey) && canAdd) {
+      e.preventDefault();
+      add();
+    }
+  };
+
+  const columnName = (column: LineItemsColumn<T>) =>
+    column.label ?? (typeof column.header === "string" ? column.header : column.key);
+
+  const headerCell = (column: LineItemsColumn<T>) => (
+    <span
+      key={column.key}
+      className={cn(
+        "min-w-0 truncate text-xs font-medium text-[var(--text-muted)]",
+        column.align === "end" && "text-end",
+      )}
+    >
+      {column.header}
+    </span>
+  );
+
+  const showTotals = totals !== undefined;
+  const labelColumn = showTotals ? columns.find((c) => !hasContent(totals[c.key]))?.key : undefined;
+
+  return (
+    <div
+      data-slot="line-items"
+      {...rest}
+      style={{ ...gridStyle, ...style }}
+      className={cn("@container space-y-2", className)}
+    >
+      <div aria-hidden className="hidden gap-2 @lg:grid @lg:grid-cols-[var(--line-items-cols)]">
+        {columns.map(headerCell)}
+        {onRemove && <span />}
+      </div>
+
+      {items.length === 0 && hasContent(empty) && (
+        <div className="rounded-md border border-dashed border-[var(--border)] px-3 py-4 text-center text-sm text-[var(--text-muted)]">
+          {empty}
+        </div>
+      )}
+
+      {items.map((item, index) => {
+        const row = index + 1;
+        const isConfirming = confirming === index;
+        return (
+          // The row's Ctrl/⌘+Enter is a shortcut for the add button, which is itself
+          // reachable by Tab; the group only listens for it bubbling from its fields.
+          // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
+          <div
+            key={getKey(item, index)}
+            ref={(el) => {
+              rowRefs.current[index] = el;
+            }}
+            role="group"
+            aria-label={rowLabel ? rowLabel(index, item) : labels.row(row)}
+            data-line-items-row=""
+            onKeyDown={onRowKeyDown}
+            className={cn(
+              "grid grid-cols-1 gap-2 @lg:grid-cols-[var(--line-items-cols)] @lg:items-start",
+              // Stacked, each row is a card of its own so the rows stay apart.
+              "@max-lg:rounded-md @max-lg:border @max-lg:border-[var(--border)] @max-lg:p-3",
+            )}
+          >
+            {columns.map((column) => (
+              <div key={column.key} className="min-w-0 space-y-1 @lg:space-y-0">
+                <span aria-hidden className="block text-xs font-medium text-[var(--text-muted)] @lg:hidden">
+                  {column.header}
+                </span>
+                {column.render({ item, index, label: labels.cell(columnName(column), row) })}
+              </div>
+            ))}
+            {onRemove && (
+              <div className="flex justify-end @lg:justify-center">
+                <IconButton
+                  type="button"
+                  data-line-items-remove=""
+                  variant={isConfirming ? "danger" : "ghost"}
+                  tone={isConfirming ? undefined : "danger"}
+                  label={isConfirming ? labels.confirmRemove(row) : labels.remove(row)}
+                  disabled={!canRemove}
+                  onClick={() => void removeAt(index)}
+                  onBlur={() => {
+                    if (isConfirming) setConfirming(null);
+                  }}
+                  onKeyDown={(e) => {
+                    if (e.key === "Escape" && isConfirming) {
+                      e.stopPropagation();
+                      setConfirming(null);
+                    }
+                  }}
+                >
+                  <Trash2 />
+                </IconButton>
+              </div>
+            )}
+          </div>
+        );
+      })}
+
+      {showTotals && (
+        <div
+          role="group"
+          aria-label={typeof totalsLabel === "string" ? totalsLabel : labels.totals}
+          data-line-items-totals=""
+          className="grid grid-cols-1 gap-2 border-t border-[var(--border)] pt-2 text-sm font-semibold tabular-nums text-[var(--text-primary)] @lg:grid-cols-[var(--line-items-cols)]"
+        >
+          {columns.map((column) => {
+            const value = totals[column.key];
+            if (column.key === labelColumn) {
+              return (
+                <span key={column.key} className="min-w-0">
+                  {totalsLabel ?? labels.totals}
+                </span>
+              );
+            }
+            return (
+              <span
+                key={column.key}
+                className={cn(
+                  "min-w-0",
+                  column.align === "end" && "@lg:text-end",
+                  // Stacked, a column with no total takes no line.
+                  !hasContent(value) && "@max-lg:hidden",
+                )}
+              >
+                {hasContent(value) && (
+                  <span className="flex justify-between gap-2 @lg:block">
+                    <span aria-hidden className="font-normal text-[var(--text-muted)] @lg:hidden">
+                      {column.header}
+                    </span>
+                    {value}
+                  </span>
+                )}
+              </span>
+            );
+          })}
+          {onRemove && <span className="@max-lg:hidden" />}
+        </div>
+      )}
+
+      {hasError && (
+        <p className="text-[11px] leading-tight text-[var(--danger)]">
+          {error}
+        </p>
+      )}
+
+      {onAdd && (
+        <Button
+          ref={addRef}
+          type="button"
+          variant="secondary"
+          className="w-full border-dashed"
+          disabled={!canAdd}
+          onClick={add}
+        >
+          <Plus aria-hidden className="size-4" />
+          {addLabel ?? labels.add}
+        </Button>
+      )}
+    </div>
+  );
+}

package/src/components/list.tsx

@@ -1,11 +1,12 @@
-import { createContext, forwardRef, useContext } from "react";
-import type { ComponentPropsWithoutRef, MouseEvent, ReactElement, ReactNode, Ref } from "react";
+import { createContext, forwardRef, useContext, useId } from "react";
+import type { ComponentPropsWithoutRef, HTMLAttributes, MouseEvent, ReactElement, ReactNode, Ref } from "react";
 import { ExternalLink } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./ui";
 import { StatusDot } from "./status-dot";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "./text-link";
 
 /* ── Labels ───────────────────────────────────────────────────────────────── */
 
@@ -95,10 +96,10 @@ export interface ListItemLinkProps {
   [key: `data-${string}`]: unknown;
 }
 
-const PAD: Record<ListDensity, { target: string; actions: string; gap: string }> = {
-  compact: { target: "gap-2 px-2 py-1.5", actions: "pe-1.5", gap: "gap-0.5" },
-  default: { target: "gap-3 px-3 py-2.5", actions: "pe-2", gap: "gap-1" },
-  comfortable: { target: "gap-3 px-4 py-3", actions: "pe-3", gap: "gap-1" },
+const PAD: Record<ListDensity, { target: string; actions: string; gap: string; body: string }> = {
+  compact: { target: "gap-2 px-2 py-1.5", actions: "pe-1.5", gap: "gap-0.5", body: "px-2 pb-1.5" },
+  default: { target: "gap-3 px-3 py-2.5", actions: "pe-2", gap: "gap-1", body: "px-3 pb-2.5" },
+  comfortable: { target: "gap-3 px-4 py-3", actions: "pe-3", gap: "gap-1", body: "px-4 pb-3" },
 };
 
 const TARGET_RING =
@@ -134,6 +135,26 @@ interface ListItemBaseProps {
    * on "Copy" from selecting the row.
    */
   actions?: ReactNode;
+  /**
+   * Rich content UNDER the title row and outside its target: photos, per-row buttons,
+   * form fields — kastlan's handover room inspector (room-inspector.tsx), the handover
+   * detail page and the wizard's defects step (wizard/defects-step.tsx), which draw
+   * each room or defect as a `Card variant="inset"` because a row could not hold a
+   * photo strip with its own buttons.
+   *
+   * The same rule as {@link actions}, one row down: the title area stays ONE named
+   * target (the button or link, with the title and subtitle as its name), and the body
+   * is its sibling, never nested in it — a thumbnail's "Remove" inside the row's button
+   * would be invalid HTML and unreachable by a screen reader. The body is a
+   * `role="group"` named by the row's title (`aria-labelledby`), so tabbing into the
+   * third photo's button of the second room is heard as "Kitchen, group" first rather
+   * than as a button floating free of any row. Inside the row's box, so a `selected`
+   * border and a `divider` hold both; the hover fill stays on the target alone, since
+   * the body is not what a click on the row does.
+   */
+  children?: ReactNode;
+  /** Classes on the {@link children} body. */
+  bodyClassName?: string;
   /**
    * The unread mark: a brand dot at the row's end, the title in semibold, and "Unread"
    * read after the title (keksdose notification-inbox.tsx:215). For another status,
@@ -165,6 +186,19 @@ interface ListItemBaseProps {
   className?: string;
   /** Classes on the main target (the button, link or static block). */
   targetClassName?: string;
+  /**
+   * Extra attributes and handlers for the main target — e.g. HTML5 drag-and-drop
+   * (`draggable`, `onDragStart`, `onDragEnd`): lenkbank's segment list drags the WHOLE
+   * 44px row, and a grip inside the button cannot start a drag in Firefox. Spread first,
+   * so the row's own role, name, state and click handling always win.
+   */
+  targetProps?: HTMLAttributes<HTMLElement>;
+  /**
+   * A visible border while unselected, instead of the transparent one. For rows laid out
+   * as a wrapping strip (lenkbank's profile bar), where borderless rows read as loose
+   * text. The selected row's brand border is unchanged.
+   */
+  bordered?: boolean;
   /** `div` for a single row outside a {@link List}; an `<li>` must sit in a list. */
   as?: "li" | "div";
   /** Reaches the main target — the element with the row's name and action. */
@@ -194,8 +228,9 @@ export type ListItemProps = ListItemBaseProps &
          * cannot do.
          */
         href: string;
-        /** Your router's link for an in-app `href`. Default `<a>`. The API `Chip`,
-         *  `StatTile` and `MenuItem` share. Ignored for an `external` row. */
+        /** Your router's link for an in-app `href`. Default: the `<UiKitProvider
+         *  linkComponent>`, then `<a>`. The API `Chip`, `StatTile` and `MenuItem`
+         *  share. Ignored for an `external` row. */
         renderLink?: (props: ListItemLinkProps) => ReactElement;
         /**
          * The link leaves the app: a plain `<a target="_blank" rel="noopener
@@ -250,7 +285,11 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
     align = "center",
     className,
     targetClassName,
+    targetProps,
+    bordered = false,
     as = "li",
+    children,
+    bodyClassName,
     href,
     renderLink,
     external = false,
@@ -262,12 +301,15 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
 ) {
   const list = useContext(ListContext);
   const labels = useKitLabels("list", DEFAULT_LIST_LABELS);
+  const kitLink = useKitLink();
   const density = densityProp ?? list.density;
   const pad = PAD[density];
   const isLink = href !== undefined && !disabled;
   const isButton = !isLink && onClick !== undefined && href === undefined;
   const interactive = isLink || isButton;
   const inert = disabled || loading;
+  const hasBody = children !== undefined && children !== null && children !== false;
+  const titleId = useId();
 
   const mark =
     status ??
@@ -284,6 +326,8 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
       {leading}
       <span className="flex min-w-0 flex-1 flex-col">
         <span
+          // Names the body's group; harmless without one.
+          id={hasBody ? titleId : undefined}
           className={cn(
             "block truncate text-sm text-[var(--text-primary)]",
             unread ? "font-semibold" : "font-medium",
@@ -321,16 +365,24 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
     "flex min-w-0 flex-1 text-start",
     align === "start" ? "items-start" : "items-center",
     pad.target,
-    "rounded-[inherit]",
+    // With a body the target is the top of the box, not all of it, so it takes its
+    // own corners and its own hover fill (see `children`).
+    hasBody ? "rounded-md" : "rounded-[inherit]",
+    hasBody && interactive && !inert && !selected && "transition-colors hover:bg-[var(--bg-hover)]",
     interactive && TARGET_RING,
     interactive && !inert && "cursor-pointer",
     loading && "cursor-progress",
     targetClassName,
   );
 
+  // `role` is the row's own (a button, a link, or nothing on a static block): a
+  // targetProps role would silently turn the row into something else.
+  const { role: _ignoredRole, ...targetExtras } = targetProps ?? {};
+
   let main: ReactNode;
   if (isLink) {
     const linkProps: ListItemLinkProps = {
+      ...(targetExtras as Partial<ListItemLinkProps>),
       ...rest,
       ref: ref as Ref<HTMLAnchorElement>,
       href,
@@ -344,8 +396,9 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
       children: body,
     };
     const { children: linkBody, ...anchorProps } = linkProps;
-    main = renderLink && !external ? (
-      <RenderedLink render={renderLink} {...linkProps} />
+    const render = external ? undefined : pickLinkRenderer(renderLink, kitLink, href);
+    main = render ? (
+      <RenderedLink render={render} {...linkProps} />
     ) : (
       <a {...anchorProps} {...(external ? { target: "_blank", rel: "noopener noreferrer" } : null)}>
         {linkBody}
@@ -354,6 +407,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
   } else if (isButton) {
     main = (
       <button
+        {...(targetExtras as HTMLAttributes<HTMLButtonElement>)}
         {...rest}
         ref={ref as Ref<HTMLButtonElement>}
         type="button"
@@ -372,6 +426,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
   } else {
     main = (
       <div
+        {...(targetExtras as HTMLAttributes<HTMLDivElement>)}
         {...rest}
         ref={ref as Ref<HTMLDivElement>}
         aria-disabled={disabled || undefined}
@@ -383,6 +438,9 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
     );
   }
 
+  const actionsEl =
+    actions != null ? <div className={cn("flex shrink-0 items-center", pad.gap, pad.actions)}>{actions}</div> : null;
+
   const Tag = as;
   return (
     <Tag
@@ -393,16 +451,33 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
     >
       <div
         className={cn(
-          "flex min-w-0 items-center rounded-md border transition-colors",
-          selected ? "border-[var(--brand)] bg-[var(--bg-surface-2)]" : "border-transparent",
-          interactive && !inert && !selected && "hover:bg-[var(--bg-hover)]",
+          "flex min-w-0 rounded-md border transition-colors",
+          hasBody ? "flex-col" : "items-center",
+          selected
+            ? "border-[var(--brand)] bg-[var(--bg-surface-2)]"
+            : bordered
+              ? "border-[var(--border)]"
+              : "border-transparent",
+          !hasBody && interactive && !inert && !selected && "hover:bg-[var(--bg-hover)]",
           disabled && "opacity-50",
           className,
         )}
       >
-        {main}
-        {actions != null && (
-          <div className={cn("flex shrink-0 items-center", pad.gap, pad.actions)}>{actions}</div>
+        {hasBody ? (
+          <>
+            <div className="flex min-w-0 items-center">
+              {main}
+              {actionsEl}
+            </div>
+            <div role="group" aria-labelledby={titleId} className={cn("min-w-0", pad.body, bodyClassName)}>
+              {children}
+            </div>
+          </>
+        ) : (
+          <>
+            {main}
+            {actionsEl}
+          </>
         )}
       </div>
     </Tag>

package/src/components/loading-state.tsx

@@ -0,0 +1,47 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { Spinner } from "./ui";
+
+export type LoadingStateSize = "sm" | "md" | "lg";
+
+export interface LoadingStateProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
+  /** The visible words under the spinner, and what the status region announces.
+   *  Default: `common.loading` ("Loading…"). */
+  label?: ReactNode;
+  /** `sm` for a panel or a table body, `md` (default) for a section, `lg` for a page. */
+  size?: LoadingStateSize;
+  /** Spinner beside the text on one line, rather than above it. */
+  inline?: boolean;
+}
+
+const SPINNER: Record<LoadingStateSize, string> = { sm: "h-4 w-4", md: "h-8 w-8", lg: "h-10 w-10" };
+const TEXT: Record<LoadingStateSize, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
+const PAD: Record<LoadingStateSize, string> = { sm: "py-4", md: "py-12", lg: "py-20" };
+
+/**
+ * A spinner and the words "Loading…", centred where the content will be.
+ *
+ * kastlan's `LoadingState` (feedback/loading-state.tsx:14), which got the reading
+ * right the second time: the WRAPPER is the `role="status"` region and the words are
+ * visible text inside it, so the spinner is decorative (`label={null}`) — otherwise
+ * the reader hears "Loading… Loading…", one from each.
+ */
+export function LoadingState({ label, size = "md", inline = false, className, ...rest }: LoadingStateProps) {
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  return (
+    <div
+      {...rest}
+      role="status"
+      className={cn(
+        "flex items-center justify-center text-center text-[var(--text-muted)]",
+        inline ? "gap-2" : "flex-col gap-2",
+        PAD[size],
+        className,
+      )}
+    >
+      <Spinner label={null} className={SPINNER[size]} />
+      <span className={TEXT[size]}>{label ?? common.loading}</span>
+    </div>
+  );
+}