@eifi1/ui-kit 0.14.1 → 0.15.0

package/src/components/text-link.tsx

@@ -4,6 +4,7 @@ import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLink } from "../i18n/kit-labels";
 import type { KitLinkComponent } from "../i18n/kit-labels";
+import { documentNavigation } from "../lib/document-navigation";
 
 /* ── Choosing what draws a link ──────────────────────────────────────────── */
 
@@ -98,7 +99,7 @@ export function replacingClick(
     onClick?.(event);
     if (!isPlainNavigationClick(event)) return;
     event.preventDefault();
-    window.location.replace(href);
+    documentNavigation.replace(href);
   };
 }
 

package/src/components/treemap.tsx

@@ -36,8 +36,9 @@ export interface TreemapNode {
   value: number;
   /** Overrides the by-index palette colour for this tile — e.g. to paint every child
    *  in its parent group's colour, so the groups stay legible in one picture. A
-   *  concrete `#rrggbb` keeps the label ink measured; anything else (a CSS var) gets
-   *  `currentColor` ink, because there is nothing to measure — set `labelColor` then. */
+   *  concrete `#rrggbb` or a bare `var(--chart-N)` keeps the label ink measured;
+   *  anything else (another var, a `color-mix()`) gets `currentColor` ink, because
+   *  there is nothing to measure — set `labelColor` then. */
   fill?: string;
   /** The label's ink, for a `fill` the kit cannot measure (a `var()` or `color-mix()`):
    *  keksdose's recency plot fills with `color-mix(in srgb, var(--chart-1) N%,
@@ -146,6 +147,22 @@ function useChartTokenHex(): string[] {
   return joined.split(",");
 }
 
+const CHART_TOKEN_REF = /^var\(\s*--chart-(\d+)\s*\)$/;
+
+/**
+ * The hex a tile fill measures as: the fill itself when it is hex, the live token when
+ * it is a bare `var(--chart-N)` (what `paletteFor` returns), otherwise null. Without
+ * the token case a hand-built recharts map coloured with the kit's own `paletteFor`
+ * got `currentColor` ink — dark page text on dark indigo in the light theme.
+ */
+function measurableFill(fill: string, tokens: readonly string[]): string | null {
+  if (parseHex(fill)) return fill;
+  const m = CHART_TOKEN_REF.exec(fill.trim());
+  if (!m) return null;
+  const hex = tokens[Number(m[1]) - 1];
+  return hex && parseHex(hex) ? hex : null;
+}
+
 // ── Tile ──────────────────────────────────────────────────────────────────
 
 const LABEL_FONT_SIZE = 12;
@@ -214,6 +231,8 @@ export function TreemapCell({
   nodeNote,
   dir = "ltr",
 }: TreemapCellProps) {
+  // Before the early return: a hook has to run on every render of the cell.
+  const tokenHex = useChartTokenHex();
   // Depth 0 is recharts' synthetic root, which spans the whole chart.
   if (!depth) return null;
   // Whole pixels: a rect on a half pixel renders its edge across two half-lit
@@ -223,7 +242,13 @@ export function TreemapCell({
   const pw = Math.round(width);
   const ph = Math.round(height);
   const tileFill = fill ?? "var(--chart-1)";
-  const ink = labelColor ?? textOn(tileFill);
+  const measured = measurableFill(tileFill, tokenHex);
+  const ink = labelColor ?? (measured ? textOn(measured) : "currentColor");
+  // The halo only on an OPAQUE fill we could measure. A translucent fill (a
+  // `color-mix(… transparent)`) composited twice — once as the tile, once as the halo
+  // over it — draws a darker ring round every glyph, which read as doubled text on the
+  // faded tiles. `none` still overrides the inherited chart `stroke`.
+  const halo = measured ? tileFill : "none";
   // Below ~44x20 there is no room for a readable word, so no label at all rather than
   // a one-letter stub bleeding over the tile edge.
   const label = pw >= 44 && ph >= 20 ? fitLabel(name ?? "", pw, LABEL_FONT_SIZE) : null;
@@ -284,7 +309,7 @@ export function TreemapCell({
           y={py + 15}
           direction={dir}
           fill={ink}
-          stroke={tileFill}
+          stroke={halo}
           strokeWidth={2.5}
           strokeLinejoin="round"
           paintOrder="stroke"
@@ -302,7 +327,7 @@ export function TreemapCell({
           direction={dir}
           fill={ink}
           fillOpacity={0.85}
-          stroke={tileFill}
+          stroke={halo}
           strokeWidth={2.5}
           strokeLinejoin="round"
           paintOrder="stroke"

package/src/components/ui.tsx

@@ -2,6 +2,7 @@ import { forwardRef, useId, useLayoutEffect, useRef, useState } from "react";
 import { ChevronDown, Eye, EyeOff, HelpCircle, Plus, X } from "lucide-react";
 import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ComponentPropsWithoutRef, CSSProperties, InputHTMLAttributes, KeyboardEvent, MouseEvent, ReactElement, ReactNode, Ref, SelectHTMLAttributes, TextareaHTMLAttributes } from "react";
 import { cn } from "../lib/cn";
+import { scrollIntoStrip, useStripFade } from "../lib/strip-fade";
 import { horizontalStep } from "../lib/direction";
 import { useMediaQuery } from "../hooks/use-media-query";
 import { Tooltip, type TooltipSide } from "./tooltip";
@@ -1290,9 +1291,20 @@ export const FIELD_DISPLAY =
 // adjacent controls). Pair the labelled case with a static FieldLabel.
 // `relative` so the trigger can host an absolutely-centred FieldChevron / clear
 // button the way the native Select does.
+//
+// `[&>:first-child]:min-h-[1lh]` holds one line box open whatever the value is. A
+// trigger with nothing chosen and no placeholder renders an EMPTY value span, an
+// empty span has no line box, and the trigger collapsed to its padding — 18px
+// tall in a stack of 38px fields (an RhfCombobox without a placeholder; DatePicker
+// and MonthPicker had met the same thing as Keksdose live #294 and patched their
+// own span with a U+00A0). Here, on the shared class, it covers every trigger
+// built on it, including a `renderTrigger` one. `1lh` rather than a fixed height
+// so it tracks whatever type the trigger is set in; the first child is the value
+// in every trigger here (the chevron and the clear button are absolute).
 export const FIELD_TRIGGER = cn(
   FIELD_BASE,
   "relative flex items-center justify-between gap-2 text-start hover:bg-[var(--bg-hover)]",
+  "[&>:first-child]:min-h-[1lh]",
 );
 
 /** An alias rather than an interface: the chevron adds nothing of its own to an
@@ -1871,7 +1883,11 @@ export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement
   invalid?: boolean;
   /** See {@link Input}'s `error`. */
   error?: ReactNode;
-  /** A {@link FieldHint} for the label line — see {@link FloatingField}. */
+  /** A {@link FieldHint} for the label line — see {@link FloatingField}. Plain
+   *  TEXT (a string or a number) is a caption instead, and goes UNDER the field
+   *  like every other field's hint, attached through `aria-describedby`: the label
+   *  line is 11px of strip shared with the label, and a sentence placed there was
+   *  set in the value's type on top of both the label and the value. */
   hint?: ReactNode;
   /**
    * `"sm"`: a 28px, 12px-type select for a toolbar or a table header, where the
@@ -1911,12 +1927,33 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
   const listBox = (nativeSize !== undefined && nativeSize > 1) || Boolean(rest.multiple);
   const small = size === "sm" && label === undefined;
   const fieldId = id ?? generated;
+  const hintId = useId();
+  // Text is a caption under the field; anything else (a FieldHint) rides the label
+  // line. See `hint` above. An empty string is no caption at all.
+  const textHint = (typeof hint === "string" && hint !== "") || typeof hint === "number";
   const { isInvalid, describedBy, errorEl } = useFieldError(
     error,
     invalid,
-    rest["aria-describedby"],
+    // The caption goes in BEFORE the error — the standing advice first, the news
+    // second, the order useFieldError keeps for a caller's own description.
+    textHint
+      ? rest["aria-describedby"]
+        ? `${rest["aria-describedby"]} ${hintId}`
+        : hintId
+      : rest["aria-describedby"],
     rest["aria-invalid"],
   );
+  const below =
+    textHint || errorEl !== null ? (
+      <>
+        {textHint && (
+          <p id={hintId} className="mt-1 text-[11px] leading-tight text-[var(--text-muted)]">
+            {hint}
+          </p>
+        )}
+        {errorEl}
+      </>
+    ) : null;
   // Custom chevron (native arrow hidden via appearance-none) so it sits a touch
   // in from the end border and matches both themes — feedback #223. A DISABLED
   // select has no menu to drop, so it drops the chevron too: the arrow is the one
@@ -1927,10 +1964,17 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
       <FieldChevron className={small ? "end-1.5 size-3.5" : undefined} />
     );
   // `pe-9` is the room the chevron takes; a list box has none to make room for.
-  const dress = listBox ? "overflow-y-auto" : "appearance-none pe-9";
+  //
+  // A list box's height is `size` rows plus its padding, but its rows are clipped at
+  // the PADDING edge, not the content edge — so FIELD_BASE's `pb-2` showed the next
+  // row through the bottom padding: `size={4}` drew four and a half. The vertical room
+  // moves onto the rows instead (option padding counts toward the row height the
+  // browser sizes the box by), and the box keeps no bottom padding: exactly `size`
+  // whole rows, at any width.
+  const dress = listBox ? "overflow-y-auto [&_option]:py-1" : "appearance-none pe-9";
   if (label === undefined) {
     return (
-      <FieldGroup errorEl={errorEl}>
+      <FieldGroup errorEl={below}>
         <div className={cn("relative", className)}>
           <select
             ref={ref}
@@ -1953,6 +1997,7 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
             className={cn(
               FIELD_BASE,
               dress,
+              listBox && "py-0",
               small && SELECT_SM,
               selectClassName,
               isInvalid && FIELD_INVALID,
@@ -1966,8 +2011,8 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
     );
   }
   return (
-    <FieldGroup errorEl={errorEl}>
-      <FloatingField className={className} htmlFor={fieldId} label={label} staticLabel hint={hint}>
+    <FieldGroup errorEl={below}>
+      <FloatingField className={className} htmlFor={fieldId} label={label} staticLabel hint={textHint ? undefined : hint}>
         <select
           ref={ref}
           id={fieldId}
@@ -1978,8 +2023,9 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
           className={cn(
             FIELD_BASE,
             // The floated label takes the top strip of a list box too, so its first
-            // row starts under the label rather than behind it.
-            listBox ? "pt-5 pb-1" : FIELD_FLOATING_PAD,
+            // row starts under the label rather than behind it. No bottom padding — see
+            // `dress`.
+            listBox ? "pt-5 pb-0" : FIELD_FLOATING_PAD,
             "peer",
             dress,
             selectClassName,
@@ -2695,6 +2741,10 @@ const TAB_EMPTY_CLASSES = "-mx-1.5 rounded border border-dashed border-[var(--bo
 const TAB_ADD_CLASSES =
   "inline-flex items-center gap-1 whitespace-nowrap rounded-md px-3 py-2 text-sm font-medium text-[var(--text-muted)] transition-colors hover:text-[var(--text-primary)] focus:outline-none focus:ring-2 focus:ring-[var(--border-strong)] disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:size-4";
 const TAB_ADD_WRAP_CLASSES = "px-2.5 text-xs md:px-3 md:text-sm";
+// `relative`: the phone's visually hidden label needs a positioned ancestor (see the
+// sr-only rule in CONTRIBUTING); `max-md:px-2` squares the lone "+".
+const TAB_ADD_PHONE_CLASSES = "relative max-md:px-2";
+
 
 export function Tabs<T extends string>({
   tabs,
@@ -2719,6 +2769,18 @@ export function Tabs<T extends string>({
   const phone = useMediaQuery(PHONE_QUERY, false);
   const vertical = orientation === "vertical" && !phone;
   const stripRef = useRef<HTMLDivElement>(null);
+  const fade = useStripFade(stripRef);
+  // The OPEN tab is scrolled into the strip whenever it changes — on mount too, for a
+  // deep link to the seventh report. A selection behind the cut edge was the worst
+  // case of the overflow above: the one tab the panel below belongs to, sliced to
+  // "80 km," under the add button. Only the strip scrolls (`scrollBy` on it, not
+  // `scrollIntoView`, which would scroll the page as well), and only as far as needed
+  // to clear the fade.
+  useLayoutEffect(() => {
+    const strip = stripRef.current;
+    const tab = strip?.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]');
+    if (strip && tab) scrollIntoStrip(strip, tab);
+  }, [active]);
   const isRemovable = (tab: TabItem<T>) => onRemove !== undefined && tab.removable !== false;
   // Whether Delete reaches this tab: every removable tab, or only the open one.
   const deletesOnKey = (tab: TabItem<T>) =>
@@ -2821,6 +2883,11 @@ export function Tabs<T extends string>({
       // Only when vertical: `horizontal` is the tablist's implicit value, and the
       // attribute on every existing strip would be noise in every snapshot of them.
       aria-orientation={vertical ? "vertical" : undefined}
+      // Merged over a caller's own style rather than replacing it; see useStripFade.
+      // `data-overflow` names the cut ends in reading-direction terms, for a caller's
+      // own affordance (a scroll button) and for tests, which cannot read the mask.
+      style={fade.mask ? { ...rest.style, maskImage: fade.mask, WebkitMaskImage: fade.mask } : rest.style}
+      data-overflow={fade.overflow}
       // With an add button the strip gains an outer box, and `className` goes there
       // — it is the box a caller's margin or width is meant for.
       className={cn(
@@ -2892,7 +2959,16 @@ export function Tabs<T extends string>({
                 {/* A separator for the NAME only — whitespace between flex items is
                     not drawn, and without it the two lines ran together into one
                     word for a screen reader ("80 km/hloop 2"). */}{" "}
-                <span className="text-[11px] font-normal leading-tight text-[var(--text-muted)]">
+                <span
+                  className={cn(
+                    "text-[11px] font-normal leading-tight text-[var(--text-muted)]",
+                    // On a wrapped strip's filled chip (below `md`) the muted grey
+                    // was dark text on the brand fill — "loop 2" all but vanished
+                    // under the one label that most needed reading. It takes the
+                    // chip's own ink instead, as the label and the × already do.
+                    wrap && isActive && !vertical && "text-[var(--brand-contrast)] md:text-[var(--text-muted)]",
+                  )}
+                >
                   {tab.detail}
                 </span>
               </span>
@@ -3013,10 +3089,14 @@ export function Tabs<T extends string>({
           type="button"
           onClick={onAdd}
           disabled={busy}
-          className={cn(TAB_ADD_CLASSES, wrap && TAB_ADD_WRAP_CLASSES)}
+          className={cn(TAB_ADD_CLASSES, wrap ? TAB_ADD_WRAP_CLASSES : TAB_ADD_PHONE_CLASSES)}
         >
           <Plus aria-hidden />
-          {addLabel ?? text.add}
+          {/* Below md a scrolling strip keeps the room for tabs: the label is visually
+              hidden and the "+" carries it as its name. Beside "+ Add loop" a 390px strip
+              showed the open tab and a sliver of the next (showcase audit). A wrapping
+              strip has its own row there, so it keeps the label. */}
+          <span className={wrap ? undefined : "max-md:sr-only"}>{addLabel ?? text.add}</span>
         </button>
       </div>
     </div>

package/src/feedback/feedback-dialog.tsx

@@ -53,6 +53,9 @@ export interface FeedbackDialogTextLabels {
   category: string;
   subject: string;
   body: string;
+  /** The body's label when `requireBody={false}`: "What happened? (optional)".
+   *  Optional, so a complete `UiKitLabels` typed before 0.14.2 still compiles. */
+  bodyOptional?: string;
   /** The heading over the attachment buttons. */
   attachment: string;
   /** The line beside the buttons naming the shortcut. */
@@ -66,6 +69,7 @@ export const DEFAULT_FEEDBACK_DIALOG_LABELS: FeedbackDialogTextLabels = {
   category: "Category",
   subject: "Subject",
   body: "What happened?",
+  bodyOptional: "What happened? (optional)",
   attachment: "Screenshot",
   submitHint: "Ctrl/⌘ + Enter to send",
   cancel: "Cancel",
@@ -108,6 +112,7 @@ export function FeedbackDialog({
   maxAttachmentBytes = DEFAULT_MAX_ATTACHMENT_BYTES,
   onAttachmentError,
   onCaptureScreenshot,
+  requireBody = true,
 }: {
   open: boolean;
   onClose: () => void;
@@ -129,6 +134,12 @@ export function FeedbackDialog({
    * attachment"; the returned file is fed through the same validation + preview.
    */
   onCaptureScreenshot?: () => Promise<File | null>;
+  /**
+   * `false`: a report with only a subject can be sent, and the body's label says it is
+   * optional (`bodyOptional`, unless `labels.body` is passed). Default `true`, the
+   * dialog's behaviour until 0.14.2 (keksdose K1: its backend takes title-only reports).
+   */
+  requireBody?: boolean;
 }) {
   const [title, setTitle] = useState("");
   const [body, setBody] = useState("");
@@ -151,7 +162,9 @@ export function FeedbackDialog({
     }
   }
 
-  const canSubmit = !!title && !!body && !submitting;
+  // Trimmed: a subject or body of spaces is empty (keksdose's API answers a blank title
+  // with a 422, and a blank report is no report).
+  const canSubmit = !!title.trim() && (!requireBody || !!body.trim()) && !submitting;
   const trySubmit = () => {
     if (canSubmit) void onSubmit({ title, body, category, attachment });
   };
@@ -174,7 +187,12 @@ export function FeedbackDialog({
     <Input label={labels.subject} value={title} onChange={(e) => setTitle(e.target.value)} variant="display" />
   );
   const bodyField = (
-    <Textarea rows={5} label={labels.body} value={body} onChange={(e) => setBody(e.target.value)} />
+    <Textarea
+      rows={5}
+      label={requireBody ? labels.body : (labelsProp?.body ?? labels.bodyOptional ?? labels.body)}
+      value={body}
+      onChange={(e) => setBody(e.target.value)}
+    />
   );
   const attachmentField = (
     <FeedbackAttachmentField

package/src/feedback/feedback-thread.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import type { ReactNode, Ref } from "react";
-import { Paperclip, Send } from "lucide-react";
+import { ImageIcon, ImageOff, Paperclip, Send } from "lucide-react";
 import { cn } from "../lib/cn";
 import { formatDate, formatRelativeTime } from "../lib/format";
 import { Button, EmptyState, Spinner, Textarea } from "../components/ui";
@@ -336,18 +336,7 @@ function DefaultAttachment({
   size: (bytes: number) => string;
 }) {
   const { name, url, type } = attachment;
-  if (url && type?.startsWith("image/")) {
-    return (
-      <a href={url} target="_blank" rel="noopener noreferrer" className="block">
-        <img
-          src={url}
-          alt={name}
-          loading="lazy"
-          className="h-20 w-20 rounded border border-[var(--border)] object-cover"
-        />
-      </a>
-    );
-  }
+  if (url && type?.startsWith("image/")) return <ImageThumbnail url={url} name={name} />;
   const content = (
     <>
       <Paperclip className="size-3.5 shrink-0" aria-hidden />
@@ -368,6 +357,40 @@ function DefaultAttachment({
   );
 }
 
+/** An image attachment's thumbnail. The box is drawn before the picture arrives —
+ *  `loading="lazy"` leaves it empty until it nears the viewport, and a URL that has
+ *  expired never fills it — and an empty bordered square read as a broken layout, not
+ *  as a picture. So the box carries an image glyph underneath until the picture
+ *  covers it, and swaps it for a broken-image glyph when the load fails. */
+function ImageThumbnail({ url, name }: { url: string; name: string }) {
+  // Keyed on the URL, so a message whose attachment is replaced tries the new one.
+  const [failedUrl, setFailedUrl] = useState<string | null>(null);
+  const failed = failedUrl === url;
+  const Glyph = failed ? ImageOff : ImageIcon;
+  return (
+    <a
+      href={url}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="relative block h-20 w-20 overflow-hidden rounded border border-[var(--border)] bg-[var(--bg-surface-2)]"
+    >
+      <Glyph aria-hidden className="absolute inset-0 m-auto size-6 text-[var(--text-muted)]" />
+      {!failed && (
+        // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- load/error are resource events, not interactions
+        <img
+          src={url}
+          alt={name}
+          loading="lazy"
+          onError={() => setFailedUrl(url)}
+          className="relative h-full w-full object-cover"
+        />
+      )}
+      {/* The <img> and its alt are gone once it failed; the link still needs a name. */}
+      {failed && <span className="sr-only">{name}</span>}
+    </a>
+  );
+}
+
 /** The time, refreshed once a minute while `active`, so "2 minutes ago" does not stay
  *  "just now" on a page left open. Read in state rather than in render, which must be
  *  pure. */

package/src/i18n/locales/de.ts

@@ -26,6 +26,7 @@ export function uiKitLabelsDe(numberLocale = "de-DE"): UiKitLabels {
       category: "Kategorie",
       subject: "Betreff",
       body: "Was ist passiert?",
+      bodyOptional: "Was ist passiert? (optional)",
       attachment: "Screenshot",
       submitHint: "Strg/⌘ + Enter zum Senden",
       cancel: "Abbrechen",

package/src/i18n/locales/es.ts

@@ -27,6 +27,7 @@ export function uiKitLabelsEs(numberLocale = "es-ES"): UiKitLabels {
       category: "Categoría",
       subject: "Asunto",
       body: "¿Qué ha pasado?",
+      bodyOptional: "¿Qué ha pasado? (opcional)",
       attachment: "Captura de pantalla",
       submitHint: "Ctrl/⌘ + Intro para enviar",
       cancel: "Cancelar",

package/src/i18n/locales/fr.ts

@@ -27,6 +27,7 @@ export function uiKitLabelsFr(numberLocale = "fr-FR"): UiKitLabels {
       category: "Catégorie",
       subject: "Objet",
       body: "Que s’est-il passé\u202f?",
+      bodyOptional: "Que s’est-il passé\u202f? (facultatif)",
       attachment: "Capture d’écran",
       submitHint: "Ctrl/⌘ + Entrée pour envoyer",
       cancel: "Annuler",

package/src/i18n/locales/hu.ts

@@ -26,6 +26,7 @@ export function uiKitLabelsHu(numberLocale = "hu-HU"): UiKitLabels {
       category: "Kategória",
       subject: "Tárgy",
       body: "Mi történt?",
+      bodyOptional: "Mi történt? (nem kötelező)",
       attachment: "Képernyőkép",
       submitHint: "Ctrl/⌘ + Enter a küldéshez",
       cancel: "Mégse",

package/src/i18n/locales/it.ts

@@ -27,6 +27,7 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
       category: "Categoria",
       subject: "Oggetto",
       body: "Cosa è successo?",
+      bodyOptional: "Cosa è successo? (facoltativo)",
       attachment: "Screenshot",
       submitHint: "Ctrl/⌘ + Invio per inviare",
       cancel: "Annulla",

package/src/i18n/locales/zh.ts

@@ -26,6 +26,7 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       category: "类别",
       subject: "主题",
       body: "发生了什么？",
+      bodyOptional: "发生了什么？（可选）",
       attachment: "截图",
       submitHint: "Ctrl/⌘ + Enter 发送",
       cancel: "取消",

package/src/index.ts

@@ -83,6 +83,7 @@ export * from "./components/numpad-sheet";
 export * from "./components/number-input";
 export * from "./components/currency-select";
 export * from "./components/amount-input";
+export * from "./components/money-field";
 export * from "./components/combobox";
 export * from "./components/picker-sheet";
 export * from "./components/entity-combobox";

package/src/lib/document-navigation.ts

@@ -0,0 +1,17 @@
+/**
+ * The full-document navigations the kit makes, behind one object the tests can spy on.
+ *
+ * jsdom implements neither `location.reload` nor `location.replace`, and its
+ * `window.location` is unforgeable: a test cannot stub it by redefining the property
+ * once the suite runs each file in its own VM context (`pool: "vmThreads"`, which took
+ * the suite from ~3 minutes to ~1). `vi.spyOn(documentNavigation, "reload")` works in
+ * every pool. Internal, not part of the package's surface.
+ */
+export const documentNavigation = {
+  reload(): void {
+    window.location.reload();
+  },
+  replace(href: string): void {
+    window.location.replace(href);
+  },
+};

package/src/lib/strip-fade.ts

@@ -0,0 +1,82 @@
+import { useLayoutEffect, useState, type RefObject } from "react";
+
+// How far the fade at a scrolled strip's cut edge reaches, and how much room a tab
+// brought into view keeps from that edge so the fade never lies on top of it.
+export const TAB_FADE_PX = 24;
+
+/**
+ * Shared by Tabs' strip and AppShell's scrolling phone sub-nav; internal, not part of
+ * the package's surface.
+ *
+ * Which ends of a sideways-scrolling strip have tabs cut off behind them, as the
+ * `mask-image` that fades those ends out — or `undefined` while everything fits.
+ *
+ * A strip that overflowed used to stop dead at its edge: the last tab sliced through
+ * mid-word, and nothing on a phone (whose scrollbars are overlays that only show
+ * while you drag) said there was more to reach. A fade is the cue — the letters
+ * thin out rather than end — and it is measured, not assumed, so a strip that fits
+ * is painted exactly as before. Physical `left`/`right` in the gradient, because
+ * `mask-image` has no logical directions; the reading direction is read from the
+ * element, and `scrollLeft` is a magnitude here because an RTL strip counts it
+ * negative from the start edge.
+ */
+export function useStripFade(
+  ref: RefObject<HTMLElement | null>,
+): { mask: string | undefined; overflow: "start" | "end" | "both" | undefined } {
+  const [edges, setEdges] = useState({ left: false, right: false, rtl: false });
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const measure = () => {
+      const hidden = el.scrollWidth - el.clientWidth;
+      const scrolled = Math.abs(el.scrollLeft);
+      const rtl = getComputedStyle(el).direction === "rtl";
+      const atStart = scrolled > 1;
+      const atEnd = hidden - scrolled > 1;
+      const left = rtl ? atEnd : atStart;
+      const right = rtl ? atStart : atEnd;
+      setEdges((prev) =>
+        prev.left === left && prev.right === right && prev.rtl === rtl ? prev : { left, right, rtl },
+      );
+    };
+    measure();
+    el.addEventListener("scroll", measure, { passive: true });
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
+    observer?.observe(el);
+    // The tabs, too: a label or a badge that grows changes the overflow without
+    // resizing the strip's own box.
+    for (const child of Array.from(el.children)) observer?.observe(child);
+    return () => {
+      el.removeEventListener("scroll", measure);
+      observer?.disconnect();
+    };
+  });
+  if (!edges.left && !edges.right) return { mask: undefined, overflow: undefined };
+  const l = edges.left ? `transparent, #000 ${TAB_FADE_PX}px` : "#000";
+  const r = edges.right ? `#000 calc(100% - ${TAB_FADE_PX}px), transparent` : "#000";
+  const rtl = edges.rtl;
+  const start = rtl ? edges.right : edges.left;
+  const end = rtl ? edges.left : edges.right;
+  return {
+    mask: `linear-gradient(to right, ${l}, ${r})`,
+    overflow: start && end ? "both" : start ? "start" : "end",
+  };
+}
+
+/**
+ * Scroll `item` into view inside `strip` — the strip only (`scrollBy` on it, never
+ * `scrollIntoView`, which would scroll the page too) — far enough to clear the fade.
+ * A no-op when the strip fits or the item is already clear of both edges.
+ */
+export function scrollIntoStrip(strip: HTMLElement, item: HTMLElement): void {
+  if (strip.scrollWidth <= strip.clientWidth) return;
+  const s = strip.getBoundingClientRect();
+  const t = item.getBoundingClientRect();
+  const delta =
+    t.left < s.left + TAB_FADE_PX
+      ? t.left - s.left - TAB_FADE_PX
+      : t.right > s.right - TAB_FADE_PX
+        ? t.right - s.right + TAB_FADE_PX
+        : 0;
+  if (delta !== 0) strip.scrollBy({ left: delta });
+}

package/src/rhf/form.tsx

@@ -197,7 +197,9 @@ export function FormItem({ className, ...rest }: FormItemProps) {
   const value = useMemo(() => ({ id, mounted, mark }), [id, mounted, mark]);
   return (
     <FormItemContext.Provider value={value}>
-      <div data-slot="form-item" {...rest} className={cn("grid gap-1", className)} />
+      {/* `content-start`: stretched to a taller neighbour's height in a grid row, the
+          item gave the extra to its rows and its control sat lower (showcase audit). */}
+      <div data-slot="form-item" {...rest} className={cn("grid content-start gap-1", className)} />
     </FormItemContext.Provider>
   );
 }