@iloveagents/foundry-web-ui 0.18.0 → 0.20.0

package/dist/components/data-table/facets.js

@@ -1,3 +1,16 @@
+/**
+ * The list width at which each band starts earning its columns. Measured on
+ * the list itself, not the viewport — a list in a side pane is narrow even on
+ * a wide screen. Exported so a host that derives breakpoints from a schema
+ * measures against the same numbers the table renders by.
+ */
+export const DATA_TABLE_MIN_WIDTH = {
+    sm: 448,
+    md: 672,
+    lg: 896,
+    xl: 1024,
+    "2xl": 1280,
+};
 /** Facet key for empty cells (`null`, `undefined`, `""`, `[]`). */
 export const FACET_EMPTY = "__none__";
 /**
@@ -5,6 +18,16 @@ export const FACET_EMPTY = "__none__";
  * element. A real value that spells the empty sentinel is escaped with a
  * leading backslash so it never masquerades as "no value".
  */
+export function columnFacetKeys(column, value) {
+    const buckets = column.columnDef.meta?.facetBuckets;
+    if (!buckets)
+        return facetKeys(value);
+    // Unique, like `facetKeys` is for arrays: a bucket rule that overlaps
+    // itself would otherwise count one row twice and report a facet with more
+    // matches than there are rows.
+    const keys = Array.from(new Set(buckets(value).filter((key) => key !== "")));
+    return keys.length ? keys : [FACET_EMPTY];
+}
 export function facetKeys(value) {
     if (value == null || value === "")
         return [FACET_EMPTY];
@@ -21,6 +44,21 @@ export function facetKeys(value) {
     }
     return [String(value)];
 }
+// TanStack memoizes a row's cells, so the array identity is a safe cache key:
+// the id → column map is built once per row instead of scanned once per row
+// per active filter (a scan that is O(columns) on every pass over the data).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const rowColumnCache = new WeakMap();
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function columnOfRow(row, columnId) {
+    const cells = row.getAllCells();
+    let byId = rowColumnCache.get(cells);
+    if (!byId) {
+        byId = new Map(cells.map((cell) => [cell.column.id, cell.column]));
+        rowColumnCache.set(cells, byId);
+    }
+    return byId.get(columnId);
+}
 /** A facet filter value is a list of selected keys; anything else means "no filter". */
 export function normalizeFacetValue(filterValue) {
     if (Array.isArray(filterValue))
@@ -39,14 +77,18 @@ export const facetFilterFn = (row, columnId, filterValue) => {
     const wanted = normalizeFacetValue(filterValue);
     if (!wanted.length)
         return true;
-    return facetKeys(row.getValue(columnId)).some((key) => wanted.includes(key));
+    const column = columnOfRow(row, columnId);
+    const keys = column
+        ? columnFacetKeys(column, row.getValue(columnId))
+        : facetKeys(row.getValue(columnId));
+    return keys.some((key) => wanted.includes(key));
 };
 facetFilterFn.autoRemove = (value) => normalizeFacetValue(value).length === 0;
 /** Rows per facet key, counted over the rows every OTHER filter lets through. */
 export function facetCounts(column) {
     const counts = new Map();
     for (const row of column.getFacetedRowModel().flatRows) {
-        for (const key of facetKeys(row.getValue(column.id))) {
+        for (const key of columnFacetKeys(column, row.getValue(column.id))) {
             counts.set(key, (counts.get(key) ?? 0) + 1);
         }
     }

package/dist/components/data-table/use-data-table.d.ts

@@ -1,4 +1,4 @@
-import { type ColumnDef, type FilterFn, type Row, type Table } from "@tanstack/react-table";
+import { type ColumnDef, type FilterFn, type Row, type Table, type VisibilityState } from "@tanstack/react-table";
 import { type DataTableState } from "./state.js";
 export interface UseDataTableOptions<T> {
     data: T[];
@@ -19,4 +19,16 @@ export interface UseDataTableOptions<T> {
     /** Replace the default AND-of-tokens search. */
     globalFilterFn?: FilterFn<T>;
 }
+/**
+ * `{ id: false }` for every column whose `meta.defaultHidden` says it starts
+ * out of the way — the leaves, since visibility is a leaf property and a
+ * grouping header has no state to hide.
+ *
+ * `useDataTable` applies this to its own initial state. A list whose state
+ * lives somewhere else (the URL) must pass it as part of that layer's
+ * `defaults` instead: re-applying it on every render would undo the user the
+ * moment they bring a column out, because "visible" is exactly what a
+ * hidden-only URL does not record.
+ */
+export declare function defaultHiddenColumns<T>(columns: readonly ColumnDef<T, any>[]): VisibilityState;
 export declare function useDataTable<T>(options: UseDataTableOptions<T>): Table<T>;

package/dist/components/data-table/use-data-table.js

@@ -9,13 +9,60 @@ import { getCoreRowModel, getExpandedRowModel, getFacetedRowModel, getFacetedUni
 import { facetFilterFn, tokenSearchFilterFn } from "./facets.js";
 import { DEFAULT_PAGE_SIZE, EMPTY_DATA_TABLE_STATE } from "./state.js";
 const PAGE_RESET_KEYS = new Set(["globalFilter", "columnFilters", "sorting"]);
+/**
+ * TanStack's own rule for a column's id, mirrored so `meta.defaultHidden` can
+ * be resolved before the table exists: an explicit `id`, else the
+ * `accessorKey` with EVERY dot turned into an underscore (`user.profile.name`
+ * → `user_profile_name`), else a string header. Anything else has no stable
+ * id to key visibility by.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function columnId(column) {
+    if (column.id)
+        return column.id;
+    const accessorKey = "accessorKey" in column ? column.accessorKey : undefined;
+    if (accessorKey != null)
+        return String(accessorKey).replace(/\./g, "_");
+    return typeof column.header === "string" ? column.header : undefined;
+}
+/**
+ * `{ id: false }` for every column whose `meta.defaultHidden` says it starts
+ * out of the way — the leaves, since visibility is a leaf property and a
+ * grouping header has no state to hide.
+ *
+ * `useDataTable` applies this to its own initial state. A list whose state
+ * lives somewhere else (the URL) must pass it as part of that layer's
+ * `defaults` instead: re-applying it on every render would undo the user the
+ * moment they bring a column out, because "visible" is exactly what a
+ * hidden-only URL does not record.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function defaultHiddenColumns(columns) {
+    const hidden = {};
+    const walk = (defs) => {
+        for (const column of defs) {
+            const children = "columns" in column ? column.columns : undefined;
+            if (children?.length) {
+                walk(children);
+                continue;
+            }
+            const id = columnId(column);
+            if (id && column.meta?.defaultHidden)
+                hidden[id] = false;
+        }
+    };
+    walk(columns);
+    return hidden;
+}
 export function useDataTable(options) {
     const { data, columns, getRowId, state: controlledState, onStateChange, initialState, pageSize, groupBy, enableRowSelection = false, enableMultiRowSelection = true, globalFilterFn, } = options;
     const controlled = controlledState !== undefined && onStateChange !== undefined;
     const basePageSize = pageSize || DEFAULT_PAGE_SIZE;
+    const defaultHidden = useMemo(() => defaultHiddenColumns(columns), [columns]);
     const [innerState, setInnerState] = useState(() => ({
         ...EMPTY_DATA_TABLE_STATE,
         ...initialState,
+        columnVisibility: { ...defaultHidden, ...initialState?.columnVisibility },
         pagination: { pageIndex: 0, pageSize: basePageSize, ...initialState?.pagination },
     }));
     const state = useMemo(() => controlled

package/dist/components/data-table/use-element-width.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The measured width of an element, or `undefined` until it has one. Lists
+ * use it to decide which columns fit: a table beside an open detail pane is
+ * narrower than the window, and only the table knows by how much.
+ */
+import { type RefObject } from "react";
+export declare function useElementWidth(ref: RefObject<HTMLElement | null>): number | undefined;

package/dist/components/data-table/use-element-width.js

@@ -0,0 +1,36 @@
+/**
+ * The measured width of an element, or `undefined` until it has one. Lists
+ * use it to decide which columns fit: a table beside an open detail pane is
+ * narrower than the window, and only the table knows by how much.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+export function useElementWidth(ref) {
+    const [width, setWidth] = useState(undefined);
+    // The ref OBJECT is stable while the node it holds may not be: a caller
+    // that swaps the element keeps the same ref, and an observer bound once
+    // would go on measuring the detached node forever. So the element itself
+    // is state, refreshed after every render that changed it.
+    const [element, setElement] = useState(null);
+    const seen = useRef(null);
+    useLayoutEffect(() => {
+        if (ref.current === seen.current)
+            return;
+        seen.current = ref.current;
+        setElement(ref.current);
+    });
+    useEffect(() => {
+        if (!element || typeof ResizeObserver === "undefined")
+            return;
+        const read = () => {
+            const next = element.getBoundingClientRect().width;
+            // A zero width means "not laid out yet" (or a test environment); treat
+            // it as unmeasured so nothing is hidden on a guess.
+            setWidth((current) => (next > 0 && Math.abs((current ?? -1) - next) > 0.5 ? next : current));
+        };
+        const observer = new ResizeObserver(read);
+        observer.observe(element);
+        read();
+        return () => observer.disconnect();
+    }, [element]);
+    return width;
+}

package/dist/components/data-table/use-pinned-offsets.d.ts

@@ -0,0 +1,9 @@
+export interface PinnedOffsets {
+    /** `columnId → left offset in px`, for the columns that are pinned. */
+    offsets: Record<string, number>;
+    /** The id of the last pinned column, which carries the edge shadow. */
+    lastPinned: string | null;
+    /** Attach to each pinned header cell so its width is tracked. */
+    measure: (columnId: string) => (element: HTMLElement | null) => void;
+}
+export declare function usePinnedOffsets(pinnedIds: readonly string[]): PinnedOffsets;

package/dist/components/data-table/use-pinned-offsets.js

@@ -0,0 +1,79 @@
+/**
+ * Left offsets for pinned columns. A pinned column sticks to the left edge
+ * of the scroll container; the ones after it stack behind their predecessors,
+ * so each needs the summed width of the pinned columns before it. Widths are
+ * measured from the rendered header cells (a column's declared `size` is a
+ * hint, not the used width) and kept current with a `ResizeObserver`.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+export function usePinnedOffsets(pinnedIds) {
+    const elements = useRef(new Map());
+    const [widths, setWidths] = useState({});
+    const key = pinnedIds.join(",");
+    const read = useCallback(() => {
+        setWidths((current) => {
+            let changed = false;
+            const next = {};
+            for (const [id, element] of elements.current) {
+                const width = element.getBoundingClientRect().width;
+                next[id] = width;
+                if (Math.abs((current[id] ?? -1) - width) > 0.5)
+                    changed = true;
+            }
+            if (!changed && Object.keys(next).length === Object.keys(current).length)
+                return current;
+            return next;
+        });
+    }, []);
+    const observerRef = useRef(null);
+    useEffect(() => {
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(read);
+        observerRef.current = observer;
+        for (const element of elements.current.values())
+            observer.observe(element);
+        read();
+        return () => {
+            observer.disconnect();
+            observerRef.current = null;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, read]);
+    // One stable callback per column: a fresh ref callback on every render
+    // would make React detach and re-attach the ref each time.
+    const callbacks = useRef(new Map());
+    const measure = useCallback((columnId) => {
+        const existing = callbacks.current.get(columnId);
+        if (existing)
+            return existing;
+        const callback = (element) => {
+            const previous = elements.current.get(columnId);
+            if (previous === element)
+                return;
+            if (previous)
+                observerRef.current?.unobserve(previous);
+            if (element) {
+                elements.current.set(columnId, element);
+                observerRef.current?.observe(element);
+            }
+            else {
+                elements.current.delete(columnId);
+            }
+            read();
+        };
+        callbacks.current.set(columnId, callback);
+        return callback;
+    }, [read]);
+    const offsets = {};
+    let running = 0;
+    for (const id of pinnedIds) {
+        offsets[id] = running;
+        running += widths[id] ?? 0;
+    }
+    return {
+        offsets,
+        lastPinned: pinnedIds.length ? pinnedIds[pinnedIds.length - 1] : null,
+        measure,
+    };
+}

package/dist/index.d.ts

@@ -35,16 +35,20 @@ export { InfiniteScrollSentinel } from "./components/infinite-scroll-sentinel.js
 export { CollectionSurface } from "./components/collection-surface.js";
 export { DataTable, type DataTableProps } from "./components/data-table/data-table.js";
 export { DataTableFrame, useDataTableFrame, type DataTableFrameProps, type DataTableFrameContextValue, } from "./components/data-table/data-table-frame.js";
-export { DataTableToolbar, visibleFacets, type DataTableFacet, type DataTableToolbarProps, } from "./components/data-table/data-table-toolbar.js";
+export { DataTableSelectionBar, type DataTableSelectionBarProps, } from "./components/data-table/data-table-selection-bar.js";
+export { DataTableToolbar, visibleFacets, type DataTableFacet, type DataTableToolbarLayout, type DataTableToolbarProps, } from "./components/data-table/data-table-toolbar.js";
 export { DataTableFacetedFilter, type DataTableFacetedFilterProps, } from "./components/data-table/data-table-faceted-filter.js";
 export { DataTableViewOptions, type DataTableViewOptionsProps, } from "./components/data-table/data-table-view-options.js";
 export { DataTableColumnHeader, type DataTableColumnHeaderProps, } from "./components/data-table/data-table-column-header.js";
 export { DataTablePagination, type DataTablePaginationProps, } from "./components/data-table/data-table-pagination.js";
 export { DataTableRowActions, type DataTableRowAction, type DataTableRowActionsProps, } from "./components/data-table/data-table-row-actions.js";
 export { selectionColumn, SELECTION_COLUMN_ID } from "./components/data-table/selection-column.js";
-export { useDataTable, type UseDataTableOptions } from "./components/data-table/use-data-table.js";
+export { useDataTable, defaultHiddenColumns, type UseDataTableOptions, } from "./components/data-table/use-data-table.js";
+export { usePinnedOffsets, type PinnedOffsets, } from "./components/data-table/use-pinned-offsets.js";
+export { useElementWidth } from "./components/data-table/use-element-width.js";
 export { DEFAULT_PAGE_SIZE, EMPTY_DATA_TABLE_STATE, isDataTableUrlKey, mergeDataTableUrlState, parseDataTableState, serializeDataTableState, type DataTableState, type DataTableUrlOptions, } from "./components/data-table/state.js";
-export { FACET_EMPTY, cellText, columnLabel, facetCounts, facetFilterFn, facetKeys, facetOptions, normalizeFacetValue, rowSearchText, tokenSearchFilterFn, type DataTableBreakpoint, type DataTableFacetCount, type DataTableFacetOption, } from "./components/data-table/facets.js";
+export { ageBucket, ageBuckets, dueState, parseDateish, relativeAge, type AgeBucket, type DateBucketOptions, type DueState, type DueStateOptions, } from "./components/data-table/date-buckets.js";
+export { DATA_TABLE_MIN_WIDTH, FACET_EMPTY, cellText, columnFacetKeys, columnLabel, facetCounts, facetFilterFn, facetKeys, facetOptions, normalizeFacetValue, rowSearchText, tokenSearchFilterFn, type DataTableBreakpoint, type DataTableFacetCount, type DataTableFacetOption, } from "./components/data-table/facets.js";
 export { createColumnHelper, flexRender, type Column, type ColumnDef, type ColumnFiltersState, type Row, type RowSelectionState, type SortingState, type Table, type VisibilityState, } from "@tanstack/react-table";
 export { ThemeRuntimeProvider, ThemeScope, ThemeDocumentMetadata, useThemeRuntime, } from "./components/theme-runtime-provider.js";
 export { JsonViewer } from "./components/json-viewer.js";

package/dist/index.js

@@ -33,6 +33,7 @@ export { InfiniteScrollSentinel } from "./components/infinite-scroll-sentinel.js
 export { CollectionSurface } from "./components/collection-surface.js";
 export { DataTable } from "./components/data-table/data-table.js";
 export { DataTableFrame, useDataTableFrame, } from "./components/data-table/data-table-frame.js";
+export { DataTableSelectionBar, } from "./components/data-table/data-table-selection-bar.js";
 export { DataTableToolbar, visibleFacets, } from "./components/data-table/data-table-toolbar.js";
 export { DataTableFacetedFilter, } from "./components/data-table/data-table-faceted-filter.js";
 export { DataTableViewOptions, } from "./components/data-table/data-table-view-options.js";
@@ -40,9 +41,12 @@ export { DataTableColumnHeader, } from "./components/data-table/data-table-colum
 export { DataTablePagination, } from "./components/data-table/data-table-pagination.js";
 export { DataTableRowActions, } from "./components/data-table/data-table-row-actions.js";
 export { selectionColumn, SELECTION_COLUMN_ID } from "./components/data-table/selection-column.js";
-export { useDataTable } from "./components/data-table/use-data-table.js";
+export { useDataTable, defaultHiddenColumns, } from "./components/data-table/use-data-table.js";
+export { usePinnedOffsets, } from "./components/data-table/use-pinned-offsets.js";
+export { useElementWidth } from "./components/data-table/use-element-width.js";
 export { DEFAULT_PAGE_SIZE, EMPTY_DATA_TABLE_STATE, isDataTableUrlKey, mergeDataTableUrlState, parseDataTableState, serializeDataTableState, } from "./components/data-table/state.js";
-export { FACET_EMPTY, cellText, columnLabel, facetCounts, facetFilterFn, facetKeys, facetOptions, normalizeFacetValue, rowSearchText, tokenSearchFilterFn, } from "./components/data-table/facets.js";
+export { ageBucket, ageBuckets, dueState, parseDateish, relativeAge, } from "./components/data-table/date-buckets.js";
+export { DATA_TABLE_MIN_WIDTH, FACET_EMPTY, cellText, columnFacetKeys, columnLabel, facetCounts, facetFilterFn, facetKeys, facetOptions, normalizeFacetValue, rowSearchText, tokenSearchFilterFn, } from "./components/data-table/facets.js";
 export { createColumnHelper, flexRender, } from "@tanstack/react-table";
 export { ThemeRuntimeProvider, ThemeScope, ThemeDocumentMetadata, useThemeRuntime, } from "./components/theme-runtime-provider.js";
 export { JsonViewer } from "./components/json-viewer.js";

package/dist/lib/app-store.d.ts

@@ -51,6 +51,8 @@ export type ContextPayload = TextPayload | PagePayload | ReferencePayload;
 export type ContextItemType = "selection" | "page" | "ref" | "note";
 export interface ContextItem {
     id: string;
+    /** Set for context that tracks the UI (a list's selection): one item per key. */
+    key?: string;
     type: ContextItemType;
     label: string;
     payload: ContextPayload;
@@ -103,7 +105,15 @@ interface AppState {
     clearHighlights: () => void;
     contextItems: ContextItem[];
     sentContext: Record<string, ContextItem[]>;
-    addContextItem: (item: Omit<ContextItem, "id" | "createdAt">) => void;
+    /** Context the user pinned. Keyed (UI-tracked) items go through
+     *  `setContextItem`, which is the only thing that replaces by key. */
+    addContextItem: (item: Omit<ContextItem, "id" | "createdAt" | "key">) => void;
+    /**
+     * Context that tracks a piece of UI rather than a user's pin — the rows
+     * selected in a list, say. One item per `key`: setting replaces, `null`
+     * clears. Without this, a chip that changes with the UI would pile up.
+     */
+    setContextItem: (key: string, item: Omit<ContextItem, "id" | "createdAt"> | null) => void;
     removeContextItem: (id: string) => void;
     promoteContextItem: (id: string) => void;
     clearAllContext: () => void;

package/dist/lib/app-store.js

@@ -60,10 +60,15 @@ export const useAppStore = create((set, get) => ({
         const prev = get().currentPage;
         if (prev === page)
             return;
-        // Clear ephemeral context on navigation
+        // Clear ephemeral context on navigation — and every KEYED item, whatever
+        // its persistence: those track a piece of UI, and that UI is gone. A pin
+        // the user made survives, because promoting an item drops its key.
         set({
             currentPage: page,
-            contextItems: get().contextItems.filter((i) => i.persistence !== "ephemeral"),
+            contextItems: get().contextItems.filter(
+            // `key === undefined`, not falsy: "" is a key someone chose, and a
+            // keyed item tracks UI that this navigation just unmounted.
+            (i) => i.persistence !== "ephemeral" && i.key === undefined),
         });
     },
     // Navigation context
@@ -118,9 +123,36 @@ export const useAppStore = create((set, get) => ({
             ],
         });
     },
+    setContextItem: (key, item) => {
+        const withoutKey = get().contextItems.filter((existing) => existing.key !== key);
+        if (!item) {
+            if (withoutKey.length !== get().contextItems.length)
+                set({ contextItems: withoutKey });
+            return;
+        }
+        if (withoutKey.length >= MAX_ITEMS)
+            return;
+        const label = item.label.length > MAX_LABEL_LENGTH
+            ? `${item.label.slice(0, MAX_LABEL_LENGTH)}...`
+            : item.label;
+        set({
+            contextItems: [
+                ...withoutKey,
+                { ...item, key, label, id: crypto.randomUUID(), createdAt: Date.now() },
+            ],
+        });
+    },
     removeContextItem: (id) => set({ contextItems: get().contextItems.filter((i) => i.id !== id) }),
     promoteContextItem: (id) => set({
-        contextItems: get().contextItems.map((i) => i.id === id ? { ...i, persistence: "persistent" } : i),
+        contextItems: get().contextItems.map((i) => {
+            if (i.id !== id)
+                return i;
+            // Pinning takes the item away from the UI that was tracking it: the
+            // key goes, so the next selection change replaces nothing and the
+            // pin the user made survives.
+            const { key: _tracked, ...rest } = i;
+            return { ...rest, persistence: "persistent" };
+        }),
     }),
     clearAllContext: () => set({ contextItems: [], sentContext: {} }),
     consumeContextForMessage: (messageId) => {
@@ -128,9 +160,14 @@ export const useAppStore = create((set, get) => ({
         if (contextItems.length === 0)
             return [];
         const snapshot = [...contextItems];
-        // Keep persistent, remove ephemeral
+        // Keep persistent, remove ephemeral — except context that TRACKS the UI
+        // (a keyed item, e.g. a live list selection). Those rows are still
+        // ticked after the message goes; dropping the chip would take them out
+        // of every later message while the user can still see them selected.
+        // Their owner clears them (`setContextItem(key, null)`), and navigation
+        // still does.
         set({
-            contextItems: contextItems.filter((i) => i.persistence === "persistent"),
+            contextItems: contextItems.filter((i) => i.persistence === "persistent" || i.key !== undefined),
             sentContext: { ...sentContext, [messageId]: snapshot },
         });
         return snapshot;

package/dist/styles.css

@@ -140,3 +140,94 @@
   --code-block: oklch(0.16 0.01 286);
   --code-block-foreground: oklch(0.9 0.01 286);
 }
+
+/* ---------------------------------------------------------------- lists --
+ * Rules the components need but a host's CSS scanner cannot infer, so they
+ * ship here. Import this stylesheet (see the README) to get them.
+ */
+
+/* A long menu — every column of a wide list — stays reachable: capped to the
+ * room the trigger has and scrollable inside it. */
+[data-menu-scroll] {
+  max-height: var(--radix-dropdown-menu-content-available-height);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+/* Frozen columns. The cell has to be opaque, since the other columns scroll
+ * underneath it, so the row's translucent states are restated opaquely. */
+[data-pinned] {
+  position: sticky;
+}
+/* The frozen column slides under the sticky header, never over it: the header
+ * row carries z-10 (see `DataTable`), so a frozen body cell has to sit below
+ * that, and the frozen header cell only has to beat its own row. */
+[data-pinned="header"] {
+  z-index: 2;
+  background-color: var(--card);
+}
+/* An opaque stand-in for the table's own surface (`bg-card/60` over the
+ * page), not the page background — otherwise the frozen strip reads as a
+ * different colour from the rows it belongs to, most visibly in dark mode. */
+[data-pinned="cell"] {
+  z-index: 1;
+  /* The opaque equal of the table's own `bg-card/60`. Every row state below
+   * mixes its tint into THIS, the way a translucent tint on an ordinary cell
+   * lands on the table surface rather than on the page. */
+  --pinned-surface: color-mix(in srgb, var(--card) 60%, var(--background));
+  background-color: var(--pinned-surface);
+}
+/* The seam says "there is more to the left" — so it appears only once the
+ * list is actually scrolled sideways, and stays quiet otherwise. */
+[data-scrolled-x] [data-pinned-edge] {
+  border-right: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+  box-shadow: 6px 0 6px -6px color-mix(in srgb, var(--foreground) 12%, transparent);
+}
+
+/* A list you can scroll should say so: keep its scrollbars visible rather
+ * than relying on the overlay ones macOS hides until you already scroll. */
+[data-list-scroller] {
+  scrollbar-gutter: stable;
+  scrollbar-width: thin;
+  scrollbar-color: color-mix(in srgb, var(--foreground) 25%, transparent) transparent;
+}
+[data-list-scroller]::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+[data-list-scroller]::-webkit-scrollbar-track {
+  background: transparent;
+}
+[data-list-scroller]::-webkit-scrollbar-thumb {
+  border: 3px solid transparent;
+  border-radius: 999px;
+  background-clip: content-box;
+  background-color: color-mix(in srgb, var(--foreground) 22%, transparent);
+}
+[data-list-scroller]:hover::-webkit-scrollbar-thumb {
+  background-color: color-mix(in srgb, var(--foreground) 32%, transparent);
+}
+
+/* A group header spans the scrollable width; its content sticks to the
+ * viewport so the label and total stay readable while columns scroll. */
+[data-group-content] {
+  position: sticky;
+  left: 0;
+}
+/* Only rows that actually respond to a hover — `DataTable` marks those —
+ * so a read-only row never lights up its frozen half alone. */
+tr[data-clickable]:hover > [data-pinned="cell"] {
+  background-color: color-mix(in srgb, var(--muted) 30%, var(--pinned-surface));
+}
+/* Only when the ROW itself is focused. A control inside a cell does not tint
+ * the ordinary cells, so tinting the frozen ones would make the strip diverge
+ * exactly while someone is using that control. */
+tr[data-focusable]:focus-visible > [data-pinned="cell"] {
+  background-color: color-mix(in srgb, var(--muted) 30%, var(--pinned-surface));
+}
+tr[data-state="selected"] > [data-pinned="cell"] {
+  background-color: color-mix(in srgb, var(--primary) 6%, var(--pinned-surface));
+}
+tr[data-active] > [data-pinned="cell"] {
+  background-color: color-mix(in srgb, var(--primary) 8%, var(--pinned-surface));
+}

package/dist/ui/dropdown-menu.js

@@ -5,7 +5,7 @@ import { Check } from "lucide-react";
 import { cn } from "@iloveagents/foundry-web-primitives";
 export const DropdownMenu = DropdownMenuPrimitive.Root;
 export const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
-export const DropdownMenuContent = forwardRef(({ className, sideOffset = 4, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Portal, { children: _jsx(DropdownMenuPrimitive.Content, { ref: ref, sideOffset: sideOffset, className: cn("z-50 min-w-[8rem] overflow-hidden rounded-md border border-border", "bg-popover p-1 text-popover-foreground shadow-md", "data-[state=open]:animate-in data-[state=closed]:animate-out", "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0", "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95", "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2", "data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2", className), ...props }) })));
+export const DropdownMenuContent = forwardRef(({ className, sideOffset = 4, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Portal, { children: _jsx(DropdownMenuPrimitive.Content, { ref: ref, sideOffset: sideOffset, "data-menu-scroll": "", className: cn("z-50 min-w-[8rem] rounded-md border border-border", "bg-popover p-1 text-popover-foreground shadow-md", "data-[state=open]:animate-in data-[state=closed]:animate-out", "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0", "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95", "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2", "data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2", className), ...props }) })));
 DropdownMenuContent.displayName = "DropdownMenuContent";
 export const DropdownMenuItem = forwardRef(({ className, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Item, { ref: ref, className: cn(
     // ``gap-2`` is the same icon-to-text spacing the framework's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-web-ui",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "MIT",
   "description": "React agent UI core for Foundry UI — chat, composer, AG-UI adapter for assistant-ui, tool cards, panels, sidebar, theme runtime, and UI stores.",
   "keywords": [
@@ -71,8 +71,8 @@
     "react-markdown": "^10.0.0",
     "remark-gfm": "^4.0.0",
     "tailwind-merge": "^3.5.0",
-    "@iloveagents/foundry-agent": "^0.18.0",
-    "@iloveagents/foundry-web-primitives": "^0.18.0"
+    "@iloveagents/foundry-agent": "^0.20.0",
+    "@iloveagents/foundry-web-primitives": "^0.20.0"
   },
   "devDependencies": {
     "@ag-ui/client": "^0.0.52",