@eifi1/ui-kit 0.31.1 → 0.32.0

package/src/components/row-actions.tsx

@@ -0,0 +1,344 @@
+import { isValidElement } from "react";
+import type { ReactElement, ReactNode } from "react";
+import { MoreHorizontal } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useLargeText } from "../hooks/use-large-text";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Popover } from "./popover";
+import { Button, CompactControls, IconButton } from "./ui";
+import type { IconButtonSize } from "./ui";
+import type { DataTableColumn } from "./data-table";
+
+/**
+ * A row's actions — inline icons at Normal, one "⋯" menu at Large and above
+ * (docs/text-size-harmonization.md §10.8).
+ *
+ * At Large an IconButton shows its label as text (§4). In a dense row — a register's
+ * action column, a list row's end — every label at once does not fit: Kurvenschmiede
+ * has 44 IconButtons in rows, kastlan 119. So a row's actions collapse instead, into
+ * the menu the user roster has used since 0.31 (`UserRowActions`, now built on this):
+ * one "⋯" button, and a menu with each action's icon AND words, where a locked one stays
+ * listed and says why.
+ *
+ * The data is the roster's `UserRowActionList`, generalised: entries, and `false` /
+ * `null` for the ones a condition left out (`row.locked || {…}`).
+ */
+
+/** One action of a row. */
+export interface RowAction {
+  /** React key. Default: the label. */
+  key?: string;
+  /** The action's name: the inline icon's name and tooltip, the menu entry's words. */
+  label: string;
+  /** Runs it. The kit sends nothing — the app opens its confirmation or calls its API. */
+  onSelect: () => void;
+  /**
+   * The glyph: a Lucide icon (`Pencil`), or an element (`<Pencil />`, an app's own
+   * svg) — DataTable's `rowActions` hand their `icon` node through. Inline, an action
+   * without one is a small text button; in the menu it is the words alone.
+   */
+  icon?: LucideIcon | ReactElement;
+  /** `danger` for delete, revoke, erase: the quiet red of IconButton's `tone="danger"`
+   *  inline, the danger text tone in the menu. */
+  tone?: "default" | "danger";
+  /** Why it is not available for this row. It stays listed, focusable, and says so — an
+   *  action that silently vanished would leave the reader looking for it. */
+  disabledReason?: ReactNode;
+  /**
+   * This action COMMITS — it saves, sends, deletes: under a locked
+   * {@link WriteLockProvider} it is refused with the lock's reason, as {@link Button}'s
+   * `commit` is, inline and in the menu alike. No provider, or an unlocked one: no effect.
+   */
+  commit?: boolean;
+  /**
+   * In flight — the request it started has not answered. Inline, the icon turns into
+   * IconButton's spinner (`pending`); collapsed, the "⋯" button does, since the menu
+   * closed when the action was chosen. Either way nothing in the row can be pressed again
+   * until it settles: the "⋯" opens no menu while busy.
+   */
+  pending?: boolean;
+  /**
+   * Not available for a moment, with nothing to explain — another action of the list
+   * is in flight (an admin panel's `busy`). The plain `disabled`; a lasting refusal is a
+   * `disabledReason`, which says why.
+   */
+  disabled?: boolean;
+  /** Leave it out for this row. */
+  hidden?: boolean;
+}
+
+/** What a row's actions may be: entries, and `false` / `null` / `undefined` for the ones
+ *  a condition left out. */
+export type RowActionList = readonly (RowAction | false | null | undefined)[];
+
+export interface RowActionsLabels {
+  /** The menu button's name when the row has no name of its own; also the actions
+   *  column's (hidden) header in {@link rowActionsColumn}. */
+  actions: string;
+  /** The menu button's name, given the row's: "Actions for Ada Example". */
+  actionsFor: (name: string) => string;
+}
+
+export const DEFAULT_ROW_ACTIONS_LABELS: RowActionsLabels = {
+  actions: "Actions",
+  actionsFor: (name) => `Actions for ${name}`,
+};
+
+/**
+ * - `"auto"` (default): the icons inline at Normal; the "⋯" menu at Large and Extra
+ *   large once there are two or more (§10.8). A single action stays inline at every
+ *   size, with its label as text at Large — one label fits a row, and a menu of one is
+ *   a detour.
+ * - `"menu"`: the menu at every size — the roster's choice, whose actions grow (§2.4
+ *   there) and do not fit a phone card as a strip.
+ * - `"inline"`: the icons at every size — for a row the app knows has room; at Large
+ *   each then shows its label (IconButton's `labelVisible`).
+ */
+export type RowActionsCollapse = "auto" | "menu" | "inline";
+
+/** The sizes a row action comes in: IconButton's row steps. `2xs` is DataTable's
+ *  compact density. At Large every one is at least a 48 px target (IconButton). */
+export type RowActionsSize = Extract<IconButtonSize, "md" | "sm" | "xs" | "2xs">;
+
+export interface RowActionsProps {
+  actions: RowActionList;
+  /** The row's name, for the menu button's name — "Actions for Ada Example". Without it
+   *  the button is "Actions". */
+  name?: string;
+  /** When the actions collapse into the menu — see {@link RowActionsCollapse}. */
+  collapse?: RowActionsCollapse;
+  /** The inline icons' and the "⋯" button's size. Default `xs`, a list row's action. */
+  size?: RowActionsSize;
+  /** The menu's width. Default `"15rem"`, in rem so it grows with the words (§3.2). */
+  menuWidth?: `${number}rem`;
+  /** On the wrapper: the inline strip, or the "⋯" button's box. */
+  className?: string;
+  labels?: Partial<RowActionsLabels>;
+}
+
+function visibleActions(actions: RowActionList): RowAction[] {
+  return actions.filter((a): a is RowAction => Boolean(a) && !(a as RowAction).hidden);
+}
+
+/** An action's glyph as a node: a component is rendered, an element is used as is. */
+function glyphOf(icon: RowAction["icon"]): ReactNode {
+  if (icon === undefined) return null;
+  if (isValidElement(icon)) return icon;
+  const Icon = icon as LucideIcon;
+  return <Icon />;
+}
+
+/**
+ * A row's actions, inline or as a "⋯" menu — see {@link RowActionsCollapse}. Every
+ * control stops its click (and the Enter/Space it stands for) from reaching the row, so
+ * a clickable row or a DataTable `rowLink` does not open as well; in a DataTable column
+ * also set `noRowLink: true`, as {@link rowActionsColumn} does.
+ *
+ * Inline, the icons sit in a {@link CompactControls} region at Normal: their labels
+ * stay the names and the tooltips, and a locked one keeps its reason in the tooltip — a
+ * line under one icon of a row would break the row. In the menu a locked action's
+ * reason is a line under its words at Large and on touch (Button's
+ * `disabledReasonDisplay`).
+ *
+ * The menu is portalled, so a table's scroller cannot clip it; Escape and an outside
+ * press close it, and focus goes back to the "⋯" button, which is where a confirmation
+ * dialog then returns it.
+ */
+export function RowActions({
+  actions,
+  name,
+  collapse = "auto",
+  size = "xs",
+  menuWidth = "15rem",
+  className,
+  labels: labelsProp,
+}: RowActionsProps) {
+  const labels = useKitLabels("rowActions", DEFAULT_ROW_ACTIONS_LABELS, labelsProp);
+  const large = useLargeText();
+  const entries = visibleActions(actions);
+  if (entries.length === 0) return null;
+  const asMenu = collapse === "menu" || (collapse === "auto" && large && entries.length > 1);
+  if (!asMenu) {
+    const strip = (
+      <div data-slot="row-actions" className={cn("inline-flex items-center gap-0.5", className)}>
+        {entries.map((action) => (
+          <InlineAction key={action.key ?? action.label} action={action} size={size} />
+        ))}
+      </div>
+    );
+    // Compact at Normal (no room for a reason line in a row); at Large an inline action
+    // is the app's choice ("inline") or the row's only one, and shows its words.
+    return large ? strip : <CompactControls>{strip}</CompactControls>;
+  }
+  const title = name ? labels.actionsFor(name) : labels.actions;
+  // The menu closed when the action was chosen, so what is in flight shows on "⋯".
+  const busy = entries.some((action) => action.pending);
+  return (
+    <Popover
+      width={menuWidth}
+      aria-label={title}
+      className="p-1"
+      trigger={({ open, toggle, ref }) => (
+        <IconButton
+          ref={ref}
+          size={size}
+          label={title}
+          // "⋯" is read by everyone as "more actions"; the menu it opens is the words.
+          labelVisible={false}
+          aria-haspopup="dialog"
+          aria-expanded={open}
+          pending={busy}
+          stopPropagation
+          onClick={toggle}
+          className={className}
+        >
+          <MoreHorizontal />
+        </IconButton>
+      )}
+    >
+      {(close) => (
+        <ul data-slot="row-actions-menu" className="space-y-0.5">
+          {entries.map((action) => {
+            const glyph = glyphOf(action.icon);
+            return (
+              <li key={action.key ?? action.label}>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  stretch
+                  tone={action.tone === "danger" ? "danger" : undefined}
+                  disabledReason={action.disabledReason}
+                  commit={action.commit}
+                  pending={action.pending}
+                  disabled={action.disabled}
+                  className="w-full justify-start text-start"
+                  onClick={() => {
+                    close();
+                    action.onSelect();
+                  }}
+                >
+                  {glyph && (
+                    <span aria-hidden className="flex shrink-0 [&_svg]:size-4">
+                      {glyph}
+                    </span>
+                  )}
+                  {action.label}
+                </Button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </Popover>
+  );
+}
+
+/** One inline action: an IconButton with its icon, else a small text button. */
+function InlineAction({ action, size }: { action: RowAction; size: RowActionsSize }) {
+  const glyph = glyphOf(action.icon);
+  if (glyph) {
+    return (
+      <IconButton
+        size={size}
+        label={action.label}
+        tone={action.tone === "danger" ? "danger" : undefined}
+        disabledReason={action.disabledReason}
+        commit={action.commit}
+        pending={action.pending}
+        disabled={action.disabled}
+        stopPropagation
+        onClick={action.onSelect}
+      >
+        {glyph}
+      </IconButton>
+    );
+  }
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="sm"
+      tone={action.tone === "danger" ? "danger" : undefined}
+      disabledReason={action.disabledReason}
+      commit={action.commit}
+      pending={action.pending}
+      disabled={action.disabled}
+      onClick={(e) => {
+        // A row listening for clicks must not open as well (IconButton's stopPropagation).
+        e.stopPropagation();
+        action.onSelect();
+      }}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") e.stopPropagation();
+      }}
+    >
+      {action.label}
+    </Button>
+  );
+}
+
+/** The actions column's hidden header, in the provider's words. */
+function RowActionsHeader({ text, labels }: { text?: string; labels?: Partial<RowActionsLabels> }) {
+  const resolved = useKitLabels("rowActions", DEFAULT_ROW_ACTIONS_LABELS, labels);
+  return <span className="sr-only">{text ?? resolved.actions}</span>;
+}
+
+export interface RowActionsColumnOptions<T> {
+  /** The column's key. Default `"actions"`. */
+  key?: string;
+  /** The row's actions — `false` / `null` for the ones a condition leaves out. */
+  actions: (row: T) => RowActionList;
+  /** The row's name, for the "⋯" button's name ("Actions for Ada Example"). */
+  name?: (row: T) => string | undefined;
+  collapse?: RowActionsCollapse;
+  /** Default `xs`. */
+  size?: RowActionsSize;
+  /**
+   * The column's name as plain text — the column-settings checklist and the phone
+   * card's label read it (`DataTableColumn.headerText`). Pass the app's own word; left
+   * out, the header shows the provider's `rowActions.actions` to a screen reader and
+   * the plain-text places fall back to the column's `key`.
+   */
+  headerText?: string;
+  labels?: Partial<RowActionsLabels>;
+  /** Anything else for the column (`mobileHidden`, `cellProps`…), merged last. */
+  column?: Partial<DataTableColumn<T>>;
+}
+
+/**
+ * A DataTable column of {@link RowActions} — an app's action column in one line
+ * (§10.8): inline icons at Normal, the "⋯" menu at Large with two or more actions.
+ *
+ *     columns={[...columns, rowActionsColumn({ actions: (r) => [...], name: (r) => r.name })]}
+ *
+ * The header is visually hidden (the icons say what the column is), the column hugs its
+ * content at the row's end, and `noRowLink` keeps a `rowHref` anchor off it, so the
+ * buttons keep their own clicks. On a phone it is a line of the card like any column;
+ * set `column: { mobileHidden: true }` to drop it there (with `mobileDetailsInRow` it
+ * then shows in the opened row instead).
+ */
+export function rowActionsColumn<T>({
+  key = "actions",
+  actions,
+  name,
+  collapse,
+  size,
+  headerText,
+  labels,
+  column,
+}: RowActionsColumnOptions<T>): DataTableColumn<T> {
+  return {
+    key,
+    header: <RowActionsHeader text={headerText} labels={labels} />,
+    headerText,
+    cell: (row) => (
+      <RowActions actions={actions(row)} name={name?.(row)} collapse={collapse} size={size} labels={labels} />
+    ),
+    className: "w-px whitespace-nowrap text-end",
+    headClassName: "w-px",
+    noRowLink: true,
+    ...column,
+  };
+}

package/src/components/scroll-area.tsx

@@ -121,7 +121,7 @@ export function ScrollArea({
         // a row with its own background would cover exactly the part of the ring that
         // says where focus is. An outline paints above it, and the negative offset
         // keeps it inside a parent that clips.
-        "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
+        "focus-visible:outline-[length:var(--focus-ring-width)] focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
         className,
       )}
     />

package/src/components/search-field.tsx

@@ -2,7 +2,7 @@ import { forwardRef, useRef } from "react";
 import type { InputHTMLAttributes } from "react";
 import { Search, X } from "lucide-react";
 import { cn } from "../lib/cn";
-import { FIELD_BASE } from "./ui";
+import { FIELD_BASE, FIELD_TOUCH_TEXT } from "./ui";
 import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 
 interface SearchFieldOwnProps
@@ -62,7 +62,9 @@ interface SearchFieldOwnProps
 // itself) without even its baseline, because the header it sits in already draws
 // the line. No `text-*` size, on purpose — the input inherits the caller's.
 const SEARCH_INLINE =
-  "block w-full min-w-0 border-0 bg-transparent py-1 text-[var(--text-primary)] shadow-none placeholder:text-[var(--text-placeholder)] focus:outline-none focus:ring-0";
+  "block w-full min-w-0 border-0 bg-transparent py-1 text-[var(--text-primary)] shadow-none placeholder:text-[var(--text-placeholder)] focus:outline-none focus:ring-0 " +
+  // FIELD_BASE carries the 16 px touch floor (§10.1); the inline look needs it too.
+  FIELD_TOUCH_TEXT;
 
 /**
  * One of the two spellings is REQUIRED, and the union is how that survives the

package/src/components/series-chart-budget.ts

@@ -26,7 +26,8 @@ interface BudgetAxis {
 }
 
 /**
- * The narrowest the plot may get before the automatic budget steps in, in px.
+ * The narrowest the plot may get before the automatic budget steps in, in px at Normal —
+ * × the text size's scale since 0.32 (see {@link autoAxisBudget}).
  *
  * About a phone's plot with one axis a side (390 px viewport, card padding, two bands
  * of 48 + 16), where a curve's shape still reads. It is the point below which the chart
@@ -38,6 +39,12 @@ export const MIN_PLOT_WIDTH = 160;
 /** The budget the automatic rule applies: one axis a side. */
 export const NARROW_AXIS_BUDGET: SeriesChartAxisBudget = { left: 1, right: 1 };
 
+/**
+ * The automatic rule's second step: the left axis alone — for a chart with an axis on
+ * each side that even one a side leaves too little plot (0.32, see {@link autoAxisBudget}).
+ */
+export const LEFT_AXIS_BUDGET: SeriesChartAxisBudget = { left: 1, right: 0 };
+
 /** The plot's margin on a side no axis band covers — `SeriesPlot`'s own. */
 const BARE_SIDE_MARGIN = 10;
 
@@ -85,10 +92,27 @@ export function budgetedAxes(
 }
 
 /**
- * The automatic budget for a chart `width` px wide: {@link NARROW_AXIS_BUDGET} when the
- * visible axes' bands would leave the plot under {@link MIN_PLOT_WIDTH} AND some side
- * draws more than one axis — the only case one-a-side gives anything back. `undefined`
- * otherwise, and for a width that is not known (no layout, no `ResizeObserver`).
+ * The automatic budget for a chart `width` px wide, in two steps — each taken only when
+ * the plot would otherwise be narrower than {@link MIN_PLOT_WIDTH} × `scale`:
+ *
+ * 1. {@link NARROW_AXIS_BUDGET}, one axis a side, when some side draws more than one
+ *    (lenkbank's four-axis curve plot on a phone);
+ * 2. {@link LEFT_AXIS_BUDGET}, the left axis alone, when the chart has an axis on EACH
+ *    side and one a side still leaves the plot too narrow (0.32,
+ *    docs/text-size-harmonization.md §4, §10.10). At 150 % a 390 px phone's two bands
+ *    are 96 px each and the plot kept about 80 px. The right-hand axis is the secondary
+ *    one — the grid hangs its rules off the left — so it goes: its lines keep their own
+ *    scale, and its unit moves into the tooltip, the readout and the legend
+ *    ({@link axisUnit}, `seriesLegendEntries`), where its values stay readable.
+ *
+ * `scale` is the text size's (`useTextSize().scale`): the bands grow with the type
+ * (`bandWidth` is handed the scaled ones), and so does the floor (§3.2, "a chart's axis
+ * width and tick spacing are multiplied by `scale`") — the room a curve needs between
+ * labels grows with the labels.
+ *
+ * `undefined` when neither step is needed, for a single-axis chart (a facing pair's two
+ * charts each have one) and for a width that is not known (no layout, no
+ * `ResizeObserver`).
  *
  * Decided on the CHART's width and the axes as declared, never on the plot the budget
  * produced, so hiding an axis cannot widen the plot back over the line and bring it
@@ -98,15 +122,23 @@ export function autoAxisBudget(
   axes: readonly BudgetAxis[],
   width: number | undefined,
   bandWidth: (axis: BudgetAxis) => number,
+  scale = 1,
 ): SeriesChartAxisBudget | undefined {
   if (width === undefined || !(width > 0)) return undefined;
   const visible = axes.filter((axis) => !axis.hide);
   const left = visible.filter((axis) => sideOf(axis) === "left");
   const right = visible.filter((axis) => sideOf(axis) === "right");
+  const floor = MIN_PLOT_WIDTH * scale;
+  /** The plot's width with `drawn` axes drawn: what their bands and the bare sides leave. */
+  const plot = (drawn: readonly BudgetAxis[]) => {
+    const onLeft = drawn.some((axis) => sideOf(axis) === "left");
+    const onRight = drawn.some((axis) => sideOf(axis) === "right");
+    const bands = drawn.reduce((sum, axis) => sum + bandWidth(axis), 0);
+    return width - bands - (onLeft ? 0 : BARE_SIDE_MARGIN) - (onRight ? 0 : BARE_SIDE_MARGIN);
+  };
+  if (left.length && right.length && plot([left[0], right[0]]) < floor) return LEFT_AXIS_BUDGET;
   if (left.length <= 1 && right.length <= 1) return undefined;
-  const bands = visible.reduce((sum, axis) => sum + bandWidth(axis), 0);
-  const margins = (left.length ? 0 : BARE_SIDE_MARGIN) + (right.length ? 0 : BARE_SIDE_MARGIN);
-  return width - bands - margins < MIN_PLOT_WIDTH ? NARROW_AXIS_BUDGET : undefined;
+  return plot(visible) < floor ? NARROW_AXIS_BUDGET : undefined;
 }
 
 /**

package/src/components/series-chart-ticks.ts

@@ -12,6 +12,16 @@
  *  to about twice this, which is the price of every tick being a round number. */
 const TARGET_TICKS = 5;
 
+/** The aim at Large and Extra large (docs/text-size-harmonization.md §4): the labels are
+ *  25–50 % wider and taller, so five of them crowd an axis that holds them at Normal. */
+export const LARGE_TEXT_TARGET_TICKS = 3;
+
+/** How many ticks to aim for at a text `scale` (`useTextSize().scale`): five at Normal,
+ *  three from Large up. */
+export function tickTarget(scale = 1): number {
+  return scale > 1 ? LARGE_TEXT_TARGET_TICKS : TARGET_TICKS;
+}
+
 /** The round step closest to `span / target`: 1, 2 or 5 times a power of ten. */
 export function niceStep(span: number, target: number = TARGET_TICKS): number {
   const rough = span / Math.max(1, target);