@eifi1/ui-kit 0.15.5 → 0.16.0

package/dist/shell/top-bar-brand.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { aB as KitLinkProps, aA as KitLinkComponent } from '../kit-labels-BD2F7sOz.js';
+import { aE as KitLinkProps, aD as KitLinkComponent } from '../kit-labels-DE--LmCk.js';
 import '../components/data-table-labels.js';
 import '../components/mini-calendar.js';
 import '../components/calendar-heatmap.js';
@@ -32,7 +32,7 @@ import '../components/dialog-frame.js';
 import '../components/modal.js';
 import '../hooks/use-search-param-state.js';
 import '../components/measured-grid.js';
-import '../feedback-attachment-BYAHJMOr.js';
+import '../feedback-attachment-WFiXJ8We.js';
 import '../feedback/feedback-thread.js';
 import '../feedback/feedback-inbox.js';
 import '../components/account-settings-labels.js';
@@ -40,12 +40,12 @@ import '../components/confirm-dialog.js';
 import '../components/floating-panel.js';
 import '../components/bulk-action-bar.js';
 import '../components/list.js';
+import '../components/signed-amount.js';
 import '../components/breadcrumbs.js';
 import '../components/toast.js';
 import '../components/description-list.js';
 import '../components/line-items.js';
 import '../components/progress-bar.js';
-import '../components/signed-amount.js';
 import '../components/error-boundary.js';
 import '../components/authed-image.js';
 import '../hooks/use-authed-src.js';

package/dist/shell.d.ts

@@ -13,7 +13,7 @@ import './theme/theme-store.js';
 import 'zustand/middleware';
 import 'zustand';
 import 'lucide-react';
-import './kit-labels-BD2F7sOz.js';
+import './kit-labels-DE--LmCk.js';
 import './components/data-table-labels.js';
 import './components/mini-calendar.js';
 import './components/calendar-heatmap.js';
@@ -44,7 +44,7 @@ import './components/dialog-frame.js';
 import './components/modal.js';
 import './hooks/use-search-param-state.js';
 import './components/measured-grid.js';
-import './feedback-attachment-BYAHJMOr.js';
+import './feedback-attachment-WFiXJ8We.js';
 import './feedback/feedback-thread.js';
 import './feedback/feedback-inbox.js';
 import './components/account-settings-labels.js';
@@ -52,12 +52,12 @@ import './components/confirm-dialog.js';
 import './components/floating-panel.js';
 import './components/bulk-action-bar.js';
 import './components/list.js';
+import './components/signed-amount.js';
 import './components/breadcrumbs.js';
 import './components/toast.js';
 import './components/description-list.js';
 import './components/line-items.js';
 import './components/progress-bar.js';
-import './components/signed-amount.js';
 import './components/error-boundary.js';
 import './components/authed-image.js';
 import './hooks/use-authed-src.js';

package/dist/wizard/stepper-nav.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
-import { f as ButtonVariant } from '../kit-labels-BD2F7sOz.js';
+import { f as ButtonVariant } from '../kit-labels-DE--LmCk.js';
 import { UseWizardReturn, WizardLabels } from './types.js';
 import '../components/data-table-labels.js';
 import '../components/mini-calendar.js';
@@ -32,7 +32,7 @@ import '../components/dialog-frame.js';
 import '../components/modal.js';
 import '../hooks/use-search-param-state.js';
 import '../components/measured-grid.js';
-import '../feedback-attachment-BYAHJMOr.js';
+import '../feedback-attachment-WFiXJ8We.js';
 import '../feedback/feedback-thread.js';
 import '../feedback/feedback-inbox.js';
 import '../components/account-settings-labels.js';
@@ -40,12 +40,12 @@ import '../components/confirm-dialog.js';
 import '../components/floating-panel.js';
 import '../components/bulk-action-bar.js';
 import '../components/list.js';
+import '../components/signed-amount.js';
 import '../components/breadcrumbs.js';
 import '../components/toast.js';
 import '../components/description-list.js';
 import '../components/line-items.js';
 import '../components/progress-bar.js';
-import '../components/signed-amount.js';
 import '../components/error-boundary.js';
 import '../components/authed-image.js';
 import '../hooks/use-authed-src.js';

package/dist/wizard.d.ts

@@ -6,7 +6,7 @@ export { WizardStep, WizardStepProps } from './wizard/wizard-step.js';
 export { WizardSummary } from './wizard/wizard-summary.js';
 export { StepperNav } from './wizard/stepper-nav.js';
 import 'react';
-import './kit-labels-BD2F7sOz.js';
+import './kit-labels-DE--LmCk.js';
 import './components/data-table-labels.js';
 import './components/mini-calendar.js';
 import './components/calendar-heatmap.js';
@@ -37,7 +37,7 @@ import './components/dialog-frame.js';
 import './components/modal.js';
 import './hooks/use-search-param-state.js';
 import './components/measured-grid.js';
-import './feedback-attachment-BYAHJMOr.js';
+import './feedback-attachment-WFiXJ8We.js';
 import './feedback/feedback-thread.js';
 import './feedback/feedback-inbox.js';
 import './components/account-settings-labels.js';
@@ -45,12 +45,12 @@ import './components/confirm-dialog.js';
 import './components/floating-panel.js';
 import './components/bulk-action-bar.js';
 import './components/list.js';
+import './components/signed-amount.js';
 import './components/breadcrumbs.js';
 import './components/toast.js';
 import './components/description-list.js';
 import './components/line-items.js';
 import './components/progress-bar.js';
-import './components/signed-amount.js';
 import './components/error-boundary.js';
 import './components/authed-image.js';
 import './hooks/use-authed-src.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "type": "module",
   "description": "App-agnostic shared design system: domain-free React components, theme and tokens.",
   "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives. Re-checked when `flag-icons` left `dependencies` and tsup started emitting a `\"use client\"` banner: neither touches this. The flag stylesheet was never imported from JS in the first place (that was the finding), and a directive prologue is a string literal every bundler lifts out before it decides whether a module is inert.",

package/src/components/amount-input.tsx

@@ -2,7 +2,7 @@ import { forwardRef, useCallback, useId, useMemo, useRef, useState } from "react
 import { ChevronDown } from "lucide-react";
 import type { ReactNode } from "react";
 import { CURRENCIES, CurrencyFlag, currencyName, getCurrency } from "./currency-select";
-import { FIELD_BASE, FIELD_DISPLAY, FIELD_INVALID, FLOATING_INPUT_CLASS, FLOATING_LABEL_CLASS, PHONE_QUERY } from "./ui";
+import { FIELD_BASE, FIELD_DISPLAY, FIELD_INVALID, FLOATING_INPUT_CLASS, FloatingField, PHONE_QUERY } from "./ui";
 import { cn } from "../lib/cn";
 import { currencyMinorDigits } from "../lib/format";
 import { useMediaQuery } from "../hooks/use-media-query";
@@ -48,6 +48,13 @@ interface AmountInputProps {
   "aria-describedby"?: string;
   "aria-invalid"?: boolean | "true" | "false";
   "aria-required"?: boolean | "true" | "false";
+  /** {@link NumberInput}'s `hint`, the same rule: a {@link FieldHint} "?" rides the
+   *  label's own line, beside the label (not at the far end, where the calculator and
+   *  the currency chip live); plain TEXT (a string or a number) is a caption UNDER
+   *  the field, attached through `aria-describedby` after the caller's own. A phone's
+   *  `variant="display"` has no visible label, so a FieldHint is dropped there; a
+   *  caption still shows. */
+  hint?: ReactNode;
   /** Every user-facing string this component and the two it composes own, so a
    *  translating host can supply its own. Each key optional, and each a per-field
    *  override of the kit-wide translation in `<UiKitProvider labels>`: `currency`
@@ -296,9 +303,13 @@ function isResultOf(previous: string, text: string, settle: (text: string) => st
 }
 
 export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
-  ({ value, onChange, currency, onCurrencyChange, placeholder, label, disabled, invalid: invalidProp, className, id, ariaLabel, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, autoFocus, tone = "neutral", negative = false, onNegativeChange, variant = "field", align = "start", labels, currencyNames, digits: digitsProp, min, max, onCommit }, ref) => {
+  ({ value, onChange, currency, onCurrencyChange, placeholder, label, disabled, invalid: invalidProp, className, id, ariaLabel, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, hint, autoFocus, tone = "neutral", negative = false, onNegativeChange, variant = "field", align = "start", labels, currencyNames, digits: digitsProp, min, max, onCommit }, ref) => {
     const generatedId = useId();
     const fieldId = id ?? generatedId;
+    const hintId = useId();
+    // Text is a caption under the field; a FieldHint rides the label line. See `hint`.
+    const textHint = (typeof hint === "string" && hint !== "") || typeof hint === "number";
+    const describedBy = textHint ? (ariaDescribedBy ? `${ariaDescribedBy} ${hintId}` : hintId) : ariaDescribedBy;
     const invalid = Boolean(invalidProp) || ariaInvalid === true || ariaInvalid === "true";
     const editable = !!onCurrencyChange;
     // On phones we suppress the OS keyboard (inputMode="none" below) and show our
@@ -454,8 +465,17 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
       <div ref={wrapperRef} className={cn("w-full", className)}>
         {/* Inner relative box holds the input + its absolutely-positioned
             trailing controls (calculator / currency), so those stay anchored to
-            the INPUT even when the mobile math bar is rendered below (#334). */}
-        <div className="relative w-full">
+            the INPUT even when the mobile math bar is rendered below (#334). It is
+            the kit's FloatingField, which draws the label — floating, or sr-only in
+            the display shape — and puts a FieldHint on the label's line, as it does
+            for NumberInput. */}
+        <FloatingField
+          className="w-full"
+          htmlFor={fieldId}
+          label={label}
+          srOnlyLabel={asDisplay}
+          hint={textHint ? undefined : hint}
+        >
         <input
           ref={setRefs}
           id={fieldId}
@@ -513,18 +533,15 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
             invalid && FIELD_INVALID,
           )}
           aria-invalid={invalid || undefined}
-          aria-describedby={ariaDescribedBy}
+          aria-describedby={describedBy}
           aria-required={ariaRequired}
         />
-        {label !== undefined && (
-          // The display shape drops the label VISUALLY, not from the accessibility
-          // tree: a 36px tinted figure at the top of a transaction form is legibly
-          // the amount, but a screen reader still needs the name, and callers that
-          // pass `label` without `ariaLabel` would otherwise be left with none.
-          <label htmlFor={fieldId} className={asDisplay ? "sr-only" : FLOATING_LABEL_CLASS}>
-            {label}
-          </label>
-        )}
+        {/* The label is FloatingField's, after these children (the floating trick
+            reads the input through `peer-*`). The display shape drops it VISUALLY,
+            not from the accessibility tree: a 36px tinted figure at the top of a
+            transaction form is legibly the amount, but a screen reader still needs
+            the name, and callers that pass `label` without `ariaLabel` would
+            otherwise be left with none. */}
         {/* Trailing controls share one flex track so the calculator icon and the
             currency suffix/picker sit side by side without overlapping. */}
         {/* The display shape has no box to inset from, so the controls align to the
@@ -627,7 +644,14 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
               })}
           </DropdownPanel>
         )}
-        </div>
+        </FloatingField>
+        {/* Outside the relative box, as NumberInput's caption is: the trailing
+            controls are `inset-y-1` in it and would stretch down over a second line. */}
+        {textHint && (
+          <p id={hintId} className="mt-1 text-[11px] leading-tight text-[var(--text-muted)]">
+            {hint}
+          </p>
+        )}
         {showNumpad && (
           <NumberPadSheet
             // Localised like the field it mirrors. Keys are typing, read by the

package/src/components/authed-image.tsx

@@ -44,8 +44,18 @@ export interface AuthedImageProps
   link?: boolean;
   /** Replaces the default skeleton while loading. */
   loadingFallback?: ReactNode;
-  /** Replaces the default "couldn't load" tile. */
+  /**
+   * Replaces the default "couldn't load" tile. `null` renders nothing in its place —
+   * an optional photo slot that simply stays empty; only `undefined` (left out) means
+   * the default tile.
+   */
   errorFallback?: ReactNode;
+  /**
+   * Keep a click on the image (and the Enter that follows its `link`) from reaching an
+   * ancestor — a thumbnail in a DataTable row or a clickable card opens itself instead
+   * of also running the row's action. As TextLink's and IconButton's `stopPropagation`.
+   */
+  stopPropagation?: boolean;
   labels?: Partial<AuthedImageLabels>;
 }
 
@@ -68,6 +78,7 @@ export function AuthedImage({
   link,
   loadingFallback,
   errorFallback,
+  stopPropagation,
   labels: labelsProp,
   onLoad,
   onError,
@@ -85,6 +96,7 @@ export function AuthedImage({
       link={link}
       loadingFallback={loadingFallback}
       errorFallback={errorFallback}
+      stopPropagation={stopPropagation}
       imgProps={rest}
       onLoad={onLoad}
       onError={onError}
@@ -106,6 +118,7 @@ export function ImageStates({
   link,
   loadingFallback,
   errorFallback,
+  stopPropagation,
   imgProps,
   onLoad,
   onError,
@@ -118,6 +131,7 @@ export function ImageStates({
   link?: boolean;
   loadingFallback?: ReactNode;
   errorFallback?: ReactNode;
+  stopPropagation?: boolean;
   imgProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "children" | "onLoad" | "onError">;
   onLoad?: ImgHTMLAttributes<HTMLImageElement>["onLoad"];
   onError?: ImgHTMLAttributes<HTMLImageElement>["onError"];
@@ -153,7 +167,10 @@ export function ImageStates({
   );
 
   return (
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- not an interaction: only fences the image's own clicks off from an ancestor's handler
     <span
+      onClick={stopPropagation ? (e) => e.stopPropagation() : undefined}
+      onKeyDown={stopPropagation ? (e) => e.key === "Enter" && e.stopPropagation() : undefined}
       data-image-state={failed ? "error" : waiting ? "loading" : fetched.status === "idle" ? "idle" : "ready"}
       className={cn("relative block overflow-hidden", wrapperClassName)}
       aria-busy={waiting || undefined}
@@ -172,7 +189,8 @@ export function ImageStates({
           </span>
         ))}
       {failed &&
-        (errorFallback ?? (
+        // `=== undefined`, not `??`: `null` is the caller asking for nothing at all.
+        (errorFallback !== undefined ? errorFallback : (
           <span
             // `role="img"` with the alt as its name: the picture that failed still
             // occupies its place in the reading order, and "couldn't be loaded" is

package/src/components/file-button.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, useRef, useState } from "react";
+import { forwardRef, useId, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, DragEvent, ReactElement, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
 import { useAnnounce } from "../hooks/use-announce";
@@ -418,6 +418,15 @@ export interface FileButtonProps
    *  Off by default: a button that silently takes drops is a surprise on a page that
    *  has a real drop target elsewhere. */
   droppable?: boolean;
+  /**
+   * Show what was picked beside the button: the file's name, or "3 files selected"
+   * (`filePicker.selected`) for several — a native `<input type="file">` says this,
+   * and a bare button that takes a file and says nothing leaves the user to trust it.
+   * The read-out is a polite live region and describes the button, so it is heard
+   * when it changes and again on focus. It holds the last ACCEPTED pick: a refused
+   * file leaves it as it was. Off by default, so the button's layout is unchanged.
+   */
+  showFileName?: boolean;
 }
 
 /**
@@ -447,6 +456,7 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
     labels,
     pending,
     droppable,
+    showFileName = false,
     disabled,
     children,
     className,
@@ -460,6 +470,9 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
   ref,
 ) {
   const inert = Boolean(disabled || pending);
+  const [picked, setPicked] = useState<readonly File[]>([]);
+  const pickedId = useId();
+  const pickerLabels = useKitLabels("filePicker", DEFAULT_FILE_PICKER_LABELS, labels);
   const picker = useFilePicker({
     accept,
     multiple,
@@ -468,12 +481,19 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
     maxFiles,
     isValid,
     invalidMessage,
-    onFiles,
+    onFiles: showFileName
+      ? (files) => {
+          setPicked(files);
+          onFiles?.(files);
+        }
+      : onFiles,
     onPick,
     onReject,
     labels,
     disabled: inert,
   });
+  const pickedText =
+    picked.length === 0 ? "" : picked.length === 1 ? picked[0].name : pickerLabels.selected(picked.length, picked[0].name);
   const [dragOver, setDragOver] = useState(false);
 
   const hasFiles = (e: DragEvent) => Array.from(e.dataTransfer?.types ?? []).includes("Files");
@@ -514,34 +534,64 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
   // declare it, hence the widening here rather than a second button implementation.
   const refProp = { ref } as { ref?: Ref<HTMLButtonElement> };
 
+  const button = (
+    <Button
+      {...rest}
+      {...refProp}
+      {...dropHandlers}
+      type="button"
+      disabled={inert}
+      aria-busy={pending || undefined}
+      aria-describedby={
+        showFileName && pickedText
+          ? [rest["aria-describedby"], pickedId].filter(Boolean).join(" ")
+          : rest["aria-describedby"]
+      }
+      data-drag-over={dragOver || undefined}
+      className={cn(
+        // A live drag gets the focus ring's colour as a ring: "let go here", in the
+        // same vocabulary the button already uses for "you are here".
+        dragOver && "ring-2 ring-[var(--brand)]",
+        // Beside a long file name it is the NAME that gives way, never the button.
+        showFileName && "shrink-0",
+        className,
+      )}
+      onClick={(e) => {
+        onClick?.(e);
+        if (!e.defaultPrevented) picker.open();
+      }}
+    >
+      {/* `label={null}`: the spinner is decoration here — `aria-busy` says the same
+          thing on the button, and a spoken "Loading" would run into its name. */}
+      {pending && <Spinner label={null} className="size-4" />}
+      {children}
+    </Button>
+  );
+
+  if (!showFileName) {
+    return (
+      <>
+        {button}
+        {picker.element}
+      </>
+    );
+  }
   return (
-    <>
-      <Button
-        {...rest}
-        {...refProp}
-        {...dropHandlers}
-        type="button"
-        disabled={inert}
-        aria-busy={pending || undefined}
-        data-drag-over={dragOver || undefined}
-        className={cn(
-          // A live drag gets the focus ring's colour as a ring: "let go here", in the
-          // same vocabulary the button already uses for "you are here".
-          dragOver && "ring-2 ring-[var(--brand)]",
-          className,
-        )}
-        onClick={(e) => {
-          onClick?.(e);
-          if (!e.defaultPrevented) picker.open();
-        }}
+    // One inline row, so the name sits beside the button wherever the button sits; the
+    // name truncates (full list in its title) rather than pushing the row wider.
+    <span className="inline-flex max-w-full min-w-0 items-center gap-2">
+      {button}
+      <span
+        id={pickedId}
+        aria-live="polite"
+        data-slot="file-button-name"
+        title={picked.map((f) => f.name).join(", ") || undefined}
+        className="min-w-0 truncate text-sm text-[var(--text-secondary)]"
       >
-        {/* `label={null}`: the spinner is decoration here — `aria-busy` says the same
-            thing on the button, and a spoken "Loading" would run into its name. */}
-        {pending && <Spinner label={null} className="size-4" />}
-        {children}
-      </Button>
+        {pickedText}
+      </span>
       {picker.element}
-    </>
+    </span>
   );
 });
 FileButton.displayName = "FileButton";

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>