@flamingo-stack/openframe-frontend-core 0.0.399 → 0.0.400-snapshot.20260710144905

package/src/components/features/auth/openframe-sso-signup-form.tsx

@@ -2,6 +2,7 @@
 
 import type * as React from 'react'
 import { cn } from '../../../utils/cn'
+import { useDeferredError } from '../../../hooks/ui/use-deferred-error'
 import { Button } from '../../ui/button'
 import { Input } from '../../ui/input'
 import { PasswordInput } from '../../ui/password-input'
@@ -72,6 +73,13 @@ export function OpenFrameSsoSignUpForm({
 }: OpenFrameSsoSignUpFormProps) {
   const fieldsDisabled = disabled || loading
 
+  // Validation messages are deferred while the user is typing (shown on blur or after a pause).
+  const emailErr = useDeferredError(errors?.email, email)
+  const firstNameErr = useDeferredError(errors?.firstName, firstName)
+  const lastNameErr = useDeferredError(errors?.lastName, lastName)
+  const passwordErr = useDeferredError(errors?.password, password)
+  const confirmErr = useDeferredError(errors?.confirmPassword, confirmPassword)
+
   const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
     if (event.key === 'Enter' && !fieldsDisabled && !submitDisabled) {
       onSubmit()
@@ -96,8 +104,9 @@ export function OpenFrameSsoSignUpForm({
         label={emailLabel}
         placeholder="username@mail.com"
         value={email}
-        error={errors?.email}
+        error={emailErr.error}
         disabled={fieldsDisabled || emailReadOnly}
+        onBlur={emailErr.onBlur}
         onChange={(event) => onEmailChange(event.target.value)}
         onKeyDown={handleKeyDown}
       />
@@ -107,8 +116,9 @@ export function OpenFrameSsoSignUpForm({
         label="First Name"
         placeholder="Enter First Name"
         value={firstName}
-        error={errors?.firstName}
+        error={firstNameErr.error}
         disabled={fieldsDisabled}
+        onBlur={firstNameErr.onBlur}
         onChange={(event) => onFirstNameChange(event.target.value)}
         onKeyDown={handleKeyDown}
       />
@@ -116,8 +126,9 @@ export function OpenFrameSsoSignUpForm({
         label="Last Name"
         placeholder="Enter Last Name"
         value={lastName}
-        error={errors?.lastName}
+        error={lastNameErr.error}
         disabled={fieldsDisabled}
+        onBlur={lastNameErr.onBlur}
         onChange={(event) => onLastNameChange(event.target.value)}
         onKeyDown={handleKeyDown}
       />
@@ -125,8 +136,9 @@ export function OpenFrameSsoSignUpForm({
         label="Password"
         placeholder="Enter Password"
         value={password}
-        error={errors?.password}
+        error={passwordErr.error}
         disabled={fieldsDisabled}
+        onBlur={passwordErr.onBlur}
         onChange={(event) => onPasswordChange(event.target.value)}
         onKeyDown={handleKeyDown}
       />
@@ -134,8 +146,9 @@ export function OpenFrameSsoSignUpForm({
         label="Confirm Password"
         placeholder="Confirm Password"
         value={confirmPassword}
-        error={errors?.confirmPassword}
+        error={confirmErr.error}
         disabled={fieldsDisabled}
+        onBlur={confirmErr.onBlur}
         onChange={(event) => onConfirmPasswordChange(event.target.value)}
         onKeyDown={handleKeyDown}
       />

package/src/components/features/auth/password-reset-form.tsx

@@ -2,6 +2,7 @@
 
 import type * as React from 'react'
 import { cn } from '../../../utils/cn'
+import { useDeferredError } from '../../../hooks/ui/use-deferred-error'
 import { Button } from '../../ui/button'
 import { Input } from '../../ui/input'
 import { BackToLoginLink } from './back-to-login-link'
@@ -66,6 +67,10 @@ export function PasswordResetForm({
 }: PasswordResetFormProps) {
   const fieldsDisabled = disabled || loading
 
+  // Validation messages are deferred while the user is typing (shown on blur or after a pause).
+  const passwordErr = useDeferredError(errors?.password, password)
+  const confirmErr = useDeferredError(errors?.confirmPassword, confirmPassword)
+
   const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
     if (event.key === 'Enter' && !fieldsDisabled && !submitDisabled) {
       onSubmit()
@@ -91,8 +96,9 @@ export function PasswordResetForm({
         label={newPasswordLabel}
         placeholder={newPasswordPlaceholder}
         value={password}
-        error={errors?.password}
+        error={passwordErr.error}
         disabled={fieldsDisabled}
+        onBlur={passwordErr.onBlur}
         onChange={(event) => onPasswordChange(event.target.value)}
         onKeyDown={handleKeyDown}
       />
@@ -103,8 +109,9 @@ export function PasswordResetForm({
         label={confirmPasswordLabel}
         placeholder={confirmPasswordPlaceholder}
         value={confirmPassword}
-        error={errors?.confirmPassword}
+        error={confirmErr.error}
         disabled={fieldsDisabled}
+        onBlur={confirmErr.onBlur}
         onChange={(event) => onConfirmPasswordChange(event.target.value)}
         onKeyDown={handleKeyDown}
       />

package/src/components/ui/data-table/data-table-header.tsx

@@ -69,7 +69,8 @@ export function DataTableHeader({
   const hasVisibleHeaderCell = headerGroup.headers.some(header => {
     if (header.isPlaceholder) return false
     if (isLgUp) return true
-    return Boolean(header.column.columnDef.meta?.filter)
+    const meta = header.column.columnDef.meta
+    return Boolean(meta?.filter) || meta?.alwaysShowHeader === true
   })
 
   return (
@@ -122,6 +123,8 @@ function HeaderCell({ header, isLgUp, sort, onSortChange }: HeaderCellProps) {
   const column = header.column
   const meta = column.columnDef.meta
   const hasFilter = Boolean(meta?.filter)
+  // Tablet visibility: filterable columns and explicit opt-ins stay rendered.
+  const keepOnTablet = hasFilter || meta?.alwaysShowHeader === true
   const align = meta?.align ?? 'left'
   // Sort is opt-in via `meta.sortable`. Direction is fully consumer-driven via
   // the `sort` prop; we do not consult TanStack's sort APIs here.
@@ -130,7 +133,7 @@ function HeaderCell({ header, isLgUp, sort, onSortChange }: HeaderCellProps) {
     sort?.id === column.id ? (sort.desc ? 'desc' : 'asc') : false
 
   // Mobile (md, below lg): hide non-filter columns so only filters are accessible.
-  if (!isLgUp && !hasFilter) return null
+  if (!isLgUp && !keepOnTablet) return null
 
   return (
     <div
@@ -139,7 +142,7 @@ function HeaderCell({ header, isLgUp, sort, onSortChange }: HeaderCellProps) {
         isLgUp && (meta?.width || 'flex-1 min-w-0'),
         meta?.headerClassName,
         // Don't apply hide classes if column is filterable on tablet (keep filter accessible)
-        !(hasFilter && !isLgUp) && getHideClasses(meta?.hideAt),
+        !(keepOnTablet && !isLgUp) && getHideClasses(meta?.hideAt),
       )}
     >
       {hasFilter ? (

package/src/components/ui/data-table/types.ts

@@ -16,6 +16,12 @@ declare module '@tanstack/react-table' {
     align?: 'left' | 'center' | 'right'
     /** Hide column at/below these Tailwind breakpoints. */
     hideAt?: TailwindBreakpoint | TailwindBreakpoint[]
+    /**
+     * Keep this header visible on tablet (md, below lg) even without
+     * `meta.filter` — for custom headers hosting their own filter UI
+     * (e.g. the date filter calendar trigger).
+     */
+    alwaysShowHeader?: boolean
     /** If present, header renders a filter dropdown with these options. */
     filter?: {
       options: DataTableFilterOption[]

package/src/components/ui/date-picker.tsx

@@ -150,6 +150,14 @@ function DatePickerCalendar({
   );
   const [hoveredDate, setHoveredDate] = React.useState<Date | undefined>(undefined);
 
+  // Keep the internal range in sync when the consumer changes `selected`
+  // externally (e.g. DateFilterMenu Reset while the popover stays open).
+  React.useEffect(() => {
+    if (mode === "range") {
+      setDraftRange(selected as DateRange | undefined);
+    }
+  }, [mode, selected]);
+
   const rangeSelected = draftRange;
   const hasCompleteRange =
     mode === "range" &&
@@ -168,7 +176,11 @@ function DatePickerCalendar({
     if (!triggerDate) return;
 
     if (!draftRange?.from || draftRange.to) {
-      setDraftRange({ from: triggerDate, to: undefined });
+      // First click starts the range — propagate it so consumers can already
+      // act on a single-day selection (e.g. DateFilterMenu Apply/Reset).
+      const started: DateRange = { from: triggerDate, to: undefined };
+      setDraftRange(started);
+      onSelect(started);
       return;
     }
     // Second click closes the range, ordering the two ends.
@@ -981,6 +993,89 @@ export function DatePickerInputSimple({
   );
 }
 
+// ============================================================================
+// DateFilterPanel Component (sort select + fluid calendar)
+// ============================================================================
+
+export interface DateFilterPanelProps {
+  /** Selection mode for the calendar. Defaults to "range". */
+  mode?: DatePickerMode;
+  /** Current sort direction shown in the select. */
+  sort: SortDirection;
+  onSortChange: (sort: SortDirection) => void;
+  /** Current calendar selection. */
+  selected: Date | DateRange | undefined;
+  onSelect: (value: Date | DateRange | undefined) => void;
+  /** Minimum selectable date. */
+  fromDate?: Date;
+  /** Maximum selectable date. */
+  toDate?: Date;
+  /** Locale for the calendar. */
+  locale?: DayPickerProps["locale"];
+  /** Label for the ascending sort option. */
+  ascLabel?: string;
+  /** Label for the descending sort option. */
+  descLabel?: string;
+  className?: string;
+}
+
+/**
+ * DateFilterPanel — the controlled sort-direction select + fluid calendar
+ * block shared by DateFilterMenu (popover) and FilterModal (mobile "Sort and
+ * Filter"). Owns no state: the consumer drafts and commits the values.
+ */
+export function DateFilterPanel({
+  mode = "range",
+  sort,
+  onSortChange,
+  selected,
+  onSelect,
+  fromDate,
+  toDate,
+  locale,
+  ascLabel = "Sort by Ascending",
+  descLabel = "Sort by Descending",
+  className,
+}: DateFilterPanelProps) {
+  return (
+    <div className={cn("flex flex-col gap-4", className)}>
+      {/* Sort direction selector */}
+      <Select
+        value={sort}
+        onValueChange={(value) => onSortChange(value as SortDirection)}
+      >
+        <SelectTrigger className="gap-2" aria-label="Sort direction">
+          {/* Wrapper is a <div> (not <span>) so SelectTrigger's
+              `[&>span]:line-clamp-1` rule doesn't force it to a vertical
+              -webkit-box and stack the icon/label into a column. */}
+          <div className="flex min-w-0 flex-1 items-center gap-2">
+            <ArrowUpDown className="size-6 shrink-0 text-ods-text-secondary" />
+            <span className="truncate">
+              <SelectValue />
+            </span>
+          </div>
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="asc">{ascLabel}</SelectItem>
+          <SelectItem value="desc">{descLabel}</SelectItem>
+        </SelectContent>
+      </Select>
+
+      {/* Calendar */}
+      <DatePickerCalendar
+        mode={mode}
+        selected={selected}
+        onSelect={onSelect}
+        numberOfMonths={1}
+        fromDate={fromDate}
+        toDate={toDate}
+        locale={locale}
+        fluid
+      />
+    </div>
+  );
+}
+
 // ============================================================================
 // DateFilterMenu Component (sort + calendar filter popover from Figma)
 // ============================================================================
@@ -999,14 +1094,21 @@ export interface DateFilterMenuProps {
   mode?: DatePickerMode;
   /** Current (applied) sort direction. Defaults to "desc". */
   sort?: SortDirection;
+  /** Baseline sort direction — Reset restores it, and a draft that differs
+   *  from it counts as an active change (shows Reset). Defaults to "desc". */
+  defaultSort?: SortDirection;
   /** Current (applied) single date — used when mode === "single". */
   date?: Date;
   /** Current (applied) range — used when mode === "range". */
   range?: DateRange;
-  /** Fired when the user presses Apply with the drafted selection. */
+  /** Fired when the user presses Apply with the drafted selection. Also fired
+   *  by Reset with a cleared selection so the consumer refetches unfiltered data. */
   onApply?: (result: DateFilterResult) => void;
   /** Fired when the menu closes (Close button, outside click, Esc). */
   onClose?: () => void;
+  /** Custom trigger element (rendered via Radix `asChild` — must accept a ref,
+   *  e.g. a native button). Defaults to the outline calendar icon Button. */
+  trigger?: React.ReactNode;
   /** Disable the trigger. */
   disabled?: boolean;
   /** Minimum selectable date. */
@@ -1029,16 +1131,21 @@ export interface DateFilterMenuProps {
 
 /**
  * DateFilterMenu — a calendar-icon-triggered popover combining a sort-direction
- * selector and a date / date-range calendar, with Close and Apply actions.
- * Selections are drafted internally and only committed via `onApply`.
+ * selector and a date / date-range calendar, with Close/Reset and Apply actions.
+ * The sort and date selection are drafted internally and committed via
+ * `onApply`. While a date is selected, Close is replaced by Reset, which
+ * clears and commits the empty selection (fires `onApply`) so the consumer
+ * drops the filter.
  */
 export function DateFilterMenu({
   mode = "range",
   sort = "desc",
+  defaultSort = "desc",
   date,
   range,
   onApply,
   onClose,
+  trigger,
   disabled = false,
   fromDate,
   toDate,
@@ -1085,18 +1192,39 @@ export function DateFilterMenu({
     setOpen(false);
   };
 
+  // Anything to reset? A calendar selection or a non-default sort — drives Close vs Reset.
+  const hasSelection =
+    mode === "single"
+      ? Boolean(draftSelected)
+      : Boolean((draftSelected as DateRange | undefined)?.from);
+  const hasChanges = hasSelection || draftSort !== defaultSort;
+
+  // Reset restores the defaults and commits them so the consumer drops the
+  // filter and refetches; the menu stays open with the button back to Close.
+  const handleReset = () => {
+    setDraftSort(defaultSort);
+    setDraftSelected(undefined);
+    onApply?.(
+      mode === "single"
+        ? { sort: defaultSort, date: undefined }
+        : { sort: defaultSort, range: undefined }
+    );
+  };
+
   return (
     <Popover.Root open={open} onOpenChange={handleOpenChange}>
       <Popover.Trigger asChild>
-        <Button
-          type="button"
-          variant="outline"
-          size="icon"
-          disabled={disabled}
-          aria-label={ariaLabel}
-          className={className}
-          leftIcon={<Calendar className="size-6" />}
-        />
+        {trigger ?? (
+          <Button
+            type="button"
+            variant="outline"
+            size="icon"
+            disabled={disabled}
+            aria-label={ariaLabel}
+            className={className}
+            leftIcon={<Calendar className="size-6" />}
+          />
+        )}
       </Popover.Trigger>
 
       <Popover.Portal>
@@ -1112,38 +1240,18 @@ export function DateFilterMenu({
           sideOffset={8}
           align={align}
         >
-          {/* Sort direction selector */}
-          <Select
-            value={draftSort}
-            onValueChange={(value) => setDraftSort(value as SortDirection)}
-          >
-            <SelectTrigger className="gap-2" aria-label="Sort direction">
-              {/* Wrapper is a <div> (not <span>) so SelectTrigger's
-                  `[&>span]:line-clamp-1` rule doesn't force it to a vertical
-                  -webkit-box and stack the icon/label into a column. */}
-              <div className="flex min-w-0 flex-1 items-center gap-2">
-                <ArrowUpDown className="size-6 shrink-0 text-ods-text-secondary" />
-                <span className="truncate">
-                  <SelectValue />
-                </span>
-              </div>
-            </SelectTrigger>
-            <SelectContent>
-              <SelectItem value="asc">{ascLabel}</SelectItem>
-              <SelectItem value="desc">{descLabel}</SelectItem>
-            </SelectContent>
-          </Select>
-
-          {/* Calendar */}
-          <DatePickerCalendar
+          {/* Sort + calendar (shared panel) */}
+          <DateFilterPanel
             mode={mode}
+            sort={draftSort}
+            onSortChange={setDraftSort}
             selected={draftSelected}
             onSelect={setDraftSelected}
-            numberOfMonths={1}
             fromDate={fromDate}
             toDate={toDate}
             locale={locale}
-            fluid
+            ascLabel={ascLabel}
+            descLabel={descLabel}
           />
 
           {/* Actions */}
@@ -1152,9 +1260,9 @@ export function DateFilterMenu({
               type="button"
               variant="outline"
               fullWidth
-              onClick={handleClose}
+              onClick={hasChanges ? handleReset : handleClose}
             >
-              Close
+              {hasChanges ? "Reset" : "Close"}
             </Button>
             <Button
               type="button"

package/src/components/ui/filter-modal.tsx

@@ -6,7 +6,9 @@ import { cn } from '../../utils/cn'
 import { Filter02Icon } from '../icons-v2-generated/sort-and-filter/filter-02-icon'
 import { Button } from './button'
 import { FilterCheckboxItem } from './filter-checkbox-item'
+import { DateFilterPanel, type DateFilterResult, type DateRange } from './date-picker'
 import { ModalV2, ModalV2Content, ModalV2Footer, ModalV2Header, ModalV2Title } from './modal-v2'
+import { ScrollFadeOverlay, useScrollFade } from './scroll-fade'
 import { Skeleton } from './skeleton'
 import { SortColumnItem, type SortConfig, type SortDirection } from './sort-column-item'
 import { TagKeyValueFilter, type TagKeyConfig } from './tag-key-value-filter'
@@ -51,6 +53,20 @@ export interface FilterModalProps {
   tagFilterTitle?: string
   /** Show skeleton loading state */
   isLoading?: boolean
+  /** Date sort + range filter rendered as the last section. Drafted with the
+   *  other filters and committed via `onChange` on Apply (defaults on Reset). */
+  dateFilter?: {
+    /** Section title. Defaults to 'Date'. */
+    title?: string
+    /** Applied sort direction. Defaults to `defaultSort`. */
+    sort?: SortDirection
+    /** Baseline sort direction restored by Reset. Defaults to 'desc'. */
+    defaultSort?: SortDirection
+    /** Applied date range. */
+    range?: DateRange
+    /** Fired on Apply with the drafted values, and on Reset with the defaults. */
+    onChange: (result: DateFilterResult) => void
+  }
   /** Text shown in empty state title */
   emptyStateTitle?: string
   /** Text shown in empty state description */
@@ -74,6 +90,7 @@ export function FilterModal({
   selectedTags,
   onTagsChange,
   tagFilterTitle,
+  dateFilter,
   isLoading = false,
   emptyStateTitle = 'No filters available',
   emptyStateDescription = 'There are no filter options to display at the moment',
@@ -83,10 +100,20 @@ export function FilterModal({
   })
   const [pendingTags, setPendingTags] = useState<string[]>(selectedTags ?? [])
 
+  const dateDefaultSort: SortDirection = dateFilter?.defaultSort ?? 'desc'
+  const [draftDateSort, setDraftDateSort] = useState<SortDirection>(dateFilter?.sort ?? dateDefaultSort)
+  const [draftDateRange, setDraftDateRange] = useState<DateRange | undefined>(dateFilter?.range)
+
+  // Scroll shadows: bottom fade by default while content continues below,
+  // top fade once scrolled (same pattern as the chat lists).
+  const { scrollRef, fadeTop, fadeBottom, update: updateFade } = useScrollFade<HTMLDivElement>()
+
   useEffect(() => {
     if (isOpen) {
       setSelectedFilters({ ...currentFilters })
       setPendingTags(selectedTags ?? [])
+      setDraftDateSort(dateFilter?.sort ?? dateDefaultSort)
+      setDraftDateRange(dateFilter?.range)
     }
   }, [isOpen, JSON.stringify(currentFilters), JSON.stringify(selectedTags)])
 
@@ -109,12 +136,14 @@ export function FilterModal({
   const handleReset = () => {
     onFilterChange({})
     onTagsChange?.([])
+    dateFilter?.onChange({ sort: dateDefaultSort, range: undefined })
     onClose()
   }
 
   const handleApply = () => {
     onFilterChange(selectedFilters)
     onTagsChange?.(pendingTags)
+    dateFilter?.onChange({ sort: draftDateSort, range: draftDateRange })
     onClose()
   }
 
@@ -125,7 +154,7 @@ export function FilterModal({
   const hasSort = !!sortConfig && sortConfig.columns.length > 0
   const hasFilterGroups = filterGroups.length > 0
   const hasTagFilter = !!tagFilterKeys && tagFilterKeys.length > 0 && !!onTagsChange
-  const isEmpty = !isLoading && !hasSort && !hasFilterGroups && !hasTagFilter
+  const isEmpty = !isLoading && !hasSort && !hasFilterGroups && !hasTagFilter && !dateFilter
 
   return (
     <ModalV2
@@ -143,7 +172,12 @@ export function FilterModal({
           !isEmpty && 'md:bg-ods-bg md:border md:border-ods-border md:rounded-md md:px-3',
         )}
       >
-        <div className="flex-1 min-h-0 overflow-y-auto flex flex-col gap-4 md:py-3">
+        <div className="relative flex-1 min-h-0 flex flex-col">
+        <div
+          ref={scrollRef}
+          onScroll={updateFade}
+          className="flex-1 min-h-0 overflow-y-auto flex flex-col gap-4 md:py-3"
+        >
         {isLoading ? (
           <>
             {[0, 1].map((group) => (
@@ -229,10 +263,31 @@ export function FilterModal({
             onTagsChange={setPendingTags}
             keysTitle={tagFilterTitle}
           />
+        )}
+        {/* Date sort + range filter */}
+        {dateFilter && (
+          <div className="flex flex-col gap-1">
+            <span className="text-h5 text-ods-text-secondary">
+              {dateFilter.title ?? 'Date'}
+            </span>
+            <DateFilterPanel
+              mode="range"
+              sort={draftDateSort}
+              onSortChange={setDraftDateSort}
+              selected={draftDateRange}
+              onSelect={(value) => setDraftDateRange(value as DateRange | undefined)}
+              className="gap-[var(--spacing-system-xxs)]"
+            />
+          </div>
         )}
           </>
         )}
         </div>
+
+        {/* Scroll shadows over the filter list edges */}
+        <ScrollFadeOverlay edge="top" visible={fadeTop} />
+        <ScrollFadeOverlay edge="bottom" visible={fadeBottom} />
+        </div>
       </ModalV2Content>
 
       <ModalV2Footer>

package/src/components/ui/index.ts

@@ -24,6 +24,7 @@ export * from './no-data'
 export * from './page-loader'
 export * from './progress-bar'
 export * from './radio-group'
+export * from './scroll-fade'
 export * from './select'
 export * from './switch'
 export * from './tag-select-dropdown'

package/src/components/ui/scroll-fade.tsx

@@ -0,0 +1,90 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../utils/cn'
+
+/**
+ * Tracks whether a scrollable element is scrolled away from its top/bottom
+ * edge, so edge fades ("scroll shadows") can be shown only where content
+ * continues. Attach `scrollRef` to the scrollable element and `update` to its
+ * `onScroll`; content/size changes are re-measured via ResizeObserver.
+ *
+ * Canonical fade pattern shared by chat lists and FilterModal.
+ */
+export function useScrollFade<T extends HTMLElement = HTMLDivElement>() {
+  const scrollRef = React.useRef<T | null>(null)
+  const [fade, setFade] = React.useState({ top: false, bottom: false })
+
+  const update = React.useCallback(() => {
+    const el = scrollRef.current
+    if (!el) return
+    setFade((prev) => {
+      const top = el.scrollTop > 0
+      const bottom = el.scrollHeight - el.scrollTop - el.clientHeight > 1
+      return prev.top === top && prev.bottom === bottom ? prev : { top, bottom }
+    })
+  }, [])
+
+  React.useLayoutEffect(() => {
+    update()
+    const el = scrollRef.current
+    if (!el) return
+    const cleanups: Array<() => void> = []
+    if (typeof ResizeObserver !== 'undefined') {
+      const resizeObserver = new ResizeObserver(update)
+      resizeObserver.observe(el)
+      cleanups.push(() => resizeObserver.disconnect())
+    }
+    // ResizeObserver only sees the container box; content growth (appended
+    // list items) changes scrollHeight without resizing it — watch mutations.
+    if (typeof MutationObserver !== 'undefined') {
+      const mutationObserver = new MutationObserver(update)
+      mutationObserver.observe(el, { childList: true, subtree: true, characterData: true })
+      cleanups.push(() => mutationObserver.disconnect())
+    }
+    return () => {
+      for (const cleanup of cleanups) cleanup()
+    }
+  }, [update])
+
+  return { scrollRef, fadeTop: fade.top, fadeBottom: fade.bottom, update }
+}
+
+export interface ScrollFadeOverlayProps {
+  /** Which edge of the scroll container the fade sits on. */
+  edge: 'top' | 'bottom'
+  /** Whether the fade is currently shown (content continues past this edge). */
+  visible: boolean
+  /**
+   * CSS color the content fades into — should match the surface behind the
+   * list. Defaults to the page background token.
+   */
+  color?: string
+  className?: string
+}
+
+/**
+ * Edge overlay that fades scrollable content into the surface behind it.
+ * Render inside a `relative` wrapper around the scrollable element.
+ */
+export function ScrollFadeOverlay({
+  edge,
+  visible,
+  color = 'var(--color-bg)',
+  className,
+}: ScrollFadeOverlayProps) {
+  return (
+    <div
+      aria-hidden
+      className={cn(
+        'pointer-events-none absolute inset-x-0 h-16 transition-opacity duration-150',
+        edge === 'top' ? 'top-0' : 'bottom-0',
+        visible ? 'opacity-100' : 'opacity-0',
+        className,
+      )}
+      style={{
+        background: `linear-gradient(${edge === 'top' ? '0deg' : '180deg'}, transparent 0%, ${color} 100%)`,
+      }}
+    />
+  )
+}

package/src/hooks/ui/index.ts

@@ -1,6 +1,7 @@
 // UI Hooks exports
 export * from './use-auto-limit-tags'
 export * from './use-debounce'
+export * from './use-deferred-error'
 export * from './use-header-height'
 export * from './use-horizontal-scrollbar'
 export * from './use-image-edge-color'