@eifi1/ui-kit 0.10.0 → 0.12.0

package/src/components/floating-panel.tsx

@@ -1,18 +1,39 @@
 import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import type { ButtonHTMLAttributes, CSSProperties, KeyboardEvent, ReactNode, Ref } from "react";
+import type {
+  AnchorHTMLAttributes,
+  ButtonHTMLAttributes,
+  CSSProperties,
+  HTMLAttributes,
+  KeyboardEvent,
+  MouseEvent,
+  ReactElement,
+  ReactNode,
+  Ref,
+} from "react";
 import { X } from "lucide-react";
 
 import { cn } from "../lib/cn";
 import { dirOf, type Direction } from "../lib/direction";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "./text-link";
+import { Tooltip, type TooltipSide } from "./tooltip";
 
 export interface FloatingPanelLabels {
   /** Accessible name of the panel header's X. */
   close: string;
+  /**
+   * What a {@link FloatingAction}'s count badge adds to its accessible name ("3 new"),
+   * read after the label: "Invoices, 3 new". The dot itself is hidden from a reader —
+   * a bare "3" read out of context says nothing about what is counted.
+   */
+  badge: (count: number) => string;
 }
 
-export const DEFAULT_FLOATING_PANEL_LABELS: FloatingPanelLabels = { close: "Close" };
+export const DEFAULT_FLOATING_PANEL_LABELS: FloatingPanelLabels = {
+  close: "Close",
+  badge: (count) => `${count} new`,
+};
 
 /** A LOGICAL corner: `bottom-end` is bottom-right in LTR and bottom-left in RTL. */
 export type FloatingCorner = "bottom-end" | "bottom-start";
@@ -89,6 +110,49 @@ export interface FloatingActionButtonProps extends Omit<ButtonHTMLAttributes<HTM
    * in both states; `aria-pressed` already says which one it is in.
    */
   pressed?: boolean;
+  /**
+   * Show `label` beside the icon: the EXTENDED FAB, a pill rather than a disc. For a
+   * corner control whose words are the point — kastlan's offline indicator
+   * (shared/offline/offline-indicator.tsx:39) is a pill saying "Offline — 2 photo(s)
+   * queued" / "Syncing…", hand-placed at `fixed bottom-4 left-4`, i.e. over the
+   * bottom nav and on the wrong side in RTL. Same height as the disc (3rem), so a
+   * {@link FloatingPanel} card above it still clears it.
+   */
+  extended?: boolean;
+  /**
+   * Announce `label` whenever it changes, through a polite `role="status"` region — for
+   * an extended FAB that REPORTS something (kastlan's offline/sync state), where a
+   * sighted user sees the words change and a screen reader user otherwise hears
+   * nothing until they happen to land on the button.
+   *
+   * ⚠️ A live region announces changes, not its own arrival: a FAB that mounts already
+   * saying "Offline" says it to nobody. Keep it mounted and pass `hidden` while there
+   * is nothing to report (kastlan returns `null` when online and idle); the region
+   * stays in the page, and the first real status is heard.
+   */
+  live?: boolean;
+  /**
+   * `primary` (default): the solid brand disc of a page's main action. `surface`: the
+   * page's surface with a hairline border — for a FAB that is a status rather than a
+   * call to action, as kastlan's offline pill is (a brand pill would shout "press me"
+   * at a user who is merely offline). Ignored while `pressed` is set; a toggle has its
+   * own two looks.
+   */
+  variant?: "primary" | "surface";
+  /**
+   * Hover and focus label in the kit {@link Tooltip}, instead of the native `title` —
+   * keksdose has ONE tooltip (dev#523) and wrapped its assistant launcher by hand,
+   * which cannot work: the tooltip's anchor is a `relative inline-flex` span, and this
+   * button is `fixed` and portalled. With `tooltip` the FAB positions a fixed wrapper
+   * instead and the button sits in the tooltip inside it. `true` shows the `label`;
+   * any other content shows that. Implies no native `title` (whatever `nativeTitle`
+   * says): one hover hint, not two. `style` stays on the button; the corner and
+   * `offset` move to the wrapper.
+   */
+  tooltip?: ReactNode;
+  /** Where the {@link tooltip} opens. Default `top`; the bubble is portalled and kept on
+   *  screen, so a corner button's label is not pushed off the edge. */
+  tooltipSide?: TooltipSide;
   ref?: Ref<HTMLButtonElement>;
 }
 
@@ -116,6 +180,11 @@ export function FloatingActionButton({
   offset = "1rem",
   nativeTitle = true,
   pressed,
+  extended = false,
+  live = false,
+  variant = "primary",
+  tooltip,
+  tooltipSide = "top",
   className,
   style,
   type = "button",
@@ -124,13 +193,12 @@ export function FloatingActionButton({
 }: FloatingActionButtonProps) {
   const [marker, dir] = usePortalDir();
   const toggle = pressed !== undefined;
-  // An empty title is "no tooltip", not an attribute with nothing in it.
-  const nativeTip = nativeTitle && title !== "" ? (title ?? label) : undefined;
-  return (
-    <>
-      <span ref={marker} hidden />
-      {typeof document !== "undefined" &&
-        createPortal(
+  const tip = tooltip === true ? label : tooltip === false || tooltip === "" ? undefined : tooltip;
+  const wrapped = tip !== undefined && tip !== null;
+  // An empty title is "no tooltip", not an attribute with nothing in it. The kit
+  // tooltip replaces it outright.
+  const nativeTip = !wrapped && nativeTitle && title !== "" ? (title ?? label) : undefined;
+  const button = (
           <button
             {...rest}
             type={type}
@@ -138,11 +206,19 @@ export function FloatingActionButton({
             aria-label={label}
             aria-pressed={pressed ?? rest["aria-pressed"]}
             title={nativeTip}
-            style={{ ...cornerStyle(corner, offset), ...style }}
+            style={wrapped ? style : { ...cornerStyle(corner, offset), ...style }}
             className={cn(
-              "fixed z-40 inline-flex size-12 items-center justify-center rounded-full",
-              "shadow-lg transition-colors",
-              !toggle && "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]",
+              // Wrapped, the wrapper is the fixed thing and the button sits in it.
+              !wrapped && "fixed z-40",
+              "inline-flex items-center justify-center rounded-full",
+              extended ? "h-12 gap-2 px-4 text-sm font-medium [&_svg]:size-5" : "size-12 [&_svg]:size-6",
+              "shadow-lg transition-colors disabled:cursor-default",
+              !toggle &&
+                variant === "primary" &&
+                "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]",
+              !toggle &&
+                variant === "surface" &&
+                "border border-[var(--border)] bg-[var(--bg-surface)] text-[var(--text-primary)] hover:bg-[var(--bg-hover)] disabled:hover:bg-[var(--bg-surface)]",
               // A toggle sits on the page's surface — a solid brand disc would read as
               // "on" in both states — and says "on" in the brand family.
               toggle && "border border-[var(--border)]",
@@ -151,12 +227,48 @@ export function FloatingActionButton({
               pressed === true &&
                 "border-[var(--brand)] bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]",
               "outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-2",
-              "[&_svg]:size-6",
               className,
             )}
           >
             {icon}
-          </button>,
+            {/* Visible words, not the name: `aria-label` already is the name, and the
+                span would only repeat it. */}
+            {extended && (
+              <span aria-hidden className="whitespace-nowrap">
+                {label}
+              </span>
+            )}
+          </button>
+  );
+  return (
+    <>
+      <span ref={marker} hidden />
+      {typeof document !== "undefined" &&
+        createPortal(
+          <>
+            {wrapped ? (
+              <div
+                dir={dir}
+                hidden={rest.hidden}
+                style={cornerStyle(corner, offset)}
+                className="fixed z-40 inline-flex"
+              >
+                <Tooltip label={tip} side={tooltipSide} portal>
+                  {/* A fragment when the bubble says the name again, so the tooltip
+                      does not describe the button with its own label — a reader would
+                      hear it twice. Other text is a real description. */}
+                  {tip === label ? <>{button}</> : button}
+                </Tooltip>
+              </div>
+            ) : (
+              button
+            )}
+            {live && (
+              <span role="status" className="sr-only">
+                {label}
+              </span>
+            )}
+          </>,
           document.body,
         )}
     </>
@@ -183,6 +295,10 @@ export interface FloatingPanelProps {
   /** The FAB's native `title` — see {@link FloatingActionButtonProps.nativeTitle}.
    *  `false` for keksdose's assistant launcher, under its one-tooltip rule (dev#523). */
   fabNativeTitle?: boolean;
+  /** The FAB's kit tooltip — see {@link FloatingActionButtonProps.tooltip}. `true` for
+   *  keksdose's assistant launcher, which wanted the kit bubble and had no way to
+   *  put one on a fixed, portalled button (dev#523). */
+  fabTooltip?: ReactNode;
   /** Default: `floatingPanel.close` from the {@link UiKitProvider}, else "Close". */
   closeLabel?: string;
   /**
@@ -239,6 +355,7 @@ export function FloatingPanel({
   corner = "bottom-end",
   offset = "1rem",
   fabNativeTitle,
+  fabTooltip,
   closeLabel,
   initialFocus,
   className,
@@ -308,6 +425,7 @@ export function FloatingPanel({
         corner={corner}
         offset={offset}
         nativeTitle={fabNativeTitle}
+        tooltip={fabTooltip}
         aria-expanded={open}
         aria-controls={open ? panelId : undefined}
         onClick={() => {
@@ -383,3 +501,249 @@ export function FloatingPanel({
     </>
   );
 }
+
+export interface FloatingActionGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
+  /** Name the group ("Register actions"); a reader then introduces the members as one
+   *  set. A group with no name is one more unlabelled wrapper. */
+  "aria-label"?: string;
+  /** Default `bottom-end`. */
+  corner?: FloatingCorner;
+  /** Distance above the nav / home indicator — see {@link FloatingActionButtonProps.offset}. */
+  offset?: string;
+  /** {@link FloatingAction}s, in reading order. */
+  children: ReactNode;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * A floating pill of {@link FloatingAction}s — one to four `size-12` toggles, actions
+ * or links with hairline dividers — pinned to a corner exactly as the
+ * {@link FloatingActionButton} is: `--app-nav-h` and the home indicator cleared, a
+ * logical corner, portalled.
+ *
+ * keksdose built it twice by hand: the /transactions phone toolbar
+ * (transactions-page.tsx:644 — upcoming and pending toggles, an invoices link with a
+ * pending count, and the brand "+") and the feedback page's "awaiting only" toggle
+ * (feedback-page.tsx:854, one button in the group anyway, so the two pages look
+ * alike). Both at `right-4 bottom-20` — `right`, not `end`, so over the page's leading
+ * edge in RTL — with `divide-x`, slate hovers, and each member's `Tooltip` spelled out.
+ *
+ * `role="group"`, NOT a toolbar: every member keeps its own tab stop, as the
+ * hand-built ones did, and there is no arrow-key roving to learn. Hide it where it
+ * does not belong with a class (`md:hidden`, as both keksdose pages do).
+ */
+export function FloatingActionGroup({
+  corner = "bottom-end",
+  offset = "1rem",
+  className,
+  style,
+  children,
+  ...rest
+}: FloatingActionGroupProps) {
+  const [marker, dir] = usePortalDir();
+  return (
+    <>
+      <span ref={marker} hidden />
+      {typeof document !== "undefined" &&
+        createPortal(
+          <div
+            {...rest}
+            role="group"
+            dir={dir}
+            data-corner={corner}
+            style={{ ...cornerStyle(corner, offset), ...style }}
+            className={cn(
+              "fixed z-40 inline-flex flex-row overflow-hidden rounded-2xl",
+              "border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+              // Dividers on the logical start edge of every member but the first, so
+              // they sit between the same two members in RTL. The member is the
+              // tooltip's wrapper span, which is the direct child.
+              "[&>*:not(:first-child)]:border-s [&>*]:border-[var(--border)]",
+              className,
+            )}
+          >
+            {children}
+          </div>,
+          document.body,
+        )}
+    </>
+  );
+}
+
+/** What {@link FloatingActionProps.renderLink} is handed. Spread it onto your router's
+ *  link, mapping `href` — `renderLink={({ href, ...p }) => <Link to={href} {...p} />}`. */
+export interface FloatingActionLinkProps {
+  href: string;
+  /** The member's whole look — keep it. */
+  className: string;
+  children: ReactNode;
+  "aria-label": string;
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+  [key: `aria-${string}`]: string | boolean | number | undefined;
+  [key: `data-${string}`]: unknown;
+}
+
+export interface FloatingActionProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick"> {
+  /** The accessible name, and the tooltip's text. Keep it the same in both states of a
+   *  toggle; `aria-pressed` says which one it is in. */
+  label: string;
+  icon: ReactNode;
+  /** Make it a toggle: `aria-pressed` and the brand "on" look (the brand glyph on the
+   *  quiet brand fill), as {@link FloatingActionButtonProps.pressed}. Ignored on a link.
+   *  For the state without the tint, see {@link pressedStyle}. */
+  pressed?: boolean;
+  /**
+   * How `pressed` looks. `tint` (default): the brand "on" look. `plain`: the member
+   * keeps its quiet look in both states and only `aria-pressed` changes — for a toggle
+   * whose icon already says which state it is in (keksdose's /transactions "Upcoming"
+   * swaps two icons; a tint on top said it twice). The same as passing `aria-pressed`
+   * without `pressed`, which also rides through untinted.
+   */
+  pressedStyle?: "tint" | "plain";
+  /**
+   * `primary`: the brand-filled member, for the group's main action (the /transactions
+   * "+"). Default: the quiet one.
+   */
+  variant?: "default" | "primary";
+  /**
+   * A count in a dot at the member's top end corner — the /transactions invoices link's
+   * pending count. Nothing is drawn for `0` or less; above 99 it reads `99+`. The count
+   * joins the accessible name through `floatingPanel.badge` ("Invoices, 3 new"), or
+   * `badgeLabel` when passed.
+   */
+  badge?: number;
+  /** The badge's words for a reader, replacing `floatingPanel.badge` — "3 to review". */
+  badgeLabel?: string;
+  /** The dot's colour. Default `warning`, the pending count's. */
+  badgeTone?: "warning" | "danger" | "brand";
+  /** Show `label` in the kit {@link Tooltip} on hover and focus. Default `true`: the
+   *  members are icon-only and this is their only visible label. */
+  tooltip?: boolean;
+  /** Where the tooltip opens. Default `top` — the group sits at the bottom of the screen. */
+  tooltipSide?: TooltipSide;
+  /** Make it a link — the /transactions invoices member. Drawn by `renderLink`, else
+   *  the `<UiKitProvider linkComponent>` (an in-app `href`), else a plain `<a>`. */
+  href?: string;
+  /** Render the link through your router's `Link` — see {@link FloatingActionLinkProps}. */
+  renderLink?: (props: FloatingActionLinkProps) => ReactElement;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  ref?: Ref<HTMLButtonElement>;
+}
+
+const BADGE_TONE: Record<NonNullable<FloatingActionProps["badgeTone"]>, string> = {
+  warning: "bg-[var(--warning)] text-[var(--text-inverse)]",
+  danger: "bg-[var(--danger)] text-[var(--danger-contrast)]",
+  brand: "bg-[var(--brand)] text-[var(--brand-contrast)]",
+};
+
+/**
+ * One member of a {@link FloatingActionGroup}: a `size-12` icon button, toggle or link
+ * with its label in a styled tooltip — what each keksdose member wrapped by hand in
+ * `<Tooltip portal>`. The tooltip is portalled because the group clips (`overflow-hidden`
+ * keeps the brand member's fill inside the pill's corners), and the focus ring is inset
+ * for the same reason.
+ */
+export function FloatingAction({
+  label,
+  icon,
+  pressed,
+  pressedStyle = "tint",
+  variant = "default",
+  badge,
+  badgeLabel,
+  badgeTone = "warning",
+  tooltip = true,
+  tooltipSide = "top",
+  href,
+  renderLink,
+  className,
+  type = "button",
+  onClick,
+  ref,
+  ...rest
+}: FloatingActionProps) {
+  const labels = useKitLabels("floatingPanel", DEFAULT_FLOATING_PANEL_LABELS);
+  const kitLink = useKitLink();
+  const counted = badge !== undefined && badge > 0;
+  const name = counted ? `${label}, ${badgeLabel ?? labels.badge(badge)}` : label;
+  const isLink = href !== undefined;
+  const look = cn(
+    "relative flex size-12 items-center justify-center transition-colors",
+    "outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--brand)]",
+    "disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:size-5",
+    variant === "primary"
+      ? "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]"
+      : pressed && !isLink && pressedStyle === "tint"
+        ? "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]"
+        : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
+    className,
+  );
+  const body = (
+    <>
+      {icon}
+      {counted && (
+        <span
+          aria-hidden
+          data-badge=""
+          className={cn(
+            "pointer-events-none absolute end-1 top-1 h-4 min-w-4 rounded-full px-1 text-center text-[10px] leading-4 font-semibold",
+            BADGE_TONE[badgeTone],
+          )}
+        >
+          {badge > 99 ? "99+" : badge}
+        </span>
+      )}
+    </>
+  );
+
+  let member: ReactElement;
+  if (isLink) {
+    // The button-only attributes stay behind; `aria-*`, `data-*` and the like ride along.
+    const { disabled: _disabled, form: _form, value: _value, name: _name, ...anchorRest } = rest;
+    const linkProps: FloatingActionLinkProps = {
+      ...(anchorRest as AnchorHTMLAttributes<HTMLAnchorElement>),
+      href,
+      "aria-label": name,
+      onClick,
+      className: look,
+      children: body,
+    };
+    const { children: content, ...anchor } = linkProps;
+    const render = pickLinkRenderer(renderLink, kitLink, href);
+    member = render ? (
+      <RenderedFloatingLink render={render} {...linkProps} />
+    ) : (
+      <a {...anchor}>{content}</a>
+    );
+  } else {
+    member = (
+      <button
+        {...rest}
+        ref={ref}
+        type={type}
+        aria-label={name}
+        aria-pressed={pressed ?? rest["aria-pressed"]}
+        onClick={onClick}
+        className={look}
+      >
+        {body}
+      </button>
+    );
+  }
+  if (!tooltip) return member;
+  return (
+    // A fragment: the bubble says the member's name, and a description that repeats
+    // the name is read twice.
+    <Tooltip label={label} side={tooltipSide} portal>
+      <>{member}</>
+    </Tooltip>
+  );
+}
+
+/** Calls `renderLink` as a component, so its hooks belong to the link, not to us. */
+function RenderedFloatingLink({
+  render,
+  ...props
+}: FloatingActionLinkProps & { render: (props: FloatingActionLinkProps) => ReactElement }) {
+  return render(props);
+}

package/src/components/form-actions.tsx

@@ -0,0 +1,191 @@
+import { isValidElement } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Button, Spinner, type ButtonVariant } from "./ui";
+
+/** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
+export interface FormActionsLabels {
+  save: string;
+  cancel: string;
+}
+
+export const DEFAULT_FORM_ACTIONS_LABELS: FormActionsLabels = {
+  save: "Save",
+  cancel: "Cancel",
+};
+
+export type FormActionsAlign = "start" | "center" | "end" | "between";
+
+/**
+ * Where the row sits:
+ *  - `inline` (default): under the form's last field, `pt-4` above it.
+ *  - `sticky`: stuck to the bottom of the scrolling page or pane, on the surface
+ *    colour with a rule above, clear of the phone's home indicator — for a long form
+ *    whose Save should not be a scroll away.
+ *  - `dialog`: no spacing of its own, for a dialog's footer slot (DialogFrame,
+ *    FullBleedDialog's `footer`), which already pads and rules it.
+ */
+export type FormActionsPlacement = "inline" | "sticky" | "dialog";
+
+/** The start-side action of {@link FormActionsProps.destructive}, as data. */
+export interface FormActionsDestructive {
+  label: ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+  /** See Button's `disabledReason`. */
+  disabledReason?: ReactNode;
+}
+
+const ALIGN_CLASS: Record<FormActionsAlign, string> = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+};
+
+const PLACEMENT_CLASS: Record<FormActionsPlacement, string> = {
+  inline: "pt-4",
+  sticky: "sticky bottom-0 z-10 border-t border-[var(--border)] bg-[var(--bg-surface)] pt-3",
+  dialog: "",
+};
+
+export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  /** Called by Cancel. Omitted: no Cancel button (a form that only saves). */
+  onCancel?: () => void;
+  /**
+   * Given: the save button is `type="button"` and calls this — for a dialog or a row
+   * that saves from a handler. Omitted: it is `type="submit"` and submits the
+   * enclosing `<form>` (or the one named by {@link form}).
+   */
+  onSubmit?: () => void;
+  /** The save button's text. Default `form.save` from the provider, else "Save". */
+  submitLabel?: ReactNode;
+  /** The cancel button's text. Default `form.cancel` from the provider, else "Cancel". */
+  cancelLabel?: ReactNode;
+  /** The save button's text while `pending` ("Saving…"). Default: `submitLabel`. */
+  pendingLabel?: ReactNode;
+  /**
+   * 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.
+   */
+  pending?: boolean;
+  /** Disable save for a reason of the form's own (an unbalanced entry). */
+  submitDisabled?: boolean;
+  /** Why save is disabled — see Button's `disabledReason`. Keeps it focusable. */
+  submitDisabledReason?: ReactNode;
+  /** The save button's variant. Default `brand`; `danger` for a save that destroys
+   *  (kastlan's `destructive` flag on its own FormActions). */
+  submitVariant?: ButtonVariant;
+  /**
+   * A destructive action at the START of the row, apart from Save and Cancel — the
+   * "Delete" of an edit dialog. Pass `{ label, onClick }` for the kit's quiet danger
+   * button, or an element of your own (a {@link DangerConfirm}, say). With it the row
+   * is `between`-aligned unless `align` says otherwise.
+   */
+  destructive?: ReactNode | FormActionsDestructive;
+  /** Horizontal alignment. Default `end` (`between` with a `destructive` action). */
+  align?: FormActionsAlign;
+  /** See {@link FormActionsPlacement}. Default `inline`. */
+  placement?: FormActionsPlacement;
+  /** The `id` of the `<form>` the save button submits, when the row is rendered
+   *  outside it (a dialog's footer slot). */
+  form?: string;
+  /** Extra actions, placed before Cancel. */
+  children?: ReactNode;
+}
+
+function isDestructiveData(value: unknown): value is FormActionsDestructive {
+  return typeof value === "object" && value !== null && !isValidElement(value) && "onClick" in value;
+}
+
+/**
+ * The Save / Cancel row every form, wizard-step form and dialog ends in — kastlan's
+ * `FormActions`, with the labels from the provider, a pending state and a place for
+ * the destructive action.
+ *
+ * ```tsx
+ * <form onSubmit={form.handleSubmit(save)}>
+ *   …
+ *   <FormActions onCancel={close} pending={mutation.isPending} />
+ * </form>
+ * ```
+ *
+ * The spinner is the kit's {@link Spinner}, drawn inside the button with `label={null}`
+ * so the button's name stays its text; `aria-busy` is what says it is working.
+ */
+export function FormActions({
+  onCancel,
+  onSubmit,
+  submitLabel,
+  cancelLabel,
+  pendingLabel,
+  pending = false,
+  submitDisabled = false,
+  submitDisabledReason,
+  submitVariant = "brand",
+  destructive,
+  align,
+  placement = "inline",
+  form,
+  children,
+  className,
+  style,
+  ...rest
+}: 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) ? (
+    <Button
+      type="button"
+      variant="ghost"
+      tone="danger"
+      onClick={destructive.onClick}
+      disabled={destructive.disabled}
+      disabledReason={destructive.disabledReason}
+    >
+      {destructive.label}
+    </Button>
+  ) : (
+    destructive
+  );
+  const saveLabel = submitLabel ?? labels.save;
+
+  return (
+    <div
+      data-slot="form-actions"
+      data-placement={placement}
+      {...rest}
+      style={
+        placement === "sticky"
+          ? { paddingBottom: "max(0.75rem, env(safe-area-inset-bottom))", ...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>}
+      <div className="flex flex-wrap items-center gap-2">
+        {children}
+        {onCancel && (
+          <Button type="button" variant="secondary" onClick={onCancel}>
+            {cancelLabel ?? labels.cancel}
+          </Button>
+        )}
+        <Button
+          type={onSubmit ? "button" : "submit"}
+          form={form}
+          onClick={onSubmit}
+          variant={submitVariant}
+          disabled={pending || submitDisabled}
+          disabledReason={pending ? undefined : submitDisabledReason}
+          aria-busy={pending || undefined}
+        >
+          {pending && <Spinner label={null} className="size-4" />}
+          {pending && pendingLabel !== undefined ? pendingLabel : saveLabel}
+        </Button>
+      </div>
+    </div>
+  );
+}