@eifi1/ui-kit 0.20.1 → 0.22.0

package/src/components/data-table.tsx

@@ -3,8 +3,10 @@ import type { CSSProperties, ReactNode, TdHTMLAttributes, ThHTMLAttributes } fro
 import { createPortal } from "react-dom";
 import {
   ArrowDown,
+  ArrowDownWideNarrow,
   ArrowUp,
   ArrowUpDown,
+  ArrowUpNarrowWide,
   ChevronDown,
   ChevronRight,
   Filter,
@@ -12,7 +14,7 @@ import {
   Trash2,
   X,
 } from "lucide-react";
-import { Card, IconButton, Spinner } from "./ui";
+import { Card, IconButton, Select, Spinner } from "./ui";
 import { cn } from "../lib/cn";
 import {
   defaultFilterState,
@@ -33,7 +35,7 @@ import { FullBleedDialog } from "./full-bleed-dialog";
 import { Popover } from "./popover";
 import { useMediaQuery } from "../hooks/use-media-query";
 import { useAnnounce } from "../hooks/use-announce";
-import { resolveDataTableLabels, type DataTableLabels } from "./data-table-labels";
+import { DEFAULT_DATA_TABLE_LABELS, resolveDataTableLabels, type DataTableLabels } from "./data-table-labels";
 import { useKitLabelOverrides, useKitLocale } from "../i18n/kit-labels";
 import { Tooltip } from "./tooltip";
 import { dirOf, isRtl, type Direction } from "../lib/direction";
@@ -78,6 +80,14 @@ export interface DataTableColumn<T> {
    * Default `"asc"`.
    */
   firstSort?: SortDir;
+  /**
+   * The column's name as plain text, for the places a ReactNode `header` cannot go:
+   * the phone sort control's options ({@link DataTableProps.mobileSort}), the spoken
+   * "Sorted by …" and the column-settings checklist. Only needed when `header` is not
+   * a string (an icon, a unit suffix); without it those places fall back to the
+   * header string, then to `key`.
+   */
+  headerText?: string;
   /**
    * Extra attributes for this column's `<td>` in a given row — a `data-*` hook, a
    * `title`, an `aria-describedby`, a class. keksdose's accounts page
@@ -390,6 +400,18 @@ export interface DataTableProps<T> {
    * wastes space (feedback #317). Desktop is unaffected.
    */
   mobileCard?: (row: T) => ReactNode;
+  /**
+   * A "Sort by" select and a direction button above the phone card list (keksdose
+   * K10). The card list has no header row, so without it a phone user is stuck with
+   * whatever order the table opened in. It drives the same sort state as the column
+   * headers — `sorts`/`onSortsChange` when controlled, the URL and `storageKey` when
+   * not — and offers the columns a header click could sort (those with a `sortBy`).
+   * Each option is named by the column's `headerText`, else its string `header`.
+   *
+   * Off by default, so no existing phone layout gains a row. Strings:
+   * {@link DataTableSortLabels}. Phones only; the desktop table is unchanged.
+   */
+  mobileSort?: boolean;
   /**
    * Swipe actions for a mobile row, revealed by dragging it horizontally. Return
    * `null` (or empty sides) for rows that should not move — a locked row, one whose
@@ -683,7 +705,120 @@ function cleanAttrs(
  */
 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;
+  return col.headerText ?? (typeof col.header === "string" ? col.header : col.key);
+}
+
+// ---------- Phone sort control (keksdose K10) ----------
+
+/**
+ * The phone sort control's strings (keksdose K10). They are `dataTable` strings —
+ * read from the table's resolved labels, so the `labels` prop and the provider's
+ * `dataTable` namespace reach them — and are declared here, beside the control, with
+ * English defaults until `DataTableLabels` declares them itself.
+ */
+export interface DataTableSortLabels {
+  /** The control's visible label: "Sort by". */
+  sortBy: string;
+  /** The "no sort" option — the rows in the order they were given: "Default order". */
+  sortDefault: string;
+  /** The direction button's name while the sort ascends: "Ascending". */
+  sortAscending: string;
+  /** …and while it descends: "Descending". */
+  sortDescending: string;
+}
+
+/** The phone sort control's words, as they sit in {@link DEFAULT_DATA_TABLE_LABELS}
+ *  (DataTableLabels extends DataTableSortLabels; one source for the English). */
+export const DEFAULT_DATA_TABLE_SORT_LABELS: DataTableSortLabels = {
+  sortBy: DEFAULT_DATA_TABLE_LABELS.sortBy,
+  sortDefault: DEFAULT_DATA_TABLE_LABELS.sortDefault,
+  sortAscending: DEFAULT_DATA_TABLE_LABELS.sortAscending,
+  sortDescending: DEFAULT_DATA_TABLE_LABELS.sortDescending,
+};
+
+const flipDir = (d: SortDir): SortDir => (d === "asc" ? "desc" : "asc");
+
+/**
+ * The card list's sort control: a "Sort by" select and a direction button.
+ *
+ * keksdose K10 (inputs audit 2026-10-02 §5; its aggregated report tables, #258): a
+ * table is sorted by its header row and the phone card list has none, so the two
+ * decisions the header carries — which column, which direction — were unreachable
+ * below the breakpoint. keksdose hand-built this row over its DataTable to answer
+ * "who did I pay the most" on the device it was asked on; this is that row, driven by
+ * the SAME sort state as the headers (controlled `sorts` included), so turning the
+ * phone sideways keeps the order and a sort chosen here is the one the URL and the
+ * storage key hold.
+ *
+ * The rules are the header's: a newly picked column starts in its `firstSort`, the
+ * direction button flips the primary sort (secondary ones stay), and "Default order"
+ * — the third click of a `"tri"` cycle — is offered only under `"tri"`, since a
+ * `"toggle"` table promises it is always ranked by something. The select's label is
+ * a real `<label>` beside it, and the button sits outside that label: a click inside
+ * a label is forwarded to the control it names, so a nested button would flip AND
+ * open the select.
+ */
+function MobileSort<T>({
+  columns,
+  sorts,
+  sortCycle,
+  compact,
+  labels,
+  onPick,
+  onFlip,
+}: {
+  columns: DataTableColumn<T>[];
+  sorts: SortState[];
+  sortCycle: SortCycle;
+  compact: boolean;
+  labels: DataTableLabels;
+  onPick: (key: string | null) => void;
+  onFlip: () => void;
+}) {
+  const selectId = useId();
+  const sortLabels: DataTableSortLabels = labels;
+  if (columns.length === 0) return null;
+  // A persisted or URL sort can name a column with no `sortBy` (or a hidden one): the
+  // sort chain drops it, and so does the control rather than claiming it.
+  const primary = sorts[0] && columns.some((c) => c.key === sorts[0].key) ? sorts[0] : null;
+  const offerDefault = sortCycle === "tri" || primary === null;
+  const desc = primary?.dir === "desc";
+  return (
+    <div
+      data-table-mobile-sort=""
+      className={cn(
+        "flex items-center gap-2 border-b border-[var(--border)]",
+        compact ? "px-3 py-1.5" : "px-4 py-2",
+      )}
+    >
+      <label htmlFor={selectId} className="shrink-0 text-xs text-[var(--text-muted)]">
+        {sortLabels.sortBy}
+      </label>
+      <Select
+        id={selectId}
+        size={compact ? "sm" : "md"}
+        className="min-w-0 flex-1"
+        value={primary?.key ?? ""}
+        onChange={(e) => onPick(e.target.value || null)}
+      >
+        {offerDefault && <option value="">{sortLabels.sortDefault}</option>}
+        {columns.map((col) => (
+          <option key={col.key} value={col.key}>
+            {columnLabel(col, labels)}
+          </option>
+        ))}
+      </Select>
+      <IconButton
+        size={compact ? "xs" : "md"}
+        variant="secondary"
+        label={desc ? sortLabels.sortDescending : sortLabels.sortAscending}
+        disabled={primary === null}
+        onClick={onFlip}
+      >
+        {desc ? <ArrowDownWideNarrow /> : <ArrowUpNarrowWide />}
+      </IconButton>
+    </div>
+  );
 }
 
 /**
@@ -857,6 +992,7 @@ export function DataTable<T>({
   mobileGroupBy,
   mobileGroupLabel,
   mobileCard,
+  mobileSort = false,
   mobileSwipeActions,
   leadingRow,
   density = "comfortable",
@@ -1125,6 +1261,13 @@ export function DataTable<T>({
       firstDir: col?.firstSort,
       cycle: sortCycle,
     });
+    commitSorts(next, key);
+  };
+
+  // Header clicks and the phone sort control (`mobileSort`) land here alike, so both
+  // go through the same owner and say the same thing.
+  const commitSorts = (next: SortState[], key: string) => {
+    const col = columns.find((c) => c.key === key);
     if (onSortsChange) onSortsChange(next);
     else setInternalSorts(next);
 
@@ -1405,9 +1548,9 @@ export function DataTable<T>({
 
   // ---- Mobile card list (md:hidden) ----
   // Renders the same paged/filtered/sorted slice but as stacked cards instead
-  // of a horizontally-scrolling table. Filters / sort / column settings are
-  // intentionally hidden here — the mobile layout assumes the user wants to
-  // scan rows quickly. Switch to a wider viewport for fine-grained control.
+  // of a horizontally-scrolling table. Column settings stay desktop-only; the
+  // filters come through a bottom sheet (feedback #299) and the sort through the
+  // opt-in `mobileSort` row (keksdose K10), both on the table's own state.
   const mobileColumns = visibleColumns.filter((c) => !c.mobileHidden);
   const mobilePrimaryCol =
     mobileColumns.find((c) => c.mobilePrimary) ?? mobileColumns[0] ?? null;
@@ -1765,6 +1908,32 @@ export function DataTable<T>({
             locale={locale}
           />
         )}
+        {mobileSort && (
+          <MobileSort
+            columns={visibleColumns.filter((c) => (!isServer || !!onSortsChange) && !!c.sortBy)}
+            sorts={sorts}
+            sortCycle={sortCycle}
+            compact={compact}
+            labels={labels}
+            onPick={(key) => {
+              if (key === null) {
+                if (sorts.length > 0) commitSorts([], sorts[0].key);
+                return;
+              }
+              if (sorts[0]?.key === key) return;
+              // A newly picked column starts where its header's first click would.
+              const col = columns.find((c) => c.key === key);
+              commitSorts([{ key, dir: col?.firstSort ?? "asc" }], key);
+            }}
+            onFlip={() => {
+              if (sorts.length === 0) return;
+              commitSorts(
+                sorts.map((s, i) => (i === 0 ? { ...s, dir: flipDir(s.dir) } : s)),
+                sorts[0].key,
+              );
+            }}
+          />
+        )}
         <ul
           className={cn(
             "divide-y divide-[var(--border)]",

package/src/components/date-picker.tsx

@@ -7,13 +7,16 @@ import { addDaysIso, parseIsoDate } from "../lib/dates";
 import {
   DEFAULT_DATE_PICKER_LABELS,
   DEFAULT_PICKER_SHEET_LABELS,
+  useKitDateFormatter,
   useKitLabels,
   useKitLocale,
   type DatePickerLabels,
+  type KitDateFormatContext,
 } from "../i18n/kit-labels";
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
-import { Button, FieldLabel, FIELD_BASE, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui";
+import { Button, FIELD_BASE, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui";
+import { FieldBox, FieldLabelLine, useFieldMessages } from "./field-anatomy";
 import { FullBleedDialog } from "./full-bleed-dialog";
 import { useMediaQuery } from "../hooks/use-media-query";
 import { MiniCalendar, type MiniCalendarProps } from "./mini-calendar";
@@ -47,13 +50,33 @@ interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "onC
   disabled?: boolean;
   /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
   invalid?: boolean;
+  /**
+   * Standing advice for the field (keksdose K4, "uniform field anatomy"), as on a
+   * {@link Select}: plain TEXT is a caption under the field, attached with
+   * `aria-describedby`; a {@link FieldHint} rides the label line (or, unlabelled, sits
+   * at the field's end, outside the box).
+   */
+  hint?: ReactNode;
+  /**
+   * What is wrong with the date, in the caller's words ("The due date is before the
+   * invoice date") — {@link Input}'s `error` (keksdose K4: DateField errors had no slot).
+   * Rendered under the field (under the whole row, with `step` / `today`), attached to
+   * the trigger with `aria-describedby` — merged with any the caller passed, after the
+   * caption — and implies `invalid`. Passing the key at all keeps the field's box while
+   * there is no message, so the trigger is never remounted as one comes and goes.
+   */
+  error?: ReactNode;
   className?: string;
-  /** Intl options for the trigger's formatted date (default: locale short date). */
+  /** Intl options for the trigger's formatted date (default: locale short date). Win
+   *  over the provider's `formatDate`. */
   formatOptions?: Intl.DateTimeFormatOptions;
-  /** Render the trigger's text for an ISO date yourself; wins over `formatOptions`.
+  /** Render the trigger's text for an ISO date yourself; wins over `formatOptions` and
+   *  over the provider's `formatDate`.
    *  For a host whose date rendering is more than one `Intl` call can say — Keksdose
    *  puts the weekday's name in the UI language beside digits ordered by a separate
-   *  format preference, two locales in one string. `locale` still drives the calendar. */
+   *  format preference, two locales in one string. `locale` still drives the calendar.
+   *  Set that rendering once with `<UiKitProvider formatDate>` (keksdose K12) and this
+   *  is for the one field that differs. */
   formatValue?: (iso: string) => string;
   /** Passed through to the {@link MiniCalendar} this opens. Its month arrows are
    *  icon-only, so their `aria-label` is the only name they have — and the package
@@ -69,6 +92,30 @@ function formatDate(iso: string, locale: string | undefined, options?: Intl.Date
   return parseIsoDate(iso)?.toLocaleDateString(locale, options) ?? "";
 }
 
+/**
+ * The trigger's date renderer, in the kit's order of precedence: the picker's own
+ * `formatValue`, then its `formatOptions` (an explicit `Intl` look for this field),
+ * then the provider's `formatDate` (keksdose K12), then the locale's short date. A
+ * provider formatter that answers `""` falls through to the default for that date.
+ */
+function useTriggerFormat(
+  source: KitDateFormatContext["source"],
+  locale: string | undefined,
+  formatOptions: Intl.DateTimeFormatOptions | undefined,
+  formatValue: ((iso: string) => string) | undefined,
+): (iso: string) => string {
+  const fromProvider = useKitDateFormatter();
+  if (formatValue) return formatValue;
+  return (iso) => {
+    if (formatOptions === undefined && fromProvider) {
+      // A single date stands alone, where the weekday helps; a range's two ends do not.
+      const text = fromProvider(iso, { unit: "day", source, locale, weekday: source === "datePicker" });
+      if (text) return text;
+    }
+    return formatDate(iso, locale, formatOptions);
+  };
+}
+
 /**
  * Everything the kit's own trigger button carries, handed to a custom one
  * ({@link DateRangePickerProps.renderTrigger}) to spread onto its `<button>`. Spread
@@ -285,6 +332,7 @@ function DateField({
   sheet = false,
   sheetBackCloses = true,
   renderTrigger,
+  labelHint,
   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.
@@ -295,6 +343,8 @@ function DateField({
   triggerText: string;
   hasValue: boolean;
   label?: ReactNode;
+  /** A `FieldHint` for the label line, beside the label. */
+  labelHint?: ReactNode;
   disabled?: boolean;
   clearable?: boolean;
   /** Already resolved by the picker (prop > provider > English). */
@@ -412,7 +462,7 @@ function DateField({
     // The caller's attributes land here, on the field's own box — the trigger inside is
     // named by `aria-labelledby` and must keep the id pair it is given.
     <div {...wrapperRest} ref={rootRef} className={cn("relative", className)}>
-      {label !== undefined && <FieldLabel>{label}</FieldLabel>}
+      {label !== undefined && <FieldLabelLine label={label} hint={labelHint} />}
       {/* The visible FieldLabel is a plain span, not a `<label htmlFor>`, so it names
           nothing on its own — this hidden twin is what the trigger is named by.
           `aria-hidden` because a name reference reads a hidden element deliberately
@@ -568,35 +618,61 @@ function useDatePickerLabels(
   return useKitLabels("datePicker", DEFAULT_DATE_PICKER_LABELS, fromProps);
 }
 
+/**
+ * The caller's `hint` when it has no label line to ride: at the end of the field,
+ * outside the box, as an unlabelled {@link Select} places its FieldHint (0.15.5 P8).
+ */
+function withEndHint(field: ReactNode, hint: ReactNode): ReactNode {
+  if (hint === undefined) return field;
+  return (
+    <div className="flex items-center gap-1.5">
+      <div className="min-w-0 flex-1">{field}</div>
+      <span className="flex shrink-0 items-center">{hint}</span>
+    </div>
+  );
+}
+
 /** Single-date picker: a field showing the formatted date, opening a calendar. */
-export function DatePicker({
-  value,
-  onChange,
-  locale: localeProp,
-  placeholder,
-  min,
-  max,
-  formatOptions,
-  formatValue,
-  step,
-  stepLabels,
-  today,
-  todayLabel,
-  className,
-  calendarLabels,
-  label,
-  clearable,
-  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) {
+export function DatePicker(props: DatePickerProps) {
+  const {
+    value,
+    onChange,
+    locale: localeProp,
+    placeholder,
+    min,
+    max,
+    formatOptions,
+    formatValue,
+    step,
+    stepLabels,
+    today,
+    todayLabel,
+    className,
+    calendarLabels,
+    label,
+    clearable,
+    clearLabel,
+    disabled,
+    invalid,
+    hint,
+    error,
+    // 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
+  } = props;
   const locale = useKitLocale(localeProp);
   const text = useDatePickerLabels(clearLabel, stepLabels, todayLabel);
-  const render = formatValue ?? ((iso: string) => formatDate(iso, locale, formatOptions));
+  const render = useTriggerFormat("datePicker", locale, formatOptions, formatValue);
+  // keksdose K4: the caption and the error under the field, attached to the TRIGGER
+  // (the element a screen reader is on) after any description of the caller's own.
+  const messages = useFieldMessages({
+    hint,
+    error,
+    invalid,
+    describedBy: rest["aria-describedby"],
+    ariaInvalid: rest["aria-invalid"],
+  });
   // With a step or a today button beside it the field is no longer the outermost
   // element — the flex row at the bottom is, and a caller's attributes belong on
   // whichever of the two is actually the root. Naming the shared props rather than
@@ -608,13 +684,15 @@ 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-describedby={messages.describedBy}
       aria-required={ariaRequired}
       label={label}
+      labelHint={messages.labelHint}
       clearable={clearable}
       clearLabel={text.clear}
       panelLabel={text.panel}
       disabled={disabled}
-      invalid={invalid}
+      invalid={messages.isInvalid}
       className={step ? "min-w-0 flex-1" : className}
       hasValue={Boolean(value)}
       triggerText={value ? render(value) : (placeholder ?? "")}
@@ -638,7 +716,16 @@ export function DatePicker({
       )}
     </DateField>
   );
-  if (!wrapped) return field;
+  // Passed at all — even as `undefined` — the field keeps its box; see FieldBox.
+  const reserve = "error" in props || "hint" in props;
+  const endHint = label === undefined ? messages.labelHint : undefined;
+  if (!wrapped) {
+    return (
+      <FieldBox below={messages.below} reserve={reserve}>
+        {withEndHint(field, endHint)}
+      </FieldBox>
+    );
+  }
 
   // An empty field has nothing to step from, so both buttons are dead until a date
   // is picked. Bounds are compared as strings: "YYYY-MM-DD" sorts chronologically.
@@ -649,7 +736,7 @@ export function DatePicker({
     if (!next || disabled) return true;
     return outOfBounds(next);
   };
-  return (
+  const row = (
     // ONE joined control, not three boxes in a row: the buttons and the field share
     // their borders (each piece overlaps the previous by a pixel) and only the outer
     // ends are rounded — the button-group shape, so ‹ date › reads as one field with
@@ -701,6 +788,13 @@ export function DatePicker({
       )}
     </div>
   );
+  // Under the whole row, not under the field between the buttons: the message is about
+  // the date, and the steppers are part of how it is entered.
+  return (
+    <FieldBox below={messages.below} reserve={reserve}>
+      {withEndHint(row, endHint)}
+    </FieldBox>
+  );
 }
 
 export interface DateRangePickerPreset {
@@ -1052,34 +1146,44 @@ function RangePanel({
 /** Two-date range picker: click a start then an end; closes once both are set.
  *  With `presets`, a column of named ranges is shown beside the calendar; with
  *  `commit="apply"` the panel drafts and commits on Apply (see {@link DateRangeCommit}). */
-export function DateRangePicker({
-  from,
-  to,
-  onChange,
-  locale: localeProp,
-  placeholder,
-  min,
-  max,
-  formatOptions,
-  formatValue,
-  separator = " – ",
-  presets,
-  preset,
-  commit = "immediate",
-  renderTrigger,
-  sheetBackCloses,
-  renderDraftSummary,
-  calendarLabels,
-  label,
-  clearable,
-  clearLabel,
-  disabled,
-  invalid,
-  ...rest
-}: DateRangePickerProps) {
+export function DateRangePicker(props: DateRangePickerProps) {
+  const {
+    from,
+    to,
+    onChange,
+    locale: localeProp,
+    placeholder,
+    min,
+    max,
+    formatOptions,
+    formatValue,
+    separator = " – ",
+    presets,
+    preset,
+    commit = "immediate",
+    renderTrigger,
+    sheetBackCloses,
+    renderDraftSummary,
+    calendarLabels,
+    label,
+    clearable,
+    clearLabel,
+    disabled,
+    invalid,
+    hint,
+    error,
+    ...rest
+  } = props;
   const locale = useKitLocale(localeProp);
   const text = useDatePickerLabels(clearLabel, undefined, undefined);
-  const render = formatValue ?? ((iso: string) => formatDate(iso, locale, formatOptions));
+  const render = useTriggerFormat("dateRangePicker", locale, formatOptions, formatValue);
+  const messages = useFieldMessages({
+    hint,
+    error,
+    invalid,
+    describedBy: rest["aria-describedby"],
+    ariaInvalid: rest["aria-invalid"],
+  });
   // The preset this picker committed itself, for a caller that does not control
   // `preset`. Cleared by a hand-picked range or a clear.
   const [ownPreset, setOwnPreset] = useState<string | undefined>(undefined);
@@ -1101,15 +1205,17 @@ export function DateRangePicker({
     if (presetId === undefined) onChange(f, t);
     else onChange(f, t, presetId);
   };
-  return (
+  const field = (
     <DateField
       {...rest}
+      aria-describedby={messages.describedBy}
       label={label}
+      labelHint={messages.labelHint}
       clearable={clearable}
       clearLabel={text.clear}
       panelLabel={text.rangePanel}
       disabled={disabled}
-      invalid={invalid}
+      invalid={messages.isInvalid}
       // Widen so the preset column sits beside the calendar (default otherwise).
       width={hasPresets ? 440 : undefined}
       hasValue={Boolean(from || to)}
@@ -1150,4 +1256,9 @@ export function DateRangePicker({
       )}
     </DateField>
   );
+  return (
+    <FieldBox below={messages.below} reserve={"error" in props || "hint" in props}>
+      {withEndHint(field, label === undefined ? messages.labelHint : undefined)}
+    </FieldBox>
+  );
 }