torch-glare 2.3.0 → 2.4.0

package/apps/lib/components/SearchableTable.tsx

@@ -1,13 +1,24 @@
 "use client";
 
-import { ReactNode, useEffect, useMemo, useRef, useState } from "react";
-import { cva } from "class-variance-authority";
+import {
+  forwardRef,
+  InputHTMLAttributes,
+  ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { cn } from "../utils/cn";
 import { Themes } from "../utils/types";
-import { Popover, PopoverContent, PopoverTrigger } from "./Popover";
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogTitle,
+} from "./Dialog";
 import { Icon, Input, Group } from "./Input";
-import { Button, LoadingIcon } from "./Button";
-import { useClickOutside } from "../hooks/useClickOutside";
+import { LoadingIcon } from "./Button";
 import {
   Table,
   TableHeader,
@@ -18,12 +29,12 @@ import {
 } from "./Table";
 
 /**
- * SearchableTable — a searchable combobox whose dropdown renders a real Table.
+ * SearchableTable — a field that opens a modal Dialog to pick a row from a Table.
  *
- * Type in the input to filter rows; the dropdown opens on focus and shows the
- * filtered data using the existing Table component (composed inside a Popover,
- * the same mechanism BadgeField uses). Click a row to select it (single-select):
- * the dropdown closes and the input shows the selected row's label.
+ * The trigger shows a placeholder until something is selected, then shows the
+ * selected row's label. Clicking it opens a dialog containing a search input and
+ * the data Table; clicking a row selects it, sets the value, and closes the
+ * dialog. Supports client- or server-side search and infinite-scroll pagination.
  */
 
 export interface SearchableTableColumn<T> {
@@ -40,13 +51,18 @@ interface Props<T> {
   /** Controlled selected row (optional). */
   value?: T | null;
   onSelect?: (row: T) => void;
-  /** Text shown in the input after selection; defaults to the first column's value. */
+  /** Text shown on the trigger after selection; defaults to the first column's value. */
   getLabel?: (row: T) => string;
   /** Stable id/key per row; defaults to JSON of the row. */
   getRowId?: (row: T) => string;
   /** Which fields the search matches; defaults to every column key. */
   searchKeys?: (keyof T & string)[];
+  /** Trigger placeholder shown until a row is selected. */
   placeholder?: string;
+  /** Placeholder for the search input inside the dialog. */
+  searchPlaceholder?: string;
+  /** Label shown on the dialog's search field. */
+  title?: string;
   size?: "XS" | "S" | "M";
   variant?: "SystemStyle" | "PresentationStyle";
   icon?: ReactNode;
@@ -71,44 +87,8 @@ interface Props<T> {
   loading?: boolean;
   /** Called when the list nears the bottom and `hasMore && !loading`. */
   onLoadMore?: () => void;
-  /** Max rows visible before the list scrolls (default 6). */
-  maxVisibleRows?: number;
 }
 
-// One M-size table row ≈ 40px + the 44px sticky header.
-const ROW_HEIGHT = 40;
-const HEADER_HEIGHT = 44;
-
-// Popover surface styled like the DropdownMenu (kept local — self-contained).
-const tableDropdownStyles = cva(
-  [
-    "p-1",
-    "rounded-[14px]",
-    "border-0", // neutralize PopoverContent's base border (the card provides its own)
-    "outline-none",
-    "overflow-y-auto",
-    "scrollbar-hide",
-    "backdrop-blur-[21px]",
-    "data-[state=open]:animate-in",
-    "data-[state=open]:fade-in-0",
-  ],
-  {
-    variants: {
-      variant: {
-        PresentationStyle: [
-          "bg-[rgba(61,64,69,0.72)]",
-          "shadow-[0_0_32px_2px_rgba(0,0,0,0.20),0_0_48px_2px_rgba(0,0,0,0.05)]",
-        ],
-        SystemStyle: [
-          "bg-background-system-body-primary",
-          "shadow-[0px_0px_18px_0px_rgba(0,0,0,0.75)]",
-        ],
-      },
-    },
-    defaultVariants: { variant: "PresentationStyle" },
-  }
-);
-
 export function SearchableTable<T extends Record<string, unknown>>({
   columns,
   rows,
@@ -117,7 +97,9 @@ export function SearchableTable<T extends Record<string, unknown>>({
   getLabel,
   getRowId,
   searchKeys,
-  placeholder = "Search…",
+  placeholder = "Select…",
+  searchPlaceholder = "Search…",
+  title = "Select an item",
   size = "M",
   variant = "PresentationStyle",
   icon,
@@ -130,14 +112,18 @@ export function SearchableTable<T extends Record<string, unknown>>({
   hasMore = false,
   loading = false,
   onLoadMore,
-  maxVisibleRows = 6,
 }: Props<T>) {
   const [open, setOpen] = useState(false);
   const [search, setSearch] = useState("");
-  const [dropdownWidth, setDropdownWidth] = useState(0);
-  const popoverContentRef = useRef<HTMLDivElement>(null);
+  const scrollRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement | null>(null);
 
+  const rowId = (row: T) => getRowId?.(row) ?? JSON.stringify(row);
+  const label = (row: T) =>
+    getLabel?.(row) ?? String(row[columns[0]?.key] ?? "");
+
+  const keysToSearch = searchKeys ?? columns.map((c) => c.key);
+
   // Debounced server search: notify the consumer to refetch when the query
   // settles. Skipped entirely if no onSearchChange is provided (static mode).
   useEffect(() => {
@@ -146,8 +132,13 @@ export function SearchableTable<T extends Record<string, unknown>>({
     return () => clearTimeout(id);
   }, [search, onSearchChange, searchDebounceMs]);
 
-  // Infinite scroll: when the vertical scroll viewport nears the bottom, ask the
-  // consumer to load the next page (onScroll is reliable across Radix's portal).
+  // Reset the query whenever the dialog closes so it reopens clean.
+  useEffect(() => {
+    if (!open) setSearch("");
+  }, [open]);
+
+  // Infinite scroll: when the scroll viewport nears the bottom, ask the consumer
+  // to load the next page.
   const handleScroll = (e: React.UIEvent<HTMLDivElement>) => {
     if (!onLoadMore || !hasMore || loading) return;
     const el = e.currentTarget;
@@ -156,22 +147,6 @@ export function SearchableTable<T extends Record<string, unknown>>({
     }
   };
 
-  const groupRef = useClickOutside<HTMLDivElement>((e) => {
-    const target = e?.target as Node;
-    if (
-      !groupRef.current?.contains(target) &&
-      !popoverContentRef.current?.contains(target)
-    ) {
-      setOpen(false);
-    }
-  });
-
-  const rowId = (row: T) => getRowId?.(row) ?? JSON.stringify(row);
-  const label = (row: T) =>
-    getLabel?.(row) ?? String(row[columns[0]?.key] ?? "");
-
-  const keysToSearch = searchKeys ?? columns.map((c) => c.key);
-
   const filteredRows = useMemo(() => {
     // Server-side search mode: render rows as-is (already filtered upstream).
     if (!filterClientSide) return rows;
@@ -185,124 +160,87 @@ export function SearchableTable<T extends Record<string, unknown>>({
   }, [rows, search, keysToSearch, filterClientSide]);
 
   const selectedId = value ? rowId(value) : undefined;
-  // True while the user is actively typing a query. When false, the input shows
-  // the selected row's label as its real value (solid text, not placeholder).
-  const [searching, setSearching] = useState(false);
 
   const handleSelect = (row: T) => {
     onSelect?.(row);
-    setSearch("");
-    setSearching(false);
     setOpen(false);
   };
 
-  // Solid value: search text while typing, otherwise the selected label.
-  const displayValue = searching ? search : value ? label(value) : "";
-
   return (
-    <Popover open={open}>
-      <PopoverTrigger asChild>
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>
+        {/* Trigger: shows placeholder until a row is selected, then its label. */}
         <Group
           dir={dir}
           data-theme={theme}
           variant={variant}
           size={size === "XS" ? "S" : size}
-          ref={groupRef as never}
-          onFocus={(e: React.FocusEvent<HTMLDivElement>) =>
-            setDropdownWidth(e.currentTarget.offsetWidth)
-          }
-          className={cn("flex w-full items-center gap-1 p-1", className)}
+          role="button"
+          tabIndex={0}
+          className={cn(
+            "flex w-full items-center gap-1 p-1 cursor-pointer",
+            className
+          )}
         >
           {icon && <Icon>{icon}</Icon>}
-          <Input
-            ref={inputRef}
-            placeholder={placeholder}
-            value={displayValue}
-            onChange={(e) => {
-              setSearch(e.target.value);
-              setSearching(true);
-            }}
-            onFocus={() => {
-              // Start a fresh search; the selected label clears so the user can type.
-              setSearching(true);
-              setSearch("");
-              setOpen(true);
-            }}
-            onBlur={() => setSearching(false)}
-            className={cn("min-w-[100px] flex-1", {
-              "!h-[18px]": size === "XS",
-              "!h-[22px]": size === "S",
-              "!h-[24px]": size === "M",
-            })}
-          />
-          {/* Chevron toggle — boxed icon button matching the Select component. */}
-          <Button
-            as="span"
-            buttonType="icon"
-            tabIndex={-1}
-            aria-label={open ? "Close" : "Open"}
-            onMouseDown={(e: React.MouseEvent) => {
-              // Prevent the input's blur/focus race; toggle the dropdown.
-              e.preventDefault();
-              if (open) {
-                setOpen(false);
-              } else {
-                inputRef.current?.focus();
-                setOpen(true);
-              }
-            }}
+          <span
             className={cn(
-              "shrink-0 h-[32px] w-[32px] rounded-[4px]",
-              open && "bg-background-presentation-action-hover text-white"
+              "flex-1 px-1 truncate typography-body-medium-regular",
+              value
+                ? "text-content-presentation-action-light-primary"
+                : "text-content-presentation-action-light-secondary"
             )}
           >
-            <i
-              className={cn(
-                "ri-arrow-down-s-line text-[16px] transition-all duration-100 ease-in-out",
-                open && "rotate-180"
-              )}
-            />
-          </Button>
+            {value ? label(value) : placeholder}
+          </span>
+          <i className="ri-arrow-down-s-line text-[16px] shrink-0 text-content-presentation-action-light-primary" />
         </Group>
-      </PopoverTrigger>
+      </DialogTrigger>
 
-      <PopoverContent
+      <DialogContent
         dir={dir}
         data-theme={theme}
-        ref={popoverContentRef}
-        variant={variant}
-        onScroll={handleScroll}
-        // Lock the dropdown to the input's width; the table scrolls horizontally
-        // inside it. Cap height to ~maxVisibleRows (+ header) so the rest scrolls.
-        style={{
-          width: dropdownWidth || undefined,
-          maxHeight: HEADER_HEIGHT + maxVisibleRows * ROW_HEIGHT + 8,
+        onOpenAutoFocus={(e) => {
+          // Focus the search input instead of the first row.
+          e.preventDefault();
+          inputRef.current?.focus();
         }}
-        onOpenAutoFocus={(e) => e.preventDefault()}
-        className={cn(tableDropdownStyles({ variant }))}
+        className={cn(
+          "w-[min(640px,90vw)]  bg-transparent !items-stretch rounded-[14px] gap-3 shadow-none",
+        )}
       >
-        {filteredRows.length > 0 && (
-          // Table-DDV wrapper: frosted bordered card around the table (Figma).
-          // The radius + overflow-hidden also go on the <table> itself, because a
-          // <table>'s corner cells paint to square edges and otherwise cover an
-          // ancestor's rounded corners.
-          <div className="rounded-[10px] border overflow-x-auto  border-white-alpha-40 bg-[rgba(184,192,204,0.5)]">
+        {/* Visually-hidden title for accessibility (Radix requires a DialogTitle). */}
+        <DialogTitle className="sr-only">{title ?? "Select an item"}</DialogTitle>
+
+        {/* Search input — local inline-label field (full control over colors). */}
+        <SearchInput
+          ref={inputRef}
+          variant={variant}
+          theme={theme}
+          dir={dir}
+          label={title}
+          value={search}
+          placeholder={searchPlaceholder}
+          onChange={(e) => setSearch(e.target.value)}
+        />
+
+        {/* Scrollable table area */}
+        <div
+          ref={scrollRef}
+          onScroll={handleScroll}
+          className="max-h-[55vh] overflow-auto scrollbar-hide rounded-[10px] border border-white-alpha-40 bg-[rgba(184,192,204,0.5)]"
+        >
+          {filteredRows.length > 0 && (
             <Table
               theme={theme as never}
               data-theme="dark"
-              // Natural width (w-max) so columns keep their sizes and the wrapper
-              // scrolls horizontally instead of squeezing them into the input width.
-              className="w-max rounded-[10px] overflow-hidden"
+              className="w-full rounded-[10px] overflow-hidden"
             >
-              {/* The blurred dark header bar is painted on the TableHEAD cells
-                  (which fill the row); bg/height on a <tr> doesn't render
-                  reliably because cells paint over it. */}
-              <TableHeader className=" bg-black-alpha-20 shadow-[0px_4px_8px_0px_rgba(0,0,0,0.15)]">
+              <TableHeader className="bg-black-alpha-20 shadow-[0px_4px_8px_0px_rgba(0,0,0,0.15)]">
                 <TableRow className="h-[44px] [&_button]:bg-white-alpha-40 [&>th]:border-white-alpha-20">
                   {columns.map((col) => (
                     <TableHead
                       key={col.key}
-                      // White semibold header text from the design.
                       className="cursor-default typography-body-medium-medium text-white"
                     >
                       {col.header}
@@ -318,15 +256,14 @@ export function SearchableTable<T extends Record<string, unknown>>({
                       key={id}
                       state={selectedId === id ? "selected" : undefined}
                       onClick={() => handleSelect(row)}
-                      // h-[40px] rows with a translucent white bottom rule.
-                      className={cn("cursor-pointer h-[40px] ", selectedId === id && "bg-white-alpha-50")}
+                      className={cn(
+                        "cursor-pointer h-[40px]",
+                        selectedId === id && "bg-white-alpha-50"
+                      )}
                     >
                       {columns.map((col) => (
                         <TableCell
                           key={col.key}
-                          // White body text; whitespace-nowrap (overriding the
-                          // component's break-all) keeps columns wide so the
-                          // table overflows horizontally instead of wrapping.
                           className="border-b border-white-alpha-20 text-white px-[8px] !whitespace-nowrap !break-normal"
                         >
                           {col.render
@@ -339,25 +276,78 @@ export function SearchableTable<T extends Record<string, unknown>>({
                 })}
               </TableBody>
             </Table>
-          </div>
-        )}
+          )}
 
-        {/* Empty state — only when nothing is loading. */}
-        {filteredRows.length === 0 && !loading && (
-          <div className="px-3 py-4 typography-body-small-regular text-white-alpha-75">
-            No results found
-          </div>
-        )}
+          {/* Empty state — only when nothing is loading. */}
+          {filteredRows.length === 0 && !loading && (
+            <div className="px-3 py-6 text-center typography-body-small-regular text-white-alpha-75">
+              No results found
+            </div>
+          )}
 
-        {/* Loading row (initial load or fetching the next page). */}
-        {loading && (
-          <div className="flex items-center justify-center py-2">
-            <LoadingIcon size="M" />
-          </div>
-        )}
-      </PopoverContent>
-    </Popover>
+          {/* Loading row (initial load or fetching the next page). */}
+          {loading && (
+            <div className="flex items-center justify-center py-3">
+              <LoadingIcon size="M" />
+            </div>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
   );
 }
 
 SearchableTable.displayName = "SearchableTable";
+
+/* -------------------------------------------------------------------------- */
+/* SearchInput — local inline-label search field (replaces InnerLabelField).  */
+/* The whole field + its text turn white on hover/focus, fully controlled here. */
+/* -------------------------------------------------------------------------- */
+
+interface SearchInputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+  variant?: "SystemStyle" | "PresentationStyle";
+  theme?: Themes;
+  label?: string;
+}
+
+const SearchInput = forwardRef<HTMLInputElement, SearchInputProps>(
+  ({ variant = "PresentationStyle", theme, label, className, ...props }, ref) => (
+    <Group
+      data-theme={theme}
+      variant={variant}
+      size="M"
+      className={cn(
+        "group flex w-full items-center gap-2 p-1 rounded-[10px] transition-colors",
+        "border border-white-alpha-40 bg-[rgba(184,192,204,0.5)]",
+        "hover:bg-background-presentation-table-row-hover",
+        "focus-within:bg-background-presentation-table-row-hover",
+        className
+      )}
+    >
+      <Icon className="shrink-0">
+        <i className="ri-search-line text-content-presentation-global-secondary transition-colors group-hover:text-white group-focus-within:text-white" />
+      </Icon>
+
+      {label && (
+        <>
+          <span className="shrink-0 px-1 typography-labels-small-regular text-content-presentation-global-secondary text-[14px] text-white transition-colors group-hover:text-white group-focus-within:text-white">
+            {label}
+          </span>
+          <span className="h-[14px] w-px shrink-0 rounded-full bg-border-presentation-action-labelless-divider transition-colors group-hover:bg-white-alpha-40" />
+        </>
+      )}
+
+      <Input
+        ref={ref}
+        {...props}
+        className={cn(
+          "min-w-[100px] flex-1 !h-[24px] bg-transparent",
+          "text-content-presentation-action-light-primary",
+          "transition-colors group-hover:!text-white group-focus-within:!text-white"
+        )}
+      />
+    </Group>
+  )
+);
+SearchInput.displayName = "SearchInput";

package/docs/components/context-menu.md

@@ -233,6 +233,33 @@ function RtlMenu() {
 }
 ```
 
+### Long Menu (max height + scroll)
+
+Tall menus scroll instead of overflowing off-screen. The surface caps at `maxHeight` (default `320`px) and never exceeds the space available after collision handling. Pass `maxHeight` to change the cap.
+
+```typescript
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLabel } from '@torch-ui/components'
+
+function LongMenu() {
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>
+        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
+          Right-click here
+        </div>
+      </ContextMenuTrigger>
+      {/* Cap the surface at 220px — the rest scrolls. */}
+      <ContextMenuContent maxHeight={220}>
+        <ContextMenuLabel>Jump to section</ContextMenuLabel>
+        {Array.from({ length: 20 }, (_, i) => (
+          <ContextMenuItem key={i}>Section {i + 1}</ContextMenuItem>
+        ))}
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+```
+
 ## API Reference
 
 ### ContextMenu (Root)
@@ -264,6 +291,7 @@ The right-click zone. Wrap it around the element the menu should open from.
 | `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant (applied as `data-theme`) |
 | `className` | `string` | - | Additional CSS classes |
 | `collisionPadding` | `number` | `8` | Min distance kept from the viewport edge |
+| `maxHeight` | `number` | `320` | Max height (px) of the surface before it scrolls. Capped at `min(maxHeight, available-height)` so the menu never overflows off-screen |
 | `autoGroup` | `boolean` | `true` | Auto-wrap loose items in a Boxed group (see Behavior notes) |
 
 ### ContextMenuItem
@@ -353,6 +381,7 @@ interface ContextMenuContentProps {
   theme?: 'dark' | 'light' | 'default'
   className?: string
   collisionPadding?: number // default 8
+  maxHeight?: number         // default 320 — surface scrolls past this
   autoGroup?: boolean        // default true
 }
 
@@ -403,6 +432,7 @@ export const ContextMenuRadioItem: React.ForwardRefExoticComponent<ContextMenuRa
 - **Opens at the pointer**: the menu opens on right-click (`contextmenu`) at the exact cursor position, not anchored to a fixed trigger button.
 - **Second right-click closes it**: the Root is made controlled and tracks `open` in context. The Trigger listens in the capture phase, and when the menu is already open it `preventDefault()` / `stopPropagation()` and closes — so a second right-click dismisses instead of re-anchoring (which Radix handles unreliably).
 - **Auto-grouping**: by default (`autoGroup` on `ContextMenuContent`, default `true`) consecutive loose items (`ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioItem`, and `ContextMenuSub`) are automatically wrapped in a `Boxed` `ContextMenuGroup`, so they render inside a boxed container like DropdownMenu even when you do not write a group. Labels and explicit groups act as boundaries and pass through unchanged. Set `autoGroup={false}` to render children verbatim.
+- **Max height & scrolling**: the surface caps its height at `min(maxHeight, available-height)` (where `maxHeight` defaults to `320`px and `available-height` is the space Radix has after collision handling). A taller menu scrolls vertically instead of overflowing off-screen — items and groups keep their full height rather than squishing. Pass `maxHeight={N}` to change the cap.
 - **Checkbox / radio keep the menu open**: `ContextMenuCheckboxItem` and `ContextMenuRadioItem` call `event.preventDefault()` inside `onSelect`, stopping Radix's default auto-close so users can toggle multiple options in one pass.
 - **Open-only animation**: only the open (enter) state animates (`fade-in`). There is intentionally no exit animation — holding the old DOM node during close breaks close/reposition on a second right-click, so it is omitted to keep repositioning reliable.
 - **Submenus and RTL**: nested `ContextMenuSub` / `ContextMenuSubTrigger` / `ContextMenuSubContent` are supported, and `dir="rtl"` on the Root mirrors the layout (including the submenu chevron).

package/docs/components/data-views-config-panel.md

@@ -148,7 +148,7 @@ render `DataViewsConfigPanel` yourself (example above) or extend the layout
 | Saved View | `savedViews` / `activeSavedView` | Radio list + "Save a New View" button. |
 | Table Columns | `config.tableColumns` | Green `Switch` per column toggles `visible`; rows are drag-reorderable (HTML5 DnD) and patch `order`. |
 | Default Sort | `config.sortBy` | Single-choice radio; selecting sets `sortBy`. Direction stays on `config.sortOrder`. |
-| Filters tab | `filterState` + `fields` | Renders `FilterPanel` restyled full-width/transparent. |
+| Filters tab | `filterState` + `fields` | Renders `FilterPanel` restyled full-width/transparent. Categorical fields render as checkbox/radio lists, or a `SearchableSelect` dropdown when a field sets `filterVariant: "searchable-select"`. |
 
 ## Internal: PanelControls
 
@@ -173,8 +173,8 @@ Common changes and where to make them:
 |---|---|
 | Make Saved View work through `DataViewsLayout` | Add `savedViews` / `activeSavedView` / `onSavedViewChange` / `onSaveNewView` to `DataViewsLayoutProps`, hold them in layout state (or accept from the host), and forward them to `<DataViewsConfigPanel>` at its render site in `DataViewsLayout.tsx`. |
 | Add a new Config section | Add a new block inside the Config. tab in `DataViewsConfigPanel.tsx`, backed by a `config.*` field so `onConfigChange` persists it. |
-| Restyle a radio/toggle | Edit `PanelControls.tsx`. Keep values matching the Figma spec; do not swap in the shared `Radio`/`Label` (they impose theming/layout that fights the dark panel — this was deliberate). |
-| Change the dark chrome | The root forces `data-theme="dark"` and uses hardcoded hex (`#1C1D1F`, `#252729`, `#005ECC`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens. |
+| Restyle a radio/toggle | Edit the radio ring in `DataViewRadio.tsx` (the `RadioRow` in `PanelControls.tsx` just wraps it) or the switch in `PanelControls.tsx`. Keep the hardcoded hex matching the Figma spec; do not swap in the shared `Radio`/`Label` (they impose theming/layout that fights the dark panel — this was deliberate). |
+| Change the dark chrome | The root forces `data-theme="dark"` and uses hardcoded hex (`#1C1D1F`, `#252729`, `#005ECC`, `#0075FF`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens — the radio/checkbox rings hardcode them (`#626467` border, `rgba(255,255,255,0.05)` fill, `#0075FF` selected) so the panel always renders dark regardless of host `data-theme`. |
 
 After any change to the panel docs or component, update this file and rebuild
 the MCP server (`cd mcp && pnpm build`) so the docs the server serves stay in

package/docs/components/data-views-layout.md

@@ -176,7 +176,11 @@ Inbox auto-detects `isRead`, `isStarred`, `hasAttachment`, `priority`. Override
 | `type` | `FieldType` | Renderer key (see below). Auto-inferred if omitted. |
 | `visible` | `boolean` | Show in cells. Default `true`. |
 | `order` | `number` | Display order. |
-| `filterable` | `boolean` | Surface this field in the filter panel. |
+| `filterable` | `boolean` | Surface this field in the filter panel. The control adapts to the field `type`: categorical fields render checkboxes/radios (or a searchable dropdown via `filterVariant`), numeric fields a range slider, and **date / date-format fields a From + To pair of Glare `DatePicker`s** (two single-date pickers bounding the range). Set `false` to explicitly exclude a field the panel would otherwise auto-detect (e.g. an `id` or `name` with few unique values). |
+| `filterLabel` | `string` | Override the label shown above this field's filter (defaults to `label`). |
+| `filterMode` | `"single" \| "multi"` | Categorical selection mode. `"multi"` (default) renders checkboxes; `"single"` renders radios. |
+| `filterVariant` | `"checkbox" \| "searchable-select"` | Categorical control style. `"checkbox"` (default) is the inline checkbox/radio list; `"searchable-select"` renders a single-select `SearchableSelect` dropdown — useful when a field has many options. Implies single-select. |
+| `filterOptions` | `string[] \| { label: string; value: string }[]` | Explicit option list for the categorical filter (otherwise options are collected from the data). |
 | `variants` | `Record<string, BadgeVariant>` | For `enum-badge`: per-value color map. |
 | `currency` | `string \| CurrencyOptions` | For `currency`: ISO code or `{ symbol, locale, decimals, code }`. |
 | `thresholds` | `[number, number]` | For `progress-bar`: warning/ok thresholds. |
@@ -188,6 +192,8 @@ Inbox auto-detects `isRead`, `isStarred`, `hasAttachment`, `priority`. Override
 
 `text` · `number` · `date` · `date-format` · `boolean` · `currency` · `number-format` · `enum-badge` · `badge-array` · `progress-bar` · `star-rating` · `icon-text` · `two-line` · `avatar` · `link` · `image` · `hidden`
 
+> **`hidden` vs `filterable: false`** — use `type: "hidden"` to drop a field from the UI **entirely** (no column, no column-toggle in the config panel, no filter) while it stays in the data for row identity — e.g. an `id` you key rows by but never want shown. Use `filterable: false` to keep a field as a **column** but remove only its **filter**.
+
 ### `BadgeVariant`
 
 `green` · `greenLight` · `cocktailGreen` · `yellow` · `redOrange` · `redLight` · `rose` · `purple` · `bluePurple` · `blue` · `navy` · `gray` · `highlight`

package/docs/components/dropdown-menu.md

@@ -299,6 +299,32 @@ function Example() {
 }
 ```
 
+### Long Menu (max height + scroll)
+
+Tall menus scroll instead of overflowing off-screen. The surface caps at `maxHeight` (default `320`px) and never exceeds the space available after collision handling. Pass `maxHeight` to change the cap.
+
+```typescript
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel } from '@torch-ui/components'
+import { Button } from '@torch-ui/components'
+
+function LongMenu() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="BorderStyle">Jump to section</Button>
+      </DropdownMenuTrigger>
+      {/* Cap the surface at 240px — the rest scrolls. */}
+      <DropdownMenuContent align="start" maxHeight={240}>
+        <DropdownMenuLabel>Sections</DropdownMenuLabel>
+        {Array.from({ length: 20 }, (_, i) => (
+          <DropdownMenuItem key={i}>Section {i + 1}</DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
 ## API Reference
 
 ### DropdownMenu (Root)
@@ -326,6 +352,7 @@ function Example() {
 | `sideOffset` | `number` | `4` | Distance from trigger |
 | `collisionPadding` | `number` | `8` | Gap kept from viewport edges when flipping/shifting |
 | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment (inherited from Radix) |
+| `maxHeight` | `number` | `320` | Max height (px) of the surface before it scrolls. Capped at `min(maxHeight, available-height)` so the menu never overflows off-screen |
 | `autoGroup` | `boolean` | `true` | Auto-wrap loose items in boxed groups |
 
 ### DropdownMenuItem
@@ -426,6 +453,7 @@ interface DropdownMenuContentProps {
   sideOffset?: number
   collisionPadding?: number
   align?: 'start' | 'center' | 'end'
+  maxHeight?: number         // default 320 — surface scrolls past this
   autoGroup?: boolean
 }