@eifi1/ui-kit 0.7.1 → 0.8.1

package/src/components/floating-panel.tsx

@@ -0,0 +1,341 @@
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import type { ButtonHTMLAttributes, CSSProperties, KeyboardEvent, 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";
+
+export interface FloatingPanelLabels {
+  /** Accessible name of the panel header's X. */
+  close: string;
+}
+
+export const DEFAULT_FLOATING_PANEL_LABELS: FloatingPanelLabels = { close: "Close" };
+
+/** A LOGICAL corner: `bottom-end` is bottom-right in LTR and bottom-left in RTL. */
+export type FloatingCorner = "bottom-end" | "bottom-start";
+
+/**
+ * How far off the bottom edge anything floating here sits: clear of `AppShell`'s phone
+ * nav (`--app-nav-h`, `0px` above `md` where the nav is not rendered) and of the home
+ * indicator, whichever reaches higher — the nav does not pad itself for the inset, so
+ * with no nav on screen the inset is all there is to clear. `max`, not a sum: where the
+ * nav does cover the inset, adding both would float the button a nav-height too high.
+ */
+const BOTTOM_CLEARANCE = "max(var(--app-nav-h, 0px), env(safe-area-inset-bottom, 0px))";
+/** The side gutter, widened for a landscape notch. Both insets, because a logical
+ *  side has no one physical inset to name. */
+const SIDE_GUTTER = "max(1rem, env(safe-area-inset-left, 0px), env(safe-area-inset-right, 0px))";
+
+function cornerStyle(corner: FloatingCorner, lift: string): CSSProperties {
+  return {
+    bottom: `calc(${BOTTOM_CLEARANCE} + ${lift})`,
+    // Logical properties, so the corner follows the reading direction with no JS. The
+    // portal carries the `dir` across (see `usePortalDir`).
+    [corner === "bottom-start" ? "insetInlineStart" : "insetInlineEnd"]: SIDE_GUTTER,
+  };
+}
+
+/**
+ * The reading direction where the component was RENDERED, for its portalled root: a
+ * portal to `<body>` leaves the subtree whose `dir` it inherited, and a logical
+ * `inset-inline-end` resolves against the portal's own direction. Read off a hidden
+ * inline marker in a layout effect, so the first painted frame already has it.
+ */
+function usePortalDir(): [Ref<HTMLSpanElement>, Direction | undefined] {
+  const marker = useRef<HTMLSpanElement>(null);
+  const [dir, setDir] = useState<Direction | undefined>(undefined);
+  useLayoutEffect(() => {
+    setDir(dirOf(marker.current));
+  }, []);
+  return [marker, dir];
+}
+
+export interface FloatingActionButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+  /** The accessible name — the button shows only its icon. */
+  label: string;
+  icon: ReactNode;
+  /** Default `bottom-end`. */
+  corner?: FloatingCorner;
+  /**
+   * Distance above the nav / home indicator, as a CSS length. Default `1rem`. Raise it
+   * to stack above another floating control in the same corner — keksdose's assistant
+   * clears the transactions page's own action group this way (`calc(1rem + 4rem)`).
+   */
+  offset?: string;
+  ref?: Ref<HTMLButtonElement>;
+}
+
+/**
+ * A round, icon-only button pinned to a corner of the viewport — the trigger of a
+ * {@link FloatingPanel}, and usable alone for a page's one primary action.
+ *
+ * keksdose hand-placed each of its floating controls: the assistant launcher at
+ * `fixed bottom-36 right-4 md:bottom-6`, the feedback page's and the transactions
+ * page's action groups at `right-4 bottom-20`. Every one of those numbers is a guess
+ * at the phone nav's height plus whatever else floats there (Keksdose live #314 found
+ * out what such a guess is worth for a footer), `right` rather than `end` puts it over
+ * the page's leading edge in RTL, and none allows for the home indicator. Here the
+ * base is `--app-nav-h` and the safe-area inset, the corner is logical, and
+ * {@link FloatingActionButtonProps.offset} is the one number left to the caller — the
+ * height of whatever else it has to clear, not the nav's.
+ *
+ * Portalled, because `position: fixed` inside any transformed ancestor (an animated
+ * page transition) is fixed to that ancestor, not to the screen.
+ */
+export function FloatingActionButton({
+  label,
+  icon,
+  corner = "bottom-end",
+  offset = "1rem",
+  className,
+  style,
+  type = "button",
+  ...rest
+}: FloatingActionButtonProps) {
+  const [marker, dir] = usePortalDir();
+  return (
+    <>
+      <span ref={marker} hidden />
+      {typeof document !== "undefined" &&
+        createPortal(
+          <button
+            {...rest}
+            type={type}
+            dir={dir}
+            aria-label={label}
+            title={rest.title ?? label}
+            style={{ ...cornerStyle(corner, offset), ...style }}
+            className={cn(
+              "fixed z-40 inline-flex size-12 items-center justify-center rounded-full",
+              "bg-[var(--brand)] text-[var(--brand-contrast)] shadow-lg transition-colors hover:bg-[var(--brand-hover)]",
+              "outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-2",
+              "[&_svg]:size-6",
+              className,
+            )}
+          >
+            {icon}
+          </button>,
+          document.body,
+        )}
+    </>
+  );
+}
+
+export interface FloatingPanelProps {
+  /** The panel's heading, and its accessible name. */
+  title: ReactNode;
+  /** The trigger's accessible name ("Assistant", "Send feedback"). */
+  fabLabel: string;
+  fabIcon: ReactNode;
+  /** Controlled open state. Leave it out to let the panel own it. */
+  open?: boolean;
+  /** Uncontrolled initial state. Default closed. */
+  defaultOpen?: boolean;
+  /** Every request to open or close — the FAB, the X, Escape. */
+  onOpenChange?: (open: boolean) => void;
+  /** Default `bottom-end`. */
+  corner?: FloatingCorner;
+  /** The FAB's distance above the nav — see {@link FloatingActionButtonProps.offset}.
+   *  From `md` up the card sits above the FAB, so it moves with it. */
+  offset?: string;
+  /** Default: `floatingPanel.close` from the {@link UiKitProvider}, else "Close". */
+  closeLabel?: string;
+  /**
+   * Where focus goes on open. Default the panel itself, so a phone's keyboard does not
+   * rise over the sheet before the user has asked to type; pass the chat field for a
+   * panel whose one job is typing.
+   */
+  initialFocus?: () => HTMLElement | null;
+  /** Extra classes for the panel. */
+  className?: string;
+  /** Extra classes for the scrolling body. */
+  bodyClassName?: string;
+  children: ReactNode;
+}
+
+/**
+ * A docked, NON-MODAL panel in a corner of the screen, opened by a
+ * {@link FloatingActionButton} — keksdose's assistant launcher and its feedback page,
+ * which each built one.
+ *
+ * ## Not a Modal
+ *
+ * The page stays usable while it is open: that is the point of an assistant beside the
+ * data it is asked about. So there is no backdrop, no scroll lock, no `aria-modal` and
+ * no focus trap — Tab walks out of the panel into the page and back, and a click on the
+ * page does not close it. It is `role="dialog"` without `aria-modal`, which is what
+ * ARIA calls a non-modal dialog, named by its heading.
+ *
+ * What it keeps from a dialog is the focus HANDOFF: opening moves focus into it (a
+ * keyboard user who pressed the FAB should not have to hunt for what appeared), and
+ * closing gives it back to the FAB — but only when focus was in the panel, so a panel
+ * closed from the page (a controlled owner) never pulls focus out of the field the
+ * user is typing in. Escape closes it while focus is inside, and only then: on the
+ * panel element, not the document, so Escape in the page keeps meaning whatever the
+ * page means by it.
+ *
+ * ## Layout
+ *
+ * From `md` up, a card above the FAB in its corner. Below `md`, a full-width sheet
+ * docked to the bottom, sitting ON the `AppShell` bottom nav (`--app-nav-h`) and
+ * clear of the home indicator. Pure CSS — no width is measured in JavaScript.
+ *
+ * The FAB carries `aria-expanded` and, while the panel exists, `aria-controls`. The
+ * panel unmounts when closed; an app that must keep a draft across a close keeps it in
+ * its own state, where it also survives a reload.
+ */
+export function FloatingPanel({
+  title,
+  fabLabel,
+  fabIcon,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  corner = "bottom-end",
+  offset = "1rem",
+  closeLabel,
+  initialFocus,
+  className,
+  bodyClassName,
+  children,
+}: FloatingPanelProps) {
+  const labels = useKitLabels(
+    "floatingPanel",
+    DEFAULT_FLOATING_PANEL_LABELS,
+    closeLabel === undefined ? undefined : { close: closeLabel },
+  );
+  const [ownOpen, setOwnOpen] = useState(defaultOpen);
+  const open = openProp ?? ownOpen;
+  const setOpen = (next: boolean) => {
+    if (openProp === undefined) setOwnOpen(next);
+    onOpenChange?.(next);
+  };
+
+  const uid = useId();
+  const panelId = `${uid}-panel`;
+  const titleId = `${uid}-title`;
+  const fabRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [marker, dir] = usePortalDir();
+
+  const initialFocusRef = useRef(initialFocus);
+  useEffect(() => {
+    initialFocusRef.current = initialFocus;
+  });
+
+  // Focus follows the open/closed TRANSITION, never the mount: a panel that renders
+  // open (`defaultOpen`, a restored route) does not take the page's focus by existing.
+  const wasOpen = useRef(open);
+  // Whether focus was inside the panel when it last changed — read at close time, when
+  // the panel (and whatever had focus in it) is already gone.
+  const focusInside = useRef(false);
+  useEffect(() => {
+    const changed = wasOpen.current !== open;
+    wasOpen.current = open;
+    if (!changed) return;
+    if (open) {
+      (initialFocusRef.current?.() ?? panelRef.current)?.focus();
+      return;
+    }
+    const active = document.activeElement;
+    const lost = active === null || active === document.body;
+    if (focusInside.current || lost) fabRef.current?.focus();
+    focusInside.current = false;
+  }, [open]);
+
+  const onPanelKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key !== "Escape" || e.defaultPrevented) return;
+    // Stopped here, so an overlay underneath with a document-level Escape listener does
+    // not close too — the innermost thing that has focus is the one that closes.
+    e.stopPropagation();
+    focusInside.current = true;
+    setOpen(false);
+  };
+
+  return (
+    <>
+      <span ref={marker} hidden />
+      <FloatingActionButton
+        ref={fabRef}
+        label={fabLabel}
+        icon={fabIcon}
+        corner={corner}
+        offset={offset}
+        aria-expanded={open}
+        aria-controls={open ? panelId : undefined}
+        onClick={() => {
+          // A press ON the FAB closing the panel: the FAB keeps focus by being clicked,
+          // nothing to hand back.
+          focusInside.current = false;
+          setOpen(!open);
+        }}
+      />
+      {open &&
+        typeof document !== "undefined" &&
+        createPortal(
+          // A container for Escape bubbling up from anything inside it, as a dialog is.
+          // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
+          <div
+            ref={panelRef}
+            id={panelId}
+            role="dialog"
+            aria-labelledby={titleId}
+            tabIndex={-1}
+            dir={dir}
+            data-corner={corner}
+            onKeyDown={onPanelKeyDown}
+            onFocus={() => {
+              focusInside.current = true;
+            }}
+            onBlur={(e) => {
+              if (!e.currentTarget.contains(e.relatedTarget as Node | null)) focusInside.current = false;
+            }}
+            // The phone's sheet sits on the nav; from `md` up the card floats above the
+            // FAB (its offset + the 3rem button + a 0.75rem gap).
+            style={
+              {
+                "--fp-bottom": `calc(${BOTTOM_CLEARANCE})`,
+                "--fp-bottom-md": `calc(${BOTTOM_CLEARANCE} + ${offset} + 3.75rem)`,
+                "--fp-side": SIDE_GUTTER,
+              } as CSSProperties
+            }
+            className={cn(
+              "animate-sheet fixed z-40 flex flex-col overflow-hidden outline-none",
+              "border border-[var(--border)] bg-[var(--bg-surface)] shadow-2xl",
+              // Phone: full width, docked, rounded only where it meets the page.
+              "inset-x-0 bottom-[var(--fp-bottom)] max-h-[min(85dvh,calc(100dvh_-_var(--fp-bottom)_-_1rem))] rounded-t-xl border-x-0 border-b-0",
+              "pb-[env(safe-area-inset-bottom,0px)] md:pb-0",
+              // md+: a card in the corner, above the FAB.
+              "md:inset-x-auto md:bottom-[var(--fp-bottom-md)] md:w-[24rem] md:max-h-[min(36rem,calc(100dvh_-_var(--fp-bottom-md)_-_1rem))] md:rounded-xl md:border",
+              corner === "bottom-start" ? "md:start-[var(--fp-side)]" : "md:end-[var(--fp-side)]",
+              className,
+            )}
+          >
+            <div className="flex shrink-0 items-center justify-between gap-2 border-b border-[var(--border)] px-4 py-3">
+              <h2 id={titleId} className="min-w-0 truncate text-base font-semibold text-[var(--text-primary)]">
+                {title}
+              </h2>
+              <button
+                type="button"
+                onClick={() => {
+                  focusInside.current = true;
+                  setOpen(false);
+                }}
+                aria-label={labels.close}
+                className="-me-1.5 shrink-0 rounded p-1.5 text-[var(--text-muted)] outline-none hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)] focus-visible:ring-2 focus-visible:ring-[var(--brand)]"
+              >
+                <X aria-hidden className="size-5" />
+              </button>
+            </div>
+            <div className={cn("min-h-0 flex-1 overflow-y-auto overscroll-contain p-4", bodyClassName)}>
+              {children}
+            </div>
+          </div>,
+          document.body,
+        )}
+    </>
+  );
+}

package/src/components/full-bleed-dialog.tsx

@@ -43,6 +43,17 @@ export interface FullBleedDialogProps extends ComponentPropsWithoutRef<"div"> {
   backCloses?: boolean;
   /** Extra classes for the PANEL (not the backdrop). */
   className?: string;
+  /**
+   * A row pinned under the scrolling body — an Apply, a Save. Keksdose's `RangeSheet`
+   * (reports/report-range-field.tsx) is a hand-rolled copy of this dialog for want of
+   * exactly this slot: a date range picked on a phone is committed by a sticky Apply,
+   * and a button at the end of the body scrolls away with the calendar.
+   *
+   * Outside the scroller, so it stays put without `position: sticky` (which would
+   * need the body to be the scroll container of its own child and paint over the
+   * last field); padded for the home indicator, since it is the panel's bottom edge.
+   */
+  footer?: ReactNode;
 }
 
 /**
@@ -81,6 +92,10 @@ export function FullBleedDialog({
   children,
   backCloses = true,
   className,
+  footer,
+  onMouseDown,
+  onMouseUp,
+  onKeyDown,
   ...rest
 }: FullBleedDialogProps) {
   // Every way OUT goes through `requestClose`, so the panel lowers itself before the
@@ -107,7 +122,15 @@ export function FullBleedDialog({
   useFocusTrap(dialogRef, { active: open });
 
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
-    if (e.key !== "Escape") return;
+    // The caller's handler first (keksdose's transaction-search keeps its list keys on
+    // the dialog); a `preventDefault()` IN THAT HANDLER claims the key, Escape included.
+    // Only there: a descendant's preventDefault does not count. A SearchField in the
+    // header prevents Escape to stop Chromium clearing a type=search input, and in
+    // 0.8.0 that silently stopped Escape from closing the dialog (keksdose).
+    const preventedBefore = e.defaultPrevented;
+    onKeyDown?.(e);
+    const claimedByCaller = !preventedBefore && e.defaultPrevented;
+    if (claimedByCaller || e.key !== "Escape") return;
     // On the panel, the way `Modal` does it, and NOT through `useEscapeKey`: this
     // dialog is the thing a `PickerSheet` opens on top of, and a document-level
     // listener cannot tell which of the two the user meant. One press would dismiss
@@ -148,7 +171,21 @@ export function FullBleedDialog({
       tabIndex={-1}
       ref={dialogRef}
       onKeyDown={handleKeyDown}
-      {...backdropClose}
+      // COMPOSED with the backdrop's, not overridden by them. These two used to ride
+      // `...rest` and then lose to `{...backdropClose}` spread after it, silently —
+      // and the one caller about to pass one is keksdose's RangeSheet, whose
+      // `onMouseDown={(e) => e.stopPropagation()}` is its dev#477 fix: a press in a
+      // portalled sheet must not reach a document-level "outside click" listener,
+      // which would unmount the day cell before its `click`. The caller's runs first;
+      // the backdrop's still runs after it, since it is the same element.
+      onMouseDown={(e) => {
+        onMouseDown?.(e);
+        backdropClose.onMouseDown(e);
+      }}
+      onMouseUp={(e) => {
+        onMouseUp?.(e);
+        backdropClose.onMouseUp(e);
+      }}
     >
       <div
         className={cn(
@@ -158,12 +195,12 @@ export function FullBleedDialog({
         )}
       >
         <div className="flex items-center justify-between gap-2 border-b border-[var(--border)] px-3 py-3">
-          <div className="min-w-0 font-medium">{header}</div>
+          <div className="min-w-0 flex-1 font-medium">{header}</div>
           <button
             type="button"
             onClick={requestClose}
             aria-label={closeLabel}
-            className="-mr-1 shrink-0 rounded p-1.5 text-[var(--text-muted)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]"
+            className="-me-1 shrink-0 rounded p-1.5 text-[var(--text-muted)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]"
           >
             <X className="size-5" />
           </button>
@@ -171,7 +208,18 @@ export function FullBleedDialog({
         {/* px-3, not px-4: every pixel of chrome here is width the form fields lose
             on a phone (feedback #32). The body is the only thing that scrolls, so the
             header stays put and the page underneath cannot move at all. */}
-        <div className="flex-1 overflow-y-auto overscroll-contain px-3 py-3">{children}</div>
+        {/* `min-h-0` so it is the BODY that gives way to a footer, not the footer that
+            is pushed off the bottom edge. */}
+        <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-3 py-3">{children}</div>
+        {footer !== undefined && footer !== null && footer !== false && (
+          <div
+            data-full-bleed-footer=""
+            className="flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-[var(--border)] px-3 pt-3"
+            style={{ paddingBottom: "max(0.75rem, env(safe-area-inset-bottom))" }}
+          >
+            {footer}
+          </div>
+        )}
       </div>
     </div>,
     document.body,

package/src/components/modal.tsx

@@ -117,9 +117,13 @@ export function useBackdropClose(onClose: () => void) {
  * where a `data-tour` anchor, a test id, an `aria-describedby` or an `aria-label` has
  * to land; before this, a closed prop list dropped all four silently (audit §api-design).
  */
-export interface ModalProps extends ComponentPropsWithoutRef<"div"> {
+export interface ModalProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
   /** Invoked on backdrop click and on Escape. */
   onClose: () => void;
+  /** `"alertdialog"` for a dialog that interrupts to ask a question the user must
+   *  answer (a confirmation) — screen readers announce it with more urgency. Only the
+   *  two dialog roles are allowed: the panel stays modal either way. */
+  role?: "dialog" | "alertdialog";
   children: ReactNode;
   /**
    * Panel max-width: `md` (28rem), `lg` (32rem), `xl` (48rem).
@@ -187,6 +191,7 @@ export function Modal({
   fullBleed,
   draggable,
   style,
+  role = "dialog",
   ...rest
 }: ModalProps) {
   const panelRef = useRef<HTMLDivElement>(null);
@@ -252,7 +257,9 @@ export function Modal({
         // walks straight out of) shows up nowhere near the call site that caused it.
         {...rest}
         ref={panelRef}
-        role="dialog"
+        // Normalised at runtime too: an untyped caller's `role="presentation"` must not
+        // take the dialog role away (props-passthrough pins that).
+        role={role === "alertdialog" ? "alertdialog" : "dialog"}
         aria-modal="true"
         aria-labelledby={labelledBy}
         tabIndex={-1}

package/src/components/progress-bar.tsx

@@ -0,0 +1,163 @@
+import { useId } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
+
+export type ProgressBarTone = "brand" | "neutral" | "success" | "warning" | "danger" | "info";
+export type ProgressBarSize = "sm" | "md" | "lg";
+
+const FILL: Record<ProgressBarTone, string> = {
+  brand: "bg-[var(--brand)]",
+  neutral: "bg-[var(--text-muted)]",
+  success: "bg-[var(--success)]",
+  warning: "bg-[var(--warning)]",
+  danger: "bg-[var(--danger)]",
+  info: "bg-[var(--info)]",
+};
+
+const TRACK_HEIGHT: Record<ProgressBarSize, string> = { sm: "h-1", md: "h-2", lg: "h-3" };
+
+export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
+  /** Where it stands. Leave it undefined for an INDETERMINATE bar — work is under way
+   *  and nobody knows how much is left (an import that reports no count). */
+  value?: number;
+  min?: number;
+  max?: number;
+  /**
+   * `progress` (default): a task moving toward completion — `role="progressbar"`.
+   * `meter`: a share of a known whole that is not going anywhere (budget used, disk
+   * space, one category's slice of spending) — `role="meter"`. keksdose's share bars
+   * were progress bars to a screen reader, which reads "busy" into a figure that is
+   * simply a figure. A meter is never indeterminate; a missing value reads as `min`.
+   */
+  variant?: "progress" | "meter";
+  /** Visible label above the bar, and its accessible name. Without it, pass
+   *  `aria-label` (an indeterminate bar with neither is named `common.loading`). */
+  label?: ReactNode;
+  /** Show the value text at the end of the label row. */
+  showValue?: boolean;
+  /**
+   * The value as words — both the visible `showValue` text and `aria-valuetext`.
+   * Default: the fraction as a percentage in the kit's locale ("42 %" in French).
+   * Pass one for anything that is not a percentage: `(v, max) => \`${v} of ${max} files\``.
+   */
+  formatValue?: (value: number, max: number, min: number) => string;
+  tone?: ProgressBarTone;
+  size?: ProgressBarSize;
+  locale?: string;
+}
+
+/**
+ * A horizontal bar that fills toward `max`.
+ *
+ * keksdose (import progress, budget share bars) and kastlan (upload and job
+ * progress) each drew their own div-in-a-div. None had a role, so a reader heard
+ * nothing at all; the share bars that did have one claimed to be progress.
+ *
+ * `aria-valuetext` is always set when there is a value: a bare `aria-valuenow="37"`
+ * is read as "37" by some readers and "37 percent" by others, and neither is right
+ * when `max` is 212 files.
+ *
+ * The indeterminate sweep stops under `prefers-reduced-motion`. It becomes a still,
+ * half-strength bar across the whole track — still visibly "something is happening",
+ * with nothing moving. The sweep is a Tailwind arbitrary `animate-[…]` rather than
+ * tokens.css's `.animate-indeterminate` class because that one is UNLAYERED, and an
+ * unlayered rule beats every layered utility, `motion-reduce:animate-none` included.
+ */
+export function ProgressBar({
+  value,
+  min = 0,
+  max = 100,
+  variant = "progress",
+  label,
+  showValue = false,
+  formatValue,
+  tone = "brand",
+  size = "md",
+  locale,
+  className,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  ...rest
+}: ProgressBarProps) {
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const kitLocale = useKitLocale(locale);
+  const labelId = useId();
+
+  const meter = variant === "meter";
+  const current = value === undefined || !Number.isFinite(value) ? (meter ? min : undefined) : value;
+  const indeterminate = current === undefined;
+  const span = max - min;
+  const clamped = indeterminate ? undefined : Math.min(max, Math.max(min, current));
+  const fraction = clamped === undefined || span <= 0 ? 0 : (clamped - min) / span;
+
+  const valueText =
+    clamped === undefined
+      ? undefined
+      : formatValue
+        ? formatValue(clamped, max, min)
+        : new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(fraction);
+
+  const labelledBy = ariaLabelledBy ?? (label != null ? labelId : undefined);
+  const name = labelledBy ? undefined : (ariaLabel ?? (indeterminate ? common.loading : undefined));
+
+  return (
+    <div className={cn("min-w-0", className)} data-state={indeterminate ? "indeterminate" : "determinate"}>
+      {(label != null || (showValue && valueText !== undefined)) && (
+        <div className="mb-1 flex items-baseline gap-2 text-sm">
+          {label != null && (
+            <span id={labelId} className="min-w-0 text-[var(--text-secondary)]">
+              {label}
+            </span>
+          )}
+          {showValue && valueText !== undefined && (
+            // Hidden: the same words are the bar's aria-valuetext, and reading them
+            // twice in a row is noise.
+            <span aria-hidden className="ms-auto shrink-0 tabular-nums text-[var(--text-muted)]">
+              {valueText}
+            </span>
+          )}
+        </div>
+      )}
+      <div
+        {...rest}
+        role={meter ? "meter" : "progressbar"}
+        aria-label={name}
+        aria-labelledby={labelledBy}
+        aria-valuemin={indeterminate ? undefined : min}
+        aria-valuemax={indeterminate ? undefined : max}
+        aria-valuenow={clamped}
+        aria-valuetext={valueText}
+        aria-busy={!meter && indeterminate ? true : undefined}
+        // `relative` + `overflow-hidden`: the indeterminate segment is positioned in
+        // here and must not paint past the rounded ends.
+        className={cn("relative w-full overflow-hidden rounded-full bg-[var(--bg-active)]", TRACK_HEIGHT[size])}
+      >
+        {indeterminate ? (
+          <div
+            data-part="fill"
+            className={cn(
+              // `left-0`, deliberately physical: the keyframes (tokens.css
+              // `indeterminate-sweep`) translate along the physical x axis, and under
+              // RTL the same keyframes are run in REVERSE — from the right edge back
+              // to the left. A logical `start-0` would park the segment at the right
+              // in RTL and the reversed sweep would then start off-screen.
+              "absolute inset-y-0 left-0 w-1/3 rounded-full",
+              "animate-[indeterminate-sweep_1.4s_ease-in-out_infinite] rtl:[animation-direction:reverse]",
+              "motion-reduce:w-full motion-reduce:animate-none motion-reduce:opacity-50",
+              FILL[tone],
+            )}
+          />
+        ) : (
+          <div
+            data-part="fill"
+            // Block flow starts at the inline start, so a plain width fills from the
+            // right under `dir="rtl"` with nothing extra.
+            className={cn("h-full rounded-full transition-[width] duration-300 motion-reduce:transition-none", FILL[tone])}
+            style={{ width: `${fraction * 100}%` }}
+          />
+        )}
+      </div>
+    </div>
+  );
+}