@eifi1/ui-kit 0.15.4 → 0.16.0

package/src/components/form-actions.tsx

@@ -1,8 +1,9 @@
 import { isValidElement } from "react";
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
-import { Button, Spinner, type ButtonVariant } from "./ui";
+import { Button, Spinner, type ButtonProps, type ButtonVariant } from "./ui";
 
 /** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
 export interface FormActionsLabels {
@@ -28,6 +29,25 @@ export type FormActionsAlign = "start" | "center" | "end" | "between";
  */
 export type FormActionsPlacement = "inline" | "sticky" | "dialog";
 
+/**
+ * What a `sticky` row sticks to — see {@link FormActionsProps.stickyWithin}.
+ *  - `viewport` (default): the page's (or AppShell pane's) bottom edge, lifted onto
+ *    the phone's bottom nav by `--app-nav-h`.
+ *  - `container`: the bottom of whatever scroll container it is in — a dialog body, a
+ *    side pane, a panel with `overflow-y-auto` — at `bottom: 0`, with no nav offset.
+ */
+export type FormActionsStickyWithin = "viewport" | "container";
+
+/**
+ * Extra attributes for the save button — an `id`, `data-*` hooks for tests or
+ * analytics, an `aria-describedby`. The props FormActions drives itself (type, click,
+ * disabled, variant, form, children, the busy state) are not among them.
+ */
+export type FormActionsSubmitProps = Omit<
+  ButtonProps,
+  "type" | "onClick" | "disabled" | "disabledReason" | "variant" | "form" | "children" | "aria-busy"
+> & { [key: `data-${string}`]: string | number | boolean | undefined };
+
 /** The start-side action of {@link FormActionsProps.destructive}, as data. */
 export interface FormActionsDestructive {
   label: ReactNode;
@@ -65,10 +85,21 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
   cancelLabel?: ReactNode;
   /** The save button's text while `pending` ("Saving…"). Default: `submitLabel`. */
   pendingLabel?: ReactNode;
+  /**
+   * A Lucide icon before the save button's text. While `pending` the spinner takes
+   * ITS place rather than being added in front of it — an icon written into
+   * `submitLabel` itself stays, so the button would show the spinner AND the glyph,
+   * two statuses side by side (keksdose's crop Apply needed a `pendingLabel` copy of
+   * its text only to drop the check mark).
+   */
+  submitIcon?: LucideIcon;
+  /** Attributes passed through to the save button: `id`, `data-*`, `aria-*`, a
+   *  `className`. See {@link FormActionsSubmitProps}. */
+  submitProps?: FormActionsSubmitProps;
   /**
    * The save is running: a spinner in the save button, `aria-busy` on it, and the
    * button disabled, so a second click cannot send the form twice. Cancel stays
-   * usable.
+   * usable. The spinner goes in front of the text, or in place of {@link submitIcon}.
    */
   pending?: boolean;
   /** Disable save for a reason of the form's own (an unbalanced entry). */
@@ -85,10 +116,39 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
    * is `between`-aligned unless `align` says otherwise.
    */
   destructive?: ReactNode | FormActionsDestructive;
+  /**
+   * Something neutral at the START of the row — a caption ("Last saved 2 min ago",
+   * "Drag the corners to crop"), a "View activity" link. After {@link destructive}
+   * when both are given; like it, makes the row `between`-aligned unless `align` says
+   * otherwise. `children` are for further ACTIONS, beside Cancel.
+   */
+  start?: ReactNode;
   /** Horizontal alignment. Default `end` (`between` with a `destructive` action). */
   align?: FormActionsAlign;
   /** See {@link FormActionsPlacement}. Default `inline`. */
   placement?: FormActionsPlacement;
+  /**
+   * With `placement="sticky"`: what the row sticks to. Default `viewport`.
+   *
+   * CSS sticky always sticks to the NEAREST scroll container, so the default row
+   * already holds inside a scrolling pane — but it offsets itself by `--app-nav-h`,
+   * which AppShell publishes on the document: inside a pane or a portalled dialog
+   * body on a phone it then floats a nav's height above that container's bottom,
+   * with the content scrolling through the gap. `container` drops that offset.
+   *
+   * What neither value can fix, because it is the layout, not the row:
+   *  - sticky moves only within its PARENT box. Inside a DataTable expansion row the
+   *    parent is the expansion cell, so the row pins to the table's own scroller
+   *    (`overflow-auto`, bounded by `maxBodyHeight`) and only while the cell spans
+   *    that scroller's bottom edge — not to the page.
+   *  - any `overflow` other than `visible`/`clip` between the row and the scroller
+   *    you mean (an `overflow-x-auto` wrapper, an `overflow-hidden` card) becomes the
+   *    scroll container; if THAT box does not scroll, the row never sticks.
+   *  - the offset is resolved against the scroller's content box, so a scroller with
+   *    bottom padding leaves that strip uncovered; give the row a negative `bottom`
+   *    through `style` and the same amount back as padding.
+   */
+  stickyWithin?: FormActionsStickyWithin;
   /** The `id` of the `<form>` the save button submits, when the row is rendered
    *  outside it (a dialog's footer slot). */
   form?: string;
@@ -121,13 +181,17 @@ export function FormActions({
   submitLabel,
   cancelLabel,
   pendingLabel,
+  submitIcon: SubmitIcon,
+  submitProps,
   pending = false,
   submitDisabled = false,
   submitDisabledReason,
   submitVariant = "brand",
   destructive,
+  start: startSlot,
   align,
   placement = "inline",
+  stickyWithin = "viewport",
   form,
   children,
   className,
@@ -136,8 +200,9 @@ export function FormActions({
 }: FormActionsProps) {
   const labels = useKitLabels("form", DEFAULT_FORM_ACTIONS_LABELS);
   const hasDestructive = destructive !== undefined && destructive !== null && destructive !== false;
-  const justify = align ?? (hasDestructive ? "between" : "end");
-  const start = !hasDestructive ? null : isDestructiveData(destructive) ? (
+  const hasStart = startSlot !== undefined && startSlot !== null && startSlot !== false;
+  const justify = align ?? (hasDestructive || hasStart ? "between" : "end");
+  const destructiveNode = !hasDestructive ? null : isDestructiveData(destructive) ? (
     <Button
       type="button"
       variant="ghost"
@@ -157,6 +222,7 @@ export function FormActions({
     <div
       data-slot="form-actions"
       data-placement={placement}
+      data-sticky-within={placement === "sticky" ? stickyWithin : undefined}
       {...rest}
       style={
         placement === "sticky"
@@ -165,15 +231,22 @@ export function FormActions({
               // On the phone's bottom nav, not behind it (keksdose live #361): `bottom-0`
               // pinned the row under AppShell's nav, which covers the page's last ~56px.
               // `--app-nav-h` is the nav's measured height (0px from md up, and outside an
-              // AppShell); the 1px overlaps the two top borders into one line.
-              bottom: "max(0px, calc(var(--app-nav-h, 0px) - 1px))",
+              // AppShell); the 1px overlaps the two top borders into one line. In a
+              // container the nav is not underneath: `--app-nav-h` is the document's,
+              // and would hold the row that far above the container's own edge.
+              bottom: stickyWithin === "container" ? 0 : "max(0px, calc(var(--app-nav-h, 0px) - 1px))",
               ...style,
             }
           : style
       }
       className={cn("flex flex-wrap items-center gap-2", ALIGN_CLASS[justify], PLACEMENT_CLASS[placement], className)}
     >
-      {start && <div className="me-auto flex items-center gap-2">{start}</div>}
+      {(hasDestructive || hasStart) && (
+        <div className="me-auto flex min-w-0 flex-wrap items-center gap-2">
+          {destructiveNode}
+          {hasStart && startSlot}
+        </div>
+      )}
       <div className="flex flex-wrap items-center gap-2">
         {children}
         {onCancel && (
@@ -182,6 +255,7 @@ export function FormActions({
           </Button>
         )}
         <Button
+          {...submitProps}
           type={onSubmit ? "button" : "submit"}
           form={form}
           onClick={onSubmit}
@@ -190,7 +264,11 @@ export function FormActions({
           disabledReason={pending ? undefined : submitDisabledReason}
           aria-busy={pending || undefined}
         >
-          {pending && <Spinner label={null} className="size-4" />}
+          {pending ? (
+            <Spinner label={null} className="size-4" />
+          ) : (
+            SubmitIcon && <SubmitIcon aria-hidden className="size-4 shrink-0" />
+          )}
           {pending && pendingLabel !== undefined ? pendingLabel : saveLabel}
         </Button>
       </div>

package/src/components/line-items.tsx

@@ -39,6 +39,37 @@ export interface LineItemCellContext<T> {
    *  hidden from assistive tech (each row repeats it), so the field has to carry it:
    *  `<Input aria-label={label} … />`. */
   label: string;
+  /** The column's own name ("Debit") for the field's VISIBLE label — set only when the
+   *  cell's labels are `"floating"` (see {@link LineItemsProps.fieldLabels}), so one
+   *  render serves both modes: `<Input label={fieldLabel} aria-label={label} … />`.
+   *  Undefined there, the Input stays a bare compact control; set, it floats "Debit"
+   *  while `aria-label` still says which row. */
+  fieldLabel?: string;
+}
+
+/** How a cell's field is labelled. `aria`: the field is a bare control named by
+ *  `aria-label`, under a header row (stacked: a small copy of the header over it).
+ *  `floating`: the field shows its own floating label ({@link LineItemCellContext.fieldLabel}),
+ *  so the list draws no header for it. */
+export type LineItemsFieldLabels = "aria" | "floating";
+
+/** The colour of a {@link LineItemsSummary}'s value. */
+export type LineItemsSummaryTone = "neutral" | "success" | "danger" | "muted";
+
+/**
+ * A line under the lines that says where they stand — a split's remainder ("Left to
+ * assign  CHF 0.00", green at zero, red otherwise, muted while the total is not known
+ * yet), with an optional action that settles it ("Set amount to total").
+ */
+export interface LineItemsSummary {
+  label: ReactNode;
+  value?: ReactNode;
+  /** The value's colour. Default `neutral`. The label stays neutral: the colour is a
+   *  second signal, never the only one — the value and label carry the meaning. */
+  tone?: LineItemsSummaryTone;
+  /** A small button at the end of the line. Disabled along with the list's
+   *  `disabled`. */
+  action?: { label: ReactNode; onClick: () => void; disabled?: boolean };
 }
 
 export interface LineItemsColumn<T> {
@@ -54,6 +85,13 @@ export interface LineItemsColumn<T> {
   width?: string;
   /** `end` for figures: the header and the totals cell end-align with the field. */
   align?: "start" | "end";
+  /** This column's labelling, over the list's {@link LineItemsProps.fieldLabels} — a
+   *  read-only "Sum" cell in a floating list keeps its header with `"aria"`. */
+  fieldLabels?: LineItemsFieldLabels;
+  /** With {@link LineItemsProps.narrowColumns} `2`: `2` gives the cell a whole row of
+   *  the stacked card (a description), where short fields pair up two to a row.
+   *  Default `1`. No effect on the wide grid. */
+  narrowSpan?: 1 | 2;
   render: (ctx: LineItemCellContext<T>) => ReactNode;
 }
 
@@ -93,12 +131,30 @@ export interface LineItemsProps<T> extends Omit<ComponentPropsWithoutRef<"div">,
   empty?: ReactNode;
   /** A message about the list as a whole ("The entry does not balance"). */
   error?: ReactNode;
+  /** A line under the lines and totals — the remainder of a split, say. See
+   *  {@link LineItemsSummary}. */
+  summary?: LineItemsSummary;
+  /** How the cells' fields are labelled. Default `aria` (compact bare controls under a
+   *  header row); `floating` hands each cell its column's name as
+   *  {@link LineItemCellContext.fieldLabel} for a visible floating label, and drops the
+   *  header for those columns. A column's own `fieldLabels` wins. */
+  fieldLabels?: LineItemsFieldLabels;
+  /** Stacked (a narrow pane), how many fields share a row of a line's card: `2` pairs
+   *  them up (a column's `narrowSpan={2}` takes a whole row), once the pane is wide
+   *  enough for two fields (18rem); narrower still, one. Default `1`. */
+  narrowColumns?: 1 | 2;
   /** Disables add and remove (the fields are the caller's to disable). */
   disabled?: boolean;
   labels?: Partial<LineItemsLabels>;
 }
 
 const REMOVE_TRACK = "2.25rem";
+const SUMMARY_TONE: Record<LineItemsSummaryTone, string> = {
+  neutral: "text-[var(--text-primary)]",
+  success: "text-[var(--success)]",
+  danger: "text-[var(--danger)]",
+  muted: "text-[var(--text-muted)]",
+};
 const FOCUSABLE =
   "input:not([disabled]):not([type=hidden]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex='-1'])";
 
@@ -158,6 +214,9 @@ export function LineItems<T>({
   totalsLabel,
   empty,
   error,
+  summary,
+  fieldLabels = "aria",
+  narrowColumns = 1,
   disabled = false,
   labels: labelsProp,
   className,
@@ -228,6 +287,11 @@ export function LineItems<T>({
 
   const columnName = (column: LineItemsColumn<T>) =>
     column.label ?? (typeof column.header === "string" ? column.header : column.key);
+  const floats = (column: LineItemsColumn<T>) => (column.fieldLabels ?? fieldLabels) === "floating";
+  // A header row only for the columns that still need one: with every field floating
+  // its own label, a row of headers would say each name twice.
+  const showHeader = columns.some((c) => !floats(c));
+  const pairs = narrowColumns === 2;
 
   const headerCell = (column: LineItemsColumn<T>) => (
     <span
@@ -237,7 +301,7 @@ export function LineItems<T>({
         column.align === "end" && "text-end",
       )}
     >
-      {column.header}
+      {floats(column) ? null : column.header}
     </span>
   );
 
@@ -251,10 +315,12 @@ export function LineItems<T>({
       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>
+      {showHeader && (
+        <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)]">
@@ -280,20 +346,42 @@ export function LineItems<T>({
             onKeyDown={onRowKeyDown}
             className={cn(
               "grid grid-cols-1 gap-2 @lg:grid-cols-[var(--line-items-cols)] @lg:items-start",
+              // Two short fields to a row of the card — from 18rem, where two fields
+              // still fit a figure each; on anything narrower they stack after all.
+              pairs && "@2xs:grid-cols-2",
               // 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>
-            ))}
+            {columns.map((column) => {
+              const floating = floats(column);
+              return (
+                <div
+                  key={column.key}
+                  className={cn(
+                    "min-w-0 space-y-1 @lg:space-y-0",
+                    // The wide grid places every cell in its own track again.
+                    pairs && column.narrowSpan === 2 && "@2xs:col-span-2 @lg:col-span-1",
+                  )}
+                >
+                  {!floating && (
+                    <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),
+                    fieldLabel: floating ? columnName(column) : undefined,
+                  })}
+                </div>
+              );
+            })}
             {onRemove && (
-              <div className="flex justify-end @lg:justify-center">
+              // Paired, the remove button keeps a row of its own at the card's end
+              // rather than squeezing in beside the last field.
+              <div className={cn("flex justify-end @lg:justify-center", pairs && "@2xs:col-span-2 @lg:col-span-1")}>
                 <IconButton
                   type="button"
                   data-line-items-remove=""
@@ -361,6 +449,35 @@ export function LineItems<T>({
         </div>
       )}
 
+      {summary && (
+        <div
+          data-line-items-summary=""
+          className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-[var(--text-primary)]"
+        >
+          <span className="min-w-0">{summary.label}</span>
+          {hasContent(summary.value) && (
+            <span
+              data-tone={summary.tone ?? "neutral"}
+              className={cn("font-semibold tabular-nums", SUMMARY_TONE[summary.tone ?? "neutral"])}
+            >
+              {summary.value}
+            </span>
+          )}
+          {summary.action && (
+            <Button
+              type="button"
+              variant="secondary"
+              size="sm"
+              className="ms-auto"
+              disabled={disabled || summary.action.disabled}
+              onClick={summary.action.onClick}
+            >
+              {summary.action.label}
+            </Button>
+          )}
+        </div>
+      )}
+
       {hasError && (
         <p className="text-[11px] leading-tight text-[var(--danger)]">
           {error}