torch-glare 2.5.3 → 2.5.5

package/apps/lib/components/DataViews/views/table-view.tsx

@@ -125,162 +125,194 @@ function TableViewImpl({
         )}
       >
         <div className="flex flex-1 flex-col gap-4 overflow-hidden">
-          <div
-            ref={scrollRef}
-            // `min-w-0` so the scroller can be narrower than the table inside it. Without it a flex
-            // item refuses to shrink below its content, so pinning the table to its natural width
-            // pushes the whole component wide instead of scrolling within it.
-            className="min-w-0 flex-1 overflow-auto rounded-lg"
-          >
-            <Table ref={tableRef} className="w-full">
-              {/* The header sticks to the scroller above by default — that lives on `TableHeader`
-                  in the primitive. Two things this view adds:
+          {/* The scroller and the end action are stacked here with NO gap, so the bar sits flush
+              under the table the way it does on the card. `min-h-0` lets the scroller actually
+              shrink — a flex item will not go below its content without it. */}
+          <div className="flex min-h-0 flex-1 flex-col">
+            <div
+              ref={scrollRef}
+              // `min-w-0` so the scroller can be narrower than the table inside it. Without it a flex
+              // item refuses to shrink below its content, so pinning the table to its natural width
+              // pushes the whole component wide instead of scrolling within it.
+              className="min-w-0 flex-1 overflow-auto rounded-lg"
+            >
+              {/* Sizes the table, not the footer — the end action now lives outside this scroller.
+                  Inside an `overflow-auto` scroller a child's `w-full` resolves against the *visible*
+                  width, so the table needs `w-max` to reach its natural width and scroll; `min-w-full`
+                  keeps it filling the scroller when the table is narrower. */}
+              <div className="w-max min-w-full">
+                {/* `overflow-visible` opts out of the primitive's `overflow-hidden` (tailwind-merge
+                  lets ours win). It has to: a clipping table is its own scrollport, and the sticky
+                  header would then resolve against a box that never scrolls. Safe here because the
+                  scroller above is `min-w-0 overflow-auto`, so a wide table scrolls inside it rather
+                  than pushing the layout. */}
+                <Table ref={tableRef} className="w-full overflow-visible">
+                  {/* The header sticks to the scroller above by default — that lives on `TableHeader`
+                    in the primitive. Two things this view adds:
 
-                  Opacity. The primitive's header token is translucent, so scrolling rows read
-                  straight through it; the primitive can't fix that without naming a surface colour
-                  it doesn't know. Here the surface *is* known — the view root above sets
-                  `form-base` — so paint that as the background-color (tailwind-merge drops the
-                  primitive's translucent one, same `bg-color` group) and re-apply the tint as a
-                  background-image, which stacks above background-color. Composited that is the
-                  exact colour the header already had, just no longer see-through.
+                    Opacity. The primitive's header token is translucent, so scrolling rows read
+                    straight through it; the primitive can't fix that without naming a surface colour
+                    it doesn't know. Here the surface *is* known — the view root above sets
+                    `form-base` — so paint that as the background-color (tailwind-merge drops the
+                    primitive's translucent one, same `bg-color` group) and re-apply the tint as a
+                    background-image, which stacks above background-color. Composited that is the
+                    exact colour the header already had, just no longer see-through.
 
-                  And `shadow-none`, because the drop shadow reads as a seam now that the view
-                  carries its own border. */}
-              <TableHeader className="bg-background-presentation-form-base bg-[image:linear-gradient(var(--background-presentation-form-header),var(--background-presentation-form-header))] shadow-none">
-                <TableRow>
-                  {onRowMove && <TableHead isDummy className="w-8" />}
-                  {selectable && (
-                    <TableHead isDummy className="w-12">
-                      {/* Size is stated on both this and the per-row checkbox rather than left to
-                          `Checkbox`'s default — they have to agree, and relying on the default on
-                          one side only is what previously made the select-all bigger than the
-                          column it heads. */}
-                      <Checkbox
-                        size="M"
-                        checked={allSelected ? true : someSelected ? "indeterminate" : false}
-                        onCheckedChange={toggleAll}
-                        aria-label="Select all rows"
-                      />
-                    </TableHead>
-                  )}
-                  {/* Keyed by position: two fields may share a `path` — the same value shown two
-                    ways — and keying on it would collide. */}
-                  {visibleFields.map((field, i) => (
-                    <TableHead
-                      key={`${field.path}-${i}`}
-                      size="M"
-                      sortType={sort?.path === field.path ? sort.direction : undefined}
-                      onSort={() => setSort(cycle(field.path))}
-                      // Without this every sort control announces itself as a bare "Sort ascending",
-                      // so a screen reader hears one identical button per column.
-                      sortLabel={field.label ?? formatPathLabel(field.path)}
-                    >
-                      {/* Wrapped rather than handed to `Table` as bare text: `truncate` needs a box
-                          to clip, and the label's parent in the primitive is already `flex min-w-0`
-                          so this span shrinks and ellipsises instead of wrapping the header row
-                          onto a second line. */}
-                      <span className="truncate">{field.label ?? field.path}</span>
-                    </TableHead>
-                  ))}
-                </TableRow>
-              </TableHeader>
+                    And `shadow-none`, because the drop shadow reads as a seam now that the view
+                    carries its own border. */}
+                  <TableHeader className="bg-background-presentation-form-base bg-[image:linear-gradient(var(--background-presentation-form-header),var(--background-presentation-form-header))] shadow-none">
+                    <TableRow>
+                      {onRowMove && <TableHead isDummy className="w-8" />}
+                      {selectable && (
+                        <TableHead isDummy className="w-12">
+                          {/* Size is stated on both this and the per-row checkbox rather than left to
+                            `Checkbox`'s default — they have to agree, and relying on the default on
+                            one side only is what previously made the select-all bigger than the
+                            column it heads. */}
+                          <Checkbox
+                            size="M"
+                            checked={allSelected ? true : someSelected ? "indeterminate" : false}
+                            onCheckedChange={toggleAll}
+                            aria-label="Select all rows"
+                          />
+                        </TableHead>
+                      )}
+                      {/* Keyed by position: two fields may share a `path` — the same value shown two
+                      ways — and keying on it would collide. */}
+                      {visibleFields.map((field, i) => (
+                        <TableHead
+                          key={`${field.path}-${i}`}
+                          size="M"
+                          sortType={sort?.path === field.path ? sort.direction : undefined}
+                          onSort={() => setSort(cycle(field.path))}
+                          // Without this every sort control announces itself as a bare "Sort ascending",
+                          // so a screen reader hears one identical button per column.
+                          sortLabel={field.label ?? formatPathLabel(field.path)}
+                        >
+                          {/* Wrapped rather than handed to `Table` as bare text: `truncate` needs a box
+                            to clip, and the label's parent in the primitive is already `flex min-w-0`
+                            so this span shrinks and ellipsises instead of wrapping the header row
+                            onto a second line. */}
+                          <span className="truncate">{field.label ?? field.path}</span>
+                        </TableHead>
+                      ))}
+                    </TableRow>
+                  </TableHeader>
 
-              <TableBody>
-                {loading && <SkeletonRows fields={visibleFields} grip={Boolean(onRowMove)} selectable={selectable} />}
-                {virtualize && padTop > 0 && (
-                  <tr aria-hidden style={{ height: padTop }} />
-                )}
-                <DragList ids={ids}>
-                  {renderIndexes.map((index) => {
-                    const row = rows[index];
-                    const id = ids[index];
-                    const selected = selection.includes(id);
-                    return (
-                      <DraggableRow
-                        key={id}
-                        id={id}
-                        draggable={Boolean(onRowMove)}
-                        state={selected ? "selected" : undefined}
-                        onClick={onRowClick ? () => onRowClick(row, id) : undefined}
-                        // A clickable row has to be reachable without a mouse. `<tr>` carries no
-                        // implicit role, so a bare `onClick` is invisible to the keyboard and to a
-                        // screen reader; these only appear when the row is actually interactive.
-                        tabIndex={onRowClick ? 0 : undefined}
-                        role={onRowClick ? "button" : undefined}
-                        onKeyDown={
-                          onRowClick
-                            ? (e) => {
-                              if (e.key !== "Enter" && e.key !== " ") return;
-                              if (e.target !== e.currentTarget) return;
-                              e.preventDefault();
-                              onRowClick(row, id);
+                  <TableBody>
+                    {loading && <SkeletonRows fields={visibleFields} grip={Boolean(onRowMove)} selectable={selectable} />}
+                    {virtualize && padTop > 0 && (
+                      <tr aria-hidden style={{ height: padTop }} />
+                    )}
+                    <DragList ids={ids}>
+                      {renderIndexes.map((index) => {
+                        const row = rows[index];
+                        const id = ids[index];
+                        const selected = selection.includes(id);
+                        return (
+                          <DraggableRow
+                            key={id}
+                            id={id}
+                            draggable={Boolean(onRowMove)}
+                            state={selected ? "selected" : undefined}
+                            onClick={onRowClick ? () => onRowClick(row, id) : undefined}
+                            // A clickable row has to be reachable without a mouse. `<tr>` carries no
+                            // implicit role, so a bare `onClick` is invisible to the keyboard and to a
+                            // screen reader; these only appear when the row is actually interactive.
+                            tabIndex={onRowClick ? 0 : undefined}
+                            role={onRowClick ? "button" : undefined}
+                            onKeyDown={
+                              onRowClick
+                                ? (e) => {
+                                  if (e.key !== "Enter" && e.key !== " ") return;
+                                  if (e.target !== e.currentTarget) return;
+                                  e.preventDefault();
+                                  onRowClick(row, id);
+                                }
+                                : undefined
                             }
-                            : undefined
-                        }
-                        className={cn(
-                          // 40px per Figma's `Table-RowBackgroand-1.1`. `Table`'s body cells default
-                          // to 50, and the two live on different elements, so the cells below must be
-                          // told as well or CSS keeps the larger.
-                          "h-[40px]",
-                          "focus-visible:ring-border-presentation-state-focus outline-none focus-visible:ring-2",
-                          onRowClick && "cursor-pointer",
-                        )}
-                      >
-                        {onRowMove && <GripCell />}
-                        {selectable && (
-                          <TableCell isDummy className="h-[40px] w-12" onClick={(e) => e.stopPropagation()}>
-                            {/* What `TableCheckbox` renders, inlined: its props are typed as button
-                            attributes, so it cannot express a controlled checkbox. */}
-                            <div className="flex items-center justify-center">
-                              <Checkbox
-                                size="M"
-                                checked={selected}
-                                onCheckedChange={() => toggleRow(id)}
-                                aria-label="Select row"
-                              />
-                            </div>
-                          </TableCell>
-                        )}
-                        {visibleFields.map((field, i) => {
-                          // `undefined` means "you paint it" — distinct from `null`, which is a
-                          // deliberate blank.
-                          const custom = renderCell?.({ field, row, id, index, fields: visibleFields });
-                          return (
-                            <TableCell key={`${field.path}-${i}`} className="h-[40px]">
-                              {/* `isolate` confines the Badge's mix-blend-luminosity to a local
-                              stacking context and `transform-gpu` promotes it to its own layer, so
-                              the table's post-mount column reflow repaints cleanly instead of
-                              leaving a ghosted badge frame. */}
-                              <span className="isolate inline-flex transform-gpu">
-                                {custom === undefined ? <Cell field={field} row={row} /> : custom}
-                              </span>
-                            </TableCell>
-                          );
-                        })}
-                      </DraggableRow>
-                    );
-                  })}
-                </DragList>
-                {virtualize && padBottom > 0 && (
-                  <tr aria-hidden style={{ height: padBottom }} />
-                )}
-                {/* The trigger. A row of its own rather than an element after the table, so it sits
-                  inside the same scroller the rows do. */}
-                {hasMore && !loading && (
-                  <tr ref={sentinelRef as React.Ref<HTMLTableRowElement>} aria-hidden>
-                    <td style={{ height: 1, padding: 0, border: 0 }} colSpan={100} />
-                  </tr>
-                )}
-                {loadingMore && (
-                  <SkeletonRows
-                    rows={2}
-                    fields={visibleFields}
-                    grip={Boolean(onRowMove)}
-                    selectable={selectable}
-                  />
-                )}
-              </TableBody>
-            </Table>
+                            className={cn(
+                              // 40px per Figma's `Table-RowBackgroand-1.1`. `Table`'s body cells default
+                              // to 50, and the two live on different elements, so the cells below must be
+                              // told as well or CSS keeps the larger.
+                              "h-[40px]",
+                              "focus-visible:ring-border-presentation-state-focus outline-none focus-visible:ring-2",
+                              onRowClick && "cursor-pointer",
+                            )}
+                          >
+                            {onRowMove && <GripCell />}
+                            {selectable && (
+                              <TableCell isDummy className="min-h-[40px] w-12" onClick={(e) => e.stopPropagation()}>
+                                {/* What `TableCheckbox` renders, inlined: its props are typed as button
+                              attributes, so it cannot express a controlled checkbox. */}
+                                <div className="flex items-center justify-center">
+                                  <Checkbox
+                                    size="M"
+                                    checked={selected}
+                                    onCheckedChange={() => toggleRow(id)}
+                                    aria-label="Select row"
+                                  />
+                                </div>
+                              </TableCell>
+                            )}
+                            {visibleFields.map((field, i) => {
+                              // `undefined` means "you paint it" — distinct from `null`, which is a
+                              // deliberate blank.
+                              const custom = renderCell?.({ field, row, id, index, fields: visibleFields });
+                              // `fade={false}` and clip instead. The fade is a `mask-image` on every
+                              // cell, close to free on its own but very expensive once a sticky header
+                              // repaints the region each scroll frame: measured on this page,
+                              // mask+sticky costs ~61ms/frame against ~29ms with the mask off and
+                              // ~17ms with neither. `overflow-hidden` is passed back because
+                              // `fade={false}` otherwise switches the cell to `overflow-visible`, and
+                              // the text would spill into the next column.
+                              return (
+                                <TableCell
+                                  key={`${field.path}-${i}`}
+                                  className="min-h-[40px]"
+                                  fade={false}
+                                  childrenClassName="overflow-hidden"
+                                >
+                                  {/* `isolate` confines the Badge's mix-blend-luminosity to a local
+                                stacking context and `transform-gpu` promotes it to its own layer, so
+                                the table's post-mount column reflow repaints cleanly instead of
+                                leaving a ghosted badge frame. */}
+                                  <span className="isolate inline-flex transform-gpu">
+                                    {custom === undefined ? <Cell field={field} row={row} /> : custom}
+                                  </span>
+                                </TableCell>
+                              );
+                            })}
+                          </DraggableRow>
+                        );
+                      })}
+                    </DragList>
+                    {virtualize && padBottom > 0 && (
+                      <tr aria-hidden style={{ height: padBottom }} />
+                    )}
+                    {/* The trigger. A row of its own rather than an element after the table, so it sits
+                    inside the same scroller the rows do. */}
+                    {hasMore && !loading && (
+                      <tr ref={sentinelRef as React.Ref<HTMLTableRowElement>} aria-hidden>
+                        <td style={{ height: 1, padding: 0, border: 0 }} colSpan={100} />
+                      </tr>
+                    )}
+                    {loadingMore && (
+                      <SkeletonRows
+                        rows={2}
+                        fields={visibleFields}
+                        grip={Boolean(onRowMove)}
+                        selectable={selectable}
+                      />
+                    )}
+                  </TableBody>
+                </Table>
+              </div>
+            </div>
+            {/* Outside the scroller, deliberately: as a sibling its width is the component's visible
+                width, so it spans the full outer container and stays put while the columns scroll
+                sideways under it — instead of stretching to the table's scrollable width and sliding
+                away like a normal row. Same placement the form Table field uses. */}
             {onAddRow && (
               <TableEndAction onClick={onAddRow}>
                 <Plus className="h-4 w-4" aria-hidden />
@@ -419,7 +451,12 @@ function SkeletonRows({
           {grip && <TableCell isDummy className="h-[40px] w-8" />}
           {selectable && <TableCell isDummy className="h-[40px] w-12" />}
           {fields.map((field, i) => (
-            <TableCell key={`${field.path}-${i}`} className="h-[40px]">
+            <TableCell
+              key={`${field.path}-${i}`}
+              className="min-h-[40px]"
+              fade={false}
+              childrenClassName="overflow-hidden"
+            >
               {/* Widths cycle rather than repeat, so a column of bars reads as text that has not
                   arrived instead of as a grid. */}
               <SkeletonBar className={["w-[70%]", "w-[45%]", "w-[85%]", "w-[60%]"][(row + i) % 4]} />

package/apps/lib/components/Drawer.tsx

@@ -37,6 +37,7 @@ DrawerOverlay.displayName = DrawerPrimitive.Overlay.displayName;
 interface DrawerContentProps extends React.ComponentPropsWithoutRef<
   typeof DrawerPrimitive.Content
 > {
+  /** @deprecated No effect here — the drag handle is `DrawerPanel`'s `showHandle`. */
   showHandle?: boolean;
   notch?: React.ReactNode;
   notchSide?: "left" | "right";
@@ -87,7 +88,17 @@ const DrawerPanel = React.forwardRef<HTMLDivElement, DrawerPanelProps>(
       // would render white-on-light = invisible).
       data-theme="light"
       className={cn(
-        "flex flex-1 gap-2 rounded-t-[16px] p-1 bg-[#F0F0F0] min-h-0",
+        // `flex-col` is load-bearing: this panel stacks header / body / footer, and its own
+        // `showHandle` centres the drag handle with `mx-auto`, which only centres in a column.
+        // It was dropped in 37fddd5 alongside the tray's — on the tray that was deliberate (FormDrawer
+        // puts the panel and its summary side by side), here it was not, and every consumer that puts
+        // a header/body/footer straight into a panel rendered them in a row.
+        //
+        // `min-w-0` for the same reason, one axis over: the tray is a row now, so width is its
+        // main axis, and a flex item's default `min-width: auto` pins it to its content — a wide
+        // form pushed the panel straight out past the tray. `min-h-0` alone covered the old
+        // column tray; the row needs both.
+        "flex flex-1 flex-col gap-2 rounded-t-[16px] p-1 bg-[#F0F0F0] min-h-0 min-w-0",
         framed && "border border-[#D4D4D4] shadow-[inset_0_-4px_16px_rgba(0,0,0,0.1)]",
         className,
       )}
@@ -113,6 +124,12 @@ const DrawerContent = React.forwardRef<
       framed: framedProp,
       wrapperClassName,
       trayClassName,
+      // Destructured only to keep it out of `...props`. The handle belongs to `DrawerPanel` now, so
+      // this does nothing here — but it was never pulled out either, so it was being spread onto the
+      // DOM node and React warned "does not recognize the `showHandle` prop on a DOM element" every
+      // time a drawer opened. Kept in the props type rather than removed: consumers still pass it.
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      showHandle,
       ...props
     },
     ref,

package/apps/lib/components/DropdownMenu.tsx

@@ -70,16 +70,27 @@ const DropdownMenuContent = React.forwardRef<
         ref={ref}
         sideOffset={sideOffset}
         collisionPadding={collisionPadding}
-        // Cap at maxHeight, but never exceed the space Radix has after collision
-        // handling. The menu scrolls (overflow on the surface) past this height.
+        // Cap at maxHeight, but never exceed the space Radix has after collision handling. The
+        // `100vh` fallback is load-bearing: an undefined var invalidates the whole `min()`, so
+        // `max-height` would resolve to `none` and the panel — which no longer scrolls itself —
+        // would grow unbounded with its rows clipped and unreachable.
         style={{
-          maxHeight: `min(${maxHeight}px, var(--radix-dropdown-menu-content-available-height))`,
+          maxHeight: `min(${maxHeight}px, var(--radix-dropdown-menu-content-available-height, 100vh))`,
           ...style,
         }}
         className={cn(menuContentStyles({ variant }), className)}
         {...props}
       >
-        {autoGroup ? autoGroupChildren(children) : children}
+        {/* Dedicated scroll viewport, matching Select's: the cap lives on the panel above, this
+            fills what is left and scrolls. `min-h-0` is what makes it work — a flex item will not
+            shrink below its content, so without it the list grows past the panel and the panel's
+            `overflow-hidden` just clips the rows with no scrollbar.
+
+            `gap-1` is re-declared here because `autoGroupChildren` emits several siblings (a group,
+            a label, a separator…) and this is now the element they are siblings within. */}
+        <div className="flex flex-col gap-1 flex-1 min-h-0 overflow-y-auto overflow-x-hidden rounded-[10px] scrollbar-hide">
+          {autoGroup ? autoGroupChildren(children) : children}
+        </div>
       </DropdownMenuPrimitive.Content>
     </DropdownMenuPrimitive.Portal>
   ),
@@ -123,18 +134,45 @@ const DropdownMenuSubContent = React.forwardRef<
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent> & {
     variant?: "PresentationStyle";
     autoGroup?: boolean;
+    maxHeight?: number;
   }
->(({ className, variant = "PresentationStyle", autoGroup = true, children, ...props }, ref) => (
-  <DropdownMenuPrimitive.Portal>
-    <DropdownMenuPrimitive.SubContent
-      ref={ref}
-      className={cn(menuContentStyles({ variant }), className)}
-      {...props}
-    >
-      {autoGroup ? autoGroupChildren(children) : children}
-    </DropdownMenuPrimitive.SubContent>
-  </DropdownMenuPrimitive.Portal>
-));
+>(
+  (
+    {
+      className,
+      variant = "PresentationStyle",
+      autoGroup = true,
+      collisionPadding = 8,
+      maxHeight = 320,
+      // Destructured out of `{...props}` so the spread below cannot clobber the cap. Radix
+      // re-publishes the namespaced available-height var on SubContent, so the same expression
+      // Content uses works here unchanged.
+      style,
+      children,
+      ...props
+    },
+    ref,
+  ) => (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.SubContent
+        ref={ref}
+        collisionPadding={collisionPadding}
+        style={{
+          maxHeight: `min(${maxHeight}px, var(--radix-dropdown-menu-content-available-height, 100vh))`,
+          ...style,
+        }}
+        className={cn(menuContentStyles({ variant }), className)}
+        {...props}
+      >
+        {/* Same panel-clips / viewport-scrolls split as Content. A submenu is a peer surface, so it
+            shares the 320px default rather than getting a smaller one of its own. */}
+        <div className="flex flex-col gap-1 flex-1 min-h-0 overflow-y-auto overflow-x-hidden rounded-[10px] scrollbar-hide">
+          {autoGroup ? autoGroupChildren(children) : children}
+        </div>
+      </DropdownMenuPrimitive.SubContent>
+    </DropdownMenuPrimitive.Portal>
+  ),
+);
 DropdownMenuSubContent.displayName = DropdownMenuPrimitive.SubContent.displayName;
 
 const DropdownMenuItem = React.forwardRef<
@@ -456,16 +494,19 @@ export const menuContentStyles = cva(
     "rounded-[14px]",
     "min-w-[240px]",
     "outline-none",
-    "overflow-y-auto",
-    "overflow-x-hidden",
+    // The panel clips; the inner viewport below owns scrolling. Height is capped inline on the
+    // Content element from `min(maxHeight, available-height)` — no `max-h-*` class here on
+    // purpose, so the inline value governs.
+    "overflow-hidden",
     // Only animate the OPEN (enter) state. An exit animation on [data-state=closed]
     // holds the old DOM node during close, which breaks the context menu's
     // close/reposition on a second right-click (Radix issue #2572).
     "data-[state=open]:animate-in",
     "data-[state=open]:fade-in-0",
-    "scrollbar-hide",
     "backdrop-blur-[21px]",
-    "flex gap-1 flex-col",
+    // No `gap` here: the panel has exactly one child (the scroll viewport), so a gap between
+    // siblings has nothing to act on. The 4px between groups/labels lives on that viewport.
+    "flex flex-col",
   ],
   {
     variants: {
@@ -475,9 +516,11 @@ export const menuContentStyles = cva(
           "shadow-[0_0_32px_2px_rgba(0,0,0,0.20),0_0_48px_2px_rgba(0,0,0,0.05)]",
         ],
       },
-      defaultVariants: {
-        variant: "PresentationStyle",
-      },
+    },
+    // Was nested inside `variants`, where cva reads it as a variant group named
+    // "defaultVariants" and no default is ever applied. `menuGroupStyles` below has it right.
+    defaultVariants: {
+      variant: "PresentationStyle",
     },
   },
 );

package/apps/lib/components/FormBuilder/fields/FieldShell.tsx

@@ -16,6 +16,7 @@ import { FormField, FormItem, FormControl } from "../../Form";
 import { FieldHint } from "../../FieldHint";
 import { Tooltip } from "../../Tooltip";
 import { useDirection, useStepRegistry, useBare } from "../context";
+import type { FieldHintSpec } from "../types";
 
 export interface FieldShellProps {
   name: string;
@@ -26,6 +27,8 @@ export interface FieldShellProps {
   hidden?: boolean;
   /** Force the field's layout direction, overriding the form's `useDirection()` context. */
   direction?: "horizontal" | "vertical" | "flexible";
+  /** Alerts stacked under the validation error. See `FieldHintSpec`. */
+  hints?: FieldHintSpec[];
   /** The input, wired to the react-hook-form field. */
   children: (
     field: ControllerRenderProps<FieldValues, string>,
@@ -47,6 +50,7 @@ export function FieldShell({
   fullWidth,
   hidden,
   direction: directionProp,
+  hints,
   children,
 }: FieldShellProps) {
   const form = useFormContext();
@@ -108,7 +112,7 @@ export function FieldShell({
       secondaryLabel={description}
       direction={direction}
       className={fullWidth ? "max-w-full" : undefined}
-      childrenUnderLabel={<FieldError message={fieldError} />}
+      childrenUnderLabel={<FieldMessages message={fieldError} hints={hints} />}
     >
       <FormField
         control={form.control}
@@ -125,10 +129,20 @@ export function FieldShell({
   );
 }
 
-/** Validation error, shown as a `FieldHint` alert (no tooltip); null when there's none. */
-function FieldError({ message }: { message?: string }) {
-  if (!message) return null;
-  return <FieldHint state="error" label={message} />;
+/**
+ * The stack under a field: the validation error first (it is the actionable one), then any author
+ * `hints` in order. Renders nothing when there is neither, so a field without hints is unchanged.
+ */
+function FieldMessages({ message, hints }: { message?: string; hints?: FieldHintSpec[] }) {
+  if (!message && !hints?.length) return null;
+  return (
+    <div className="flex flex-col items-start gap-[4px]">
+      {message && <FieldHint state="error" label={message} />}
+      {hints?.map((hint, i) => (
+        <FieldHint key={i} state={hint.state ?? "info"} label={hint.label} icon={hint.icon} />
+      ))}
+    </div>
+  );
 }
 
 /**

package/apps/lib/components/FormBuilder/types.ts

@@ -41,6 +41,16 @@ export type FieldKind =
   | "custom";
 
 /** Props shared by every `FormBuilder.*` field. `name` is the RHF path. */
+/**
+ * One alert under a field. Mirrors `FieldHint`'s own props so the design system stays the single
+ * source of truth for how each state looks.
+ */
+export interface FieldHintSpec {
+  label: ReactNode;
+  state?: "info" | "warning" | "error" | "success";
+  icon?: ReactNode;
+}
+
 export interface BaseFieldProps {
   name: string;
   label?: ReactNode;
@@ -51,6 +61,12 @@ export interface BaseFieldProps {
   hidden?: boolean;
   /** Span the full section width. */
   fullWidth?: boolean;
+  /**
+   * Alerts stacked under the field. The validation error, when there is one, always renders first —
+   * it is the actionable message — and these follow in order. Ignored in `bare` mode (a
+   * `FormBuilder.Table` cell), where errors surface as a tooltip to keep the row one line tall.
+   */
+  hints?: FieldHintSpec[];
 }
 
 export interface OptionItem {