@notis_ai/cli 0.2.18 → 0.2.19

package/{template/packages → dist}/sdk/src/hooks/useCollectionInteractions.ts

@@ -17,22 +17,23 @@ import {
 } from '../interactions/actions';
 import {
   activateShortcutCollection,
+  releaseShortcutCollection,
   createShortcutCollectionOwner,
   useShortcuts,
   type ShortcutDefinition,
   type ShortcutScope,
 } from '../interactions/shortcuts';
 
+import type { MultiSelectActionBarProps } from '../components/MultiSelectActionBar';
+import { isInteractionElementVisible } from '../interactions/visibility';
+import { useLongPressSelection } from './useLongPressSelection';
+import { useMarqueeSelection, type SelectionMarqueeRect } from './useMarqueeSelection';
+
 export const COLLECTION_ITEM_ATTRIBUTE = 'data-notis-collection-item-id';
 const LEGACY_ROW_ATTRIBUTE = 'data-notis-row-id';
 const INTERACTIVE_SELECTOR = 'button, a, input, textarea, select, [role="button"], [contenteditable]:not([contenteditable="false"])';
 
-export interface SelectionMarqueeRect {
-  left: number;
-  top: number;
-  width: number;
-  height: number;
-}
+export type { SelectionMarqueeRect };
 
 export type CollectionInteractionReason =
   | 'activate'
@@ -93,6 +94,8 @@ export interface UseCollectionInteractionsOptions<T> {
   enabled?: boolean;
   bindKeyboardShortcuts?: boolean;
   enableDragSelect?: boolean;
+  /** Touch-only long press; optional per view. */
+  enableLongPressSelection?: boolean;
   /** Plain item clicks activate the item and clear checkbox selection by default. */
   clearSelectionOnPlainClick?: boolean;
   dragThreshold?: number;
@@ -114,6 +117,7 @@ export interface CollectionInteractionController<T> {
   lastClickedId: string | null;
   dragRect: SelectionMarqueeRect | null;
   actions: ResolvedCollectionAction[];
+  getActionBarProps: () => Pick<MultiSelectActionBarProps, 'selectedCount' | 'actions' | 'collectionOwnerId' | 'isAvailable' | 'shortcutsEnabled' | 'onClearSelection'>;
 
   isSelected: (id: string) => boolean;
   getSelectedItems: () => T[];
@@ -128,7 +132,7 @@ export interface CollectionInteractionController<T> {
   onCheckboxClick: (id: string) => (event: ReactMouseEvent) => void;
   onRowMouseDown: (id: string) => (event: ReactMouseEvent) => void;
   getRowProps: (id: string) => Record<string, string>;
-  getItemProps: (id: string) => {
+  getItemProps: (id: string) => Partial<ReturnType<ReturnType<typeof useLongPressSelection>>> & {
     [COLLECTION_ITEM_ATTRIBUTE]: string;
     [LEGACY_ROW_ATTRIBUTE]: string;
     tabIndex: number;
@@ -185,13 +189,6 @@ function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
   return true;
 }
 
-function rectsIntersect(
-  a: { left: number; top: number; right: number; bottom: number },
-  b: { left: number; top: number; right: number; bottom: number },
-): boolean {
-  return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
-}
-
 export function useCollectionInteractions<T>(
   options: UseCollectionInteractionsOptions<T>,
 ): CollectionInteractionController<T> {
@@ -213,6 +210,7 @@ export function useCollectionInteractions<T>(
     enabled = true,
     bindKeyboardShortcuts = true,
     enableDragSelect = selectionMode === 'multiple',
+    enableLongPressSelection = false,
     clearSelectionOnPlainClick = true,
     dragThreshold = 5,
     shortcuts: shortcutOverrides,
@@ -233,13 +231,14 @@ export function useCollectionInteractions<T>(
     defaultAnchorId === undefined ? defaultActiveId : defaultAnchorId,
   );
   const anchorId = controlledAnchorId === undefined ? uncontrolledAnchorId : controlledAnchorId;
-  const [dragRect, setDragRect] = useState<SelectionMarqueeRect | null>(null);
 
   const itemsRef = useRef(items);
   const getIdRef = useRef(getId);
   const selectedIdsRef = useRef(selectedIds);
   const activeIdRef = useRef(activeId);
   const anchorIdRef = useRef(anchorId);
+  // Keep manually selected rows outside the current keyboard range on reversal.
+  const keyboardRangeBaseRef = useRef<Set<string> | null>(null);
   const onSelectionChangeRef = useRef(onSelectionChange);
   const onActiveIdChangeRef = useRef(onActiveIdChange);
   const onAnchorIdChangeRef = useRef(onAnchorIdChange);
@@ -247,6 +246,11 @@ export function useCollectionInteractions<T>(
   const onActivateRef = useRef(onActivate);
   const resolveNextIdRef = useRef(resolveNextId);
   const containerRef = useRef<HTMLElement | null>(null);
+  const [containerElement, setContainerElement] = useState<HTMLElement | null>(null);
+  const setContainerRef = useCallback((node: HTMLElement | null) => {
+    containerRef.current = node;
+    setContainerElement(node);
+  }, []);
   const shortcutCollectionOwnerRef = useRef<string | null>(null);
   if (!shortcutCollectionOwnerRef.current) {
     shortcutCollectionOwnerRef.current = createShortcutCollectionOwner();
@@ -254,6 +258,9 @@ export function useCollectionInteractions<T>(
 
   itemsRef.current = items;
   getIdRef.current = getId;
+  if (!setsEqual(selectedIdsRef.current, selectedIds) || anchorIdRef.current !== anchorId) {
+    keyboardRangeBaseRef.current = null;
+  }
   selectedIdsRef.current = selectedIds;
   activeIdRef.current = activeId;
   anchorIdRef.current = anchorId;
@@ -316,6 +323,7 @@ export function useCollectionInteractions<T>(
   const activate = useCallback((id: string) => {
     const item = itemsRef.current.find((candidate) => getIdRef.current(candidate) === id);
     if (!item || !selectableIdsRef.current.includes(id)) return;
+    keyboardRangeBaseRef.current = null;
     setActive(id, 'activate');
     setAnchor(id, 'activate');
     onActivateRef.current?.(item, id);
@@ -323,6 +331,7 @@ export function useCollectionInteractions<T>(
 
   const toggle = useCallback((id: string) => {
     if (selectionMode === 'none' || !selectableIdsRef.current.includes(id)) return;
+    keyboardRangeBaseRef.current = null;
     const next = new Set(selectedIdsRef.current);
     if (next.has(id)) next.delete(id);
     else {
@@ -334,6 +343,7 @@ export function useCollectionInteractions<T>(
   }, [commitSelection, selectionMode, setAnchor]);
 
   const select = useCallback((ids: string[]) => {
+    keyboardRangeBaseRef.current = null;
     const next = new Set(ids);
     const last = ids[ids.length - 1] ?? null;
     setAnchor(last, 'toggle');
@@ -341,12 +351,14 @@ export function useCollectionInteractions<T>(
   }, [commitSelection, setAnchor]);
 
   const clear = useCallback(() => {
+    keyboardRangeBaseRef.current = null;
     setAnchor(null, 'clear');
     commitSelection(new Set(), 'clear');
   }, [commitSelection, setAnchor]);
 
   const selectAll = useCallback(() => {
     if (selectionMode === 'none') return;
+    keyboardRangeBaseRef.current = null;
     const ids = selectionMode === 'single' ? selectableIdsRef.current.slice(0, 1) : selectableIdsRef.current;
     const last = ids[ids.length - 1] ?? null;
     setAnchor(last, 'select-all');
@@ -361,12 +373,16 @@ export function useCollectionInteractions<T>(
       commitSelection(new Set([toId]), reason);
       return;
     }
-    commitSelection(new Set(ids.slice(Math.min(from, to), Math.max(from, to) + 1)), reason);
+    commitSelection(new Set([
+      ...(keyboardRangeBaseRef.current ?? []),
+      ...ids.slice(Math.min(from, to), Math.max(from, to) + 1),
+    ]), reason);
   }, [commitSelection]);
 
   const selectRange = useCallback((fromId: string, toId: string) => {
     const ids = selectableIdsRef.current;
     if (selectionMode === 'none' || !ids.includes(toId)) return;
+    keyboardRangeBaseRef.current = null;
     const resolvedFromId = ids.includes(fromId)
       ? fromId
       : activeIdRef.current && ids.includes(activeIdRef.current)
@@ -390,6 +406,9 @@ export function useCollectionInteractions<T>(
 
   useEffect(() => {
     const allowed = new Set(selectableIds);
+    if (keyboardRangeBaseRef.current) {
+      keyboardRangeBaseRef.current = new Set(Array.from(keyboardRangeBaseRef.current).filter((id) => allowed.has(id)));
+    }
     const pruned = new Set(Array.from(selectedIdsRef.current).filter((id) => allowed.has(id)));
     if (!setsEqual(pruned, selectedIdsRef.current)) commitSelection(pruned, 'items-changed');
     if (activeIdRef.current && !allowed.has(activeIdRef.current)) setActive(null, 'items-changed');
@@ -398,11 +417,39 @@ export function useCollectionInteractions<T>(
     }
   }, [commitSelection, selectableIds, setActive, setAnchor]);
 
+  const focusItem = useCallback((id: string) => {
+    const nodes = containerRef.current?.querySelectorAll<HTMLElement>(`[${COLLECTION_ITEM_ATTRIBUTE}]`);
+    const node = nodes ? Array.from(nodes).find(
+      (candidate) => candidate.getAttribute(COLLECTION_ITEM_ATTRIBUTE) === id && isInteractionElementVisible(candidate),
+    ) : null;
+    node?.focus({ preventScroll: true });
+    node?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+  }, []);
+
+  const focusPointerItem = useCallback((id: string) => {
+    setActive(id, 'activate');
+    focusItem(id);
+  }, [focusItem, setActive]);
+
+  const selectPointerRange = useCallback((id: string) => {
+    const rangeAnchor = anchorIdRef.current ?? activeIdRef.current ?? id;
+    const ids = selectableIdsRef.current;
+    const from = ids.indexOf(rangeAnchor);
+    const to = ids.indexOf(id);
+    const range = new Set(ids.slice(Math.min(from, to), Math.max(from, to) + 1));
+    const base = keyboardRangeBaseRef.current ?? new Set(Array.from(selectedIdsRef.current).filter((selected) => !range.has(selected)));
+    keyboardRangeBaseRef.current = base;
+    setAnchor(rangeAnchor, 'range');
+    replaceRange(rangeAnchor, id, 'range');
+    focusPointerItem(id);
+  }, [focusPointerItem, replaceRange, setAnchor]);
+
   const moveActive = useCallback((direction: CollectionNavigationDirection, extend = false) => {
     const ids = selectableIdsRef.current;
     if (ids.length === 0) return;
     const current = activeIdRef.current;
-    let next = resolveNextIdRef.current?.({
+    // Range gestures follow the displayed order, independent of asymmetric grid geometry.
+    let next = extend ? null : resolveNextIdRef.current?.({
       direction,
       currentId: current,
       items: itemsRef.current,
@@ -419,23 +466,21 @@ export function useCollectionInteractions<T>(
     if (!next || next === current) return;
     const stableAnchor = anchorIdRef.current ?? current ?? next;
     if (extend) {
+      keyboardRangeBaseRef.current ??= new Set(
+        Array.from(selectedIdsRef.current).filter((id) => id !== stableAnchor),
+      );
       if (!anchorIdRef.current) {
         setAnchor(stableAnchor, 'range');
       }
       replaceRange(stableAnchor, next, 'range');
     } else {
+      keyboardRangeBaseRef.current = new Set();
       setAnchor(next, 'navigate');
     }
     setActive(next, extend ? 'range' : 'navigate');
     const nextId = next;
-    requestAnimationFrame(() => {
-      const nodes = containerRef.current?.querySelectorAll<HTMLElement>(`[${COLLECTION_ITEM_ATTRIBUTE}]`);
-      const node = nodes ? Array.from(nodes).find(
-        (candidate) => candidate.getAttribute(COLLECTION_ITEM_ATTRIBUTE) === nextId,
-      ) : null;
-      node?.focus({ preventScroll: true });
-    });
-  }, [replaceRange, setActive, setAnchor]);
+    requestAnimationFrame(() => focusItem(nextId));
+  }, [focusItem, replaceRange, setActive, setAnchor]);
 
   const keyboard = useMemo<CollectionKeyboardShortcuts>(
     () => ({ ...DEFAULT_SHORTCUTS, ...(shortcutOverrides || {}) }),
@@ -456,7 +501,9 @@ export function useCollectionInteractions<T>(
     const extendDown = filterShortcutKeys(keyboard.extendNext, (key) => !key.toLowerCase().endsWith('arrowright'));
     const extendLeft = filterShortcutKeys(keyboard.extendPrevious, (key) => key.toLowerCase().endsWith('arrowleft'));
     const extendUp = filterShortcutKeys(keyboard.extendPrevious, (key) => !key.toLowerCase().endsWith('arrowleft'));
-    add('collection.clear', 'Clear selection', keyboard.clear, clear);
+    // An empty collection has nothing to dismiss. Let the enclosing surface
+    // own Escape (for example Desktop's final Inbox navigation layer).
+    add('collection.clear', 'Clear selection', selectedIds.size > 0 ? keyboard.clear : false, clear);
     add('collection.select-all', 'Select all visible items', selectionMode === 'none' ? false : keyboard.selectAll, selectAll);
     add('collection.toggle', 'Toggle active item', selectionMode === 'none' ? false : keyboard.toggle, () => {
       const id = activeIdRef.current ?? anchorIdRef.current;
@@ -477,124 +524,52 @@ export function useCollectionInteractions<T>(
       if (id) activate(id);
     });
     return definitions;
-  }, [activate, clear, keyboard, moveActive, selectAll, selectionMode, toggle]);
+  }, [activate, clear, keyboard, moveActive, selectAll, selectedIds.size, selectionMode, toggle]);
+  const isAvailable = useCallback(() => isInteractionElementVisible(containerRef.current), []);
+  useEffect(() => {
+    const owner = shortcutCollectionOwnerRef.current!;
+    const container = containerElement;
+    const Observer = container?.ownerDocument.defaultView?.MutationObserver;
+    const observer = Observer ? new Observer(() => {
+      if (!isAvailable()) releaseShortcutCollection(owner);
+    }) : null;
+    let element: Element | null = container;
+    while (element) {
+      observer?.observe(element, { attributes: true, attributeFilter: ['hidden', 'inert', 'aria-hidden', 'style', 'class'] });
+      const root: Node = element.getRootNode();
+      element = element.parentElement ?? ('host' in root ? (root as ShadowRoot).host : null);
+    }
+    return () => { observer?.disconnect(); releaseShortcutCollection(owner); };
+  }, [containerElement, isAvailable]);
+
   useShortcuts(keyDefinitions, {
     enabled: enabled && bindKeyboardShortcuts,
     scope: shortcutScope,
     priority: shortcutPriority,
     collectionOwnerId: shortcutCollectionOwnerRef.current,
+    isAvailable,
   });
 
   const activateCollectionShortcuts = useCallback(() => {
     activateShortcutCollection(shortcutCollectionOwnerRef.current!);
   }, []);
 
-  const dragPendingRef = useRef(false);
-  const dragActiveRef = useRef(false);
-  const dragStartRef = useRef({ x: 0, y: 0 });
-  const dragCurrentRef = useRef({ x: 0, y: 0 });
-  const clickShouldClearRef = useRef(false);
-  const suppressNextClickRef = useRef(false);
-
-  const armSuppressNextClick = useCallback(() => {
-    suppressNextClickRef.current = true;
-    setTimeout(() => { suppressNextClickRef.current = false; }, 0);
-  }, []);
-
-  const computeDragRect = useCallback((): SelectionMarqueeRect => ({
-    left: Math.min(dragStartRef.current.x, dragCurrentRef.current.x),
-    top: Math.min(dragStartRef.current.y, dragCurrentRef.current.y),
-    width: Math.abs(dragCurrentRef.current.x - dragStartRef.current.x),
-    height: Math.abs(dragCurrentRef.current.y - dragStartRef.current.y),
-  }), []);
-
-  const computeIntersectingIds = useCallback((rect: {
-    left: number; top: number; right: number; bottom: number;
-  }) => {
-    const nodes = containerRef.current?.querySelectorAll<HTMLElement>(`[${COLLECTION_ITEM_ATTRIBUTE}]`);
-    if (!nodes) return [];
-    const ids: string[] = [];
-    nodes.forEach((node) => {
-      if (!rectsIntersect(rect, node.getBoundingClientRect())) return;
-      const id = node.getAttribute(COLLECTION_ITEM_ATTRIBUTE);
-      if (id && selectableIdsRef.current.includes(id)) ids.push(id);
-    });
-    return ids;
-  }, []);
-
-  const handleContainerMouseDown = useCallback((event: ReactMouseEvent) => {
-    if (!enabled || event.button !== 0) return;
-    const target = event.target as HTMLElement | null;
-    if (!target) return;
-    const itemTarget = target.closest(`[${COLLECTION_ITEM_ATTRIBUTE}]`);
-    const interactiveTarget = target.closest(INTERACTIVE_SELECTOR);
-    if (interactiveTarget && interactiveTarget !== itemTarget) {
-      clickShouldClearRef.current = false;
-      return;
-    }
-    clickShouldClearRef.current = !itemTarget;
-    if (itemTarget) return;
-    if (!enableDragSelect || selectionMode !== 'multiple') return;
-    dragPendingRef.current = true;
-    dragStartRef.current = { x: event.clientX, y: event.clientY };
-    dragCurrentRef.current = { x: event.clientX, y: event.clientY };
-  }, [enableDragSelect, enabled, selectionMode]);
-
-  const handleContainerClickCapture = useCallback((event: ReactMouseEvent) => {
-    if (!suppressNextClickRef.current) return;
-    suppressNextClickRef.current = false;
-    event.preventDefault();
-    event.stopPropagation();
-  }, []);
-
-  useEffect(() => {
-    if (!enabled || !enableDragSelect || selectionMode !== 'multiple') return;
-    const handleMouseMove = (event: MouseEvent) => {
-      if (dragPendingRef.current) {
-        const dx = event.clientX - dragStartRef.current.x;
-        const dy = event.clientY - dragStartRef.current.y;
-        if (Math.abs(dx) > dragThreshold || Math.abs(dy) > dragThreshold) {
-          dragPendingRef.current = false;
-          dragActiveRef.current = true;
-          window.getSelection()?.removeAllRanges();
-        } else return;
-      }
-      if (!dragActiveRef.current) return;
-      event.preventDefault();
-      dragCurrentRef.current = { x: event.clientX, y: event.clientY };
-      const rect = computeDragRect();
-      setDragRect(rect);
-      const ids = computeIntersectingIds({
-        left: rect.left,
-        top: rect.top,
-        right: rect.left + rect.width,
-        bottom: rect.top + rect.height,
-      });
+  // The marquee (drag from empty space) is the shared one the toolkit list uses too.
+  const marquee = useMarqueeSelection({
+    enabled: enabled && enableDragSelect && selectionMode === 'multiple',
+    itemAttribute: COLLECTION_ITEM_ATTRIBUTE,
+    isSelectable: (id) => selectableIdsRef.current.includes(id),
+    onSelect: (ids) => {
       commitSelection(new Set(ids), 'drag');
       const last = ids[ids.length - 1] ?? null;
       setAnchor(last, 'drag');
-    };
-    const handleMouseUp = () => {
-      const wasPending = dragPendingRef.current;
-      const wasActive = dragActiveRef.current;
-      dragPendingRef.current = false;
-      dragActiveRef.current = false;
-      if (wasActive) {
-        setDragRect(null);
-        clickShouldClearRef.current = false;
-        armSuppressNextClick();
-      } else if (wasPending && clickShouldClearRef.current) {
-        clickShouldClearRef.current = false;
-        clear();
-      }
-    };
-    document.addEventListener('mousemove', handleMouseMove);
-    document.addEventListener('mouseup', handleMouseUp);
-    return () => {
-      document.removeEventListener('mousemove', handleMouseMove);
-      document.removeEventListener('mouseup', handleMouseUp);
-    };
-  }, [armSuppressNextClick, clear, commitSelection, computeDragRect, computeIntersectingIds, dragThreshold, enableDragSelect, enabled, selectionMode, setAnchor]);
+    },
+    onClear: clear,
+    threshold: dragThreshold,
+    interactiveSelector: INTERACTIVE_SELECTOR,
+  });
+  const dragRect = marquee.rect;
+  const { armSuppressNextClick, onMouseDown: handleContainerMouseDown, onClickCapture: handleContainerClickCapture } = marquee;
 
   const onRowMouseDown = useCallback((id: string) => (event: ReactMouseEvent) => {
     if (!enabled || event.button !== 0 || event.shiftKey || !(event.metaKey || event.ctrlKey)) return;
@@ -604,23 +579,34 @@ export function useCollectionInteractions<T>(
     event.preventDefault();
     event.stopPropagation();
     toggle(id);
+    focusPointerItem(id);
     armSuppressNextClick();
-  }, [armSuppressNextClick, enabled, toggle]);
+  }, [armSuppressNextClick, enabled, focusPointerItem, toggle]);
 
   const onCheckboxClick = useCallback((id: string) => (event: ReactMouseEvent) => {
     event.stopPropagation();
+    if (!enabled) return;
     if (event.shiftKey && selectionMode === 'multiple') {
-      const rangeAnchor = anchorIdRef.current ?? activeIdRef.current ?? id;
-      selectRange(rangeAnchor, id);
-    } else toggle(id);
-  }, [selectRange, selectionMode, toggle]);
+      selectPointerRange(id);
+    } else {
+      toggle(id);
+      focusPointerItem(id);
+    }
+  }, [enabled, focusPointerItem, selectPointerRange, selectionMode, toggle]);
 
   const getRowProps = useCallback((id: string) => ({
     [COLLECTION_ITEM_ATTRIBUTE]: id,
     [LEGACY_ROW_ATTRIBUTE]: id,
   }), []);
 
+  const longPress = useLongPressSelection((id) => {
+    if (!enabled || selectionMode === 'none') return;
+    activateCollectionShortcuts();
+    toggle(id);
+    focusPointerItem(id);
+  });
   const getItemProps = useCallback((id: string) => ({
+    ...(enableLongPressSelection ? longPress(id) : {}),
     [COLLECTION_ITEM_ATTRIBUTE]: id,
     [LEGACY_ROW_ATTRIBUTE]: id,
     tabIndex: activeIdRef.current === id || (!activeIdRef.current && selectableIdsRef.current[0] === id) ? 0 : -1,
@@ -633,15 +619,14 @@ export function useCollectionInteractions<T>(
     },
     onMouseDown: onRowMouseDown(id),
     onClick: (event: ReactMouseEvent) => {
-      if (event.defaultPrevented) return;
+      if (!enabled || event.defaultPrevented) return;
       if (!selectableIdsRef.current.includes(id)) return;
       const target = event.target as HTMLElement | null;
       const interactiveTarget = target?.closest(INTERACTIVE_SELECTOR);
       if (interactiveTarget && interactiveTarget !== event.currentTarget) return;
       if (event.shiftKey && selectionMode === 'multiple') {
         event.preventDefault();
-        const rangeAnchor = anchorIdRef.current ?? activeIdRef.current ?? id;
-        selectRange(rangeAnchor, id);
+        selectPointerRange(id);
         return;
       }
       if (event.metaKey || event.ctrlKey) return;
@@ -649,19 +634,19 @@ export function useCollectionInteractions<T>(
       activate(id);
     },
     onKeyDown: (event: ReactKeyboardEvent) => {
-      if (event.key !== ' ' || event.metaKey || event.ctrlKey || event.altKey) return;
+      if (!enabled || event.key !== ' ' || event.metaKey || event.ctrlKey || event.altKey) return;
       if (event.target !== event.currentTarget) return;
       event.preventDefault();
       if (selectionMode === 'none') activate(id);
       else toggle(id);
     },
-  }), [activate, activateCollectionShortcuts, clear, clearSelectionOnPlainClick, onRowMouseDown, selectRange, selectionMode, setActive, toggle]);
+  }), [activate, activateCollectionShortcuts, clear, clearSelectionOnPlainClick, enabled, enableLongPressSelection, longPress, onRowMouseDown, selectPointerRange, selectionMode, setActive, toggle]);
 
   const getCheckboxProps = useCallback((id: string) => ({
     isSelected: selectedIdsRef.current.has(id),
-    disabled: !selectableIdsRef.current.includes(id),
+    disabled: !enabled || !selectableIdsRef.current.includes(id),
     onClick: onCheckboxClick(id),
-  }), [onCheckboxClick]);
+  }), [enabled, onCheckboxClick]);
 
   const getSelectedItems = useCallback(() => getItemsForIds(selectedIdsRef.current), [getItemsForIds]);
   const isSelected = useCallback((id: string) => selectedIds.has(id), [selectedIds]);
@@ -681,14 +666,38 @@ export function useCollectionInteractions<T>(
       icon: action.icon,
       shortcut,
       destructive: action.destructive ?? action.intent === 'delete',
-      disabled,
+      disabled: !enabled || disabled,
       pending: action.pending,
-      onRun: () => action.onRun(actionContext),
+      onRun: () => { if (!enabled || disabled || action.pending) return; return action.onRun(actionContext); },
     };
-  }), [actionContext, actionDefinitions]);
+  }), [actionContext, actionDefinitions, enabled]);
+
+  // Optimistic filtering can remove the last selected row before a request settles.
+  // Keep pending keys on the visible controller, independently of toolbar mounting.
+  useShortcuts(resolvedActions.flatMap((action): ShortcutDefinition[] => (
+    action.shortcut && (action.pending || action.disabled)
+      ? [{ id: `collection.pending.${action.id}`, keys: action.shortcut, allowRepeat: true, onTrigger: () => undefined }]
+      : []
+  )), {
+    enabled: bindKeyboardShortcuts && resolvedActions.some((action) => action.pending),
+    scope: shortcutScope,
+    priority: shortcutPriority + 25,
+    collectionOwnerId: shortcutCollectionOwnerRef.current!,
+    isAvailable,
+  });
+
+  const getActionBarProps = useCallback(() => ({
+    selectedCount: selectedIds.size,
+    actions: resolvedActions,
+    collectionOwnerId: shortcutCollectionOwnerRef.current!,
+    isAvailable,
+    // Pending work may disable collection gestures but must retain its action keys.
+    shortcutsEnabled: bindKeyboardShortcuts && (enabled || resolvedActions.some((action) => action.pending)),
+    onClearSelection: enabled ? clear : undefined,
+  }), [selectedIds.size, resolvedActions, isAvailable, enabled, bindKeyboardShortcuts, clear]);
 
   const getContainerProps = useCallback(() => ({
-    ref: (node: HTMLElement | null) => { containerRef.current = node; },
+    ref: setContainerRef,
     onMouseDown: (event: ReactMouseEvent) => {
       activateCollectionShortcuts();
       handleContainerMouseDown(event);
@@ -696,7 +705,7 @@ export function useCollectionInteractions<T>(
     onFocusCapture: activateCollectionShortcuts,
     onClickCapture: handleContainerClickCapture,
     style: { userSelect: 'none' as const },
-  }), [activateCollectionShortcuts, handleContainerClickCapture, handleContainerMouseDown]);
+  }), [activateCollectionShortcuts, handleContainerClickCapture, handleContainerMouseDown, setContainerRef]);
 
   return {
     selectedIds,
@@ -707,6 +716,7 @@ export function useCollectionInteractions<T>(
     lastClickedId: anchorId,
     dragRect,
     actions: resolvedActions,
+    getActionBarProps,
     isSelected,
     getSelectedItems,
     setActive,

package/dist/sdk/src/hooks/useDatabaseSchema.ts

@@ -0,0 +1,50 @@
+'use client';
+
+import { useQuery } from './useQuery';
+import { useNotisRuntime } from '../provider';
+import { normalizeDatabaseProperty, optionalString } from '../documents';
+import type { DatabaseProperty } from '../runtime';
+
+interface GetDatabaseResult {
+  database?: {
+    name?: string;
+    description?: string | null;
+    schema?: {
+      properties?: unknown[];
+    };
+  };
+  message?: string;
+  error?: string;
+}
+
+export interface UseDatabaseSchemaResult {
+  name: string | null;
+  description: string | null;
+  properties: DatabaseProperty[];
+  loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
+  error: Error | null;
+  /** Reads again; resolves to the read's error, or null when it succeeded. */
+  refetch: () => Promise<Error | null>;
+}
+
+/** Fetch a database's schema (normalized properties + metadata). */
+export function useDatabaseSchema(databaseSlug: string): UseDatabaseSchemaResult {
+  const runtime = useNotisRuntime();
+  const query = useQuery(['database-schema', databaseSlug], async () => {
+    const result = await runtime!.callTool<GetDatabaseResult>('LOCAL_NOTIS_DATABASE_GET_DATABASE', {
+      database_slug: databaseSlug,
+    }, { dedupe: true, readOnly: true });
+    if (!result.database) throw new Error(result.error || result.message || 'Database not found');
+    return {
+      name: optionalString(result.database.name),
+      description: optionalString(result.database.description),
+      properties: (result.database.schema?.properties ?? []).map(normalizeDatabaseProperty)
+        .filter((property): property is DatabaseProperty => Boolean(property)),
+    };
+  }, { readOnly: true });
+  return { ...query, name: query.data?.name ?? null, description: query.data?.description ?? null,
+    properties: query.data?.properties ?? EMPTY_PROPERTIES };
+}
+const EMPTY_PROPERTIES: DatabaseProperty[] = [];

package/{template/packages → dist}/sdk/src/hooks/useDatabaseSubscription.ts

@@ -36,7 +36,7 @@ export function useDatabaseSubscription(
 ): UseDatabaseSubscriptionResult {
   const runtime = useNotisRuntime();
   const { subscribe = true, ...documentOptions } = options;
-  const { documents, loading, error, refetch } = useDocuments(databaseSlug, documentOptions);
+  const { documents, loading, isFetching, hasData, error, refetch } = useDocuments(databaseSlug, documentOptions);
   const [live, setLive] = useState(false);
 
   const refetchRef = useRef(refetch);
@@ -72,5 +72,5 @@ export function useDatabaseSubscription(
     };
   }, [runtime, databaseSlug, enabled]);
 
-  return { documents, rows: documents, loading, error, refetch, live };
+  return { documents, rows: documents, loading, isFetching, hasData, error, refetch, live };
 }

package/dist/sdk/src/hooks/useDocument.ts

@@ -0,0 +1,51 @@
+'use client';
+
+import { useQuery } from './useQuery';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord } from '../runtime';
+import { pick, type Words } from '../words/types';
+
+/** The words of the document hook's own failures, in English and French (C8). */
+export const DOCUMENT_HOOK_WORDS = Object.freeze({
+  notFound: { en: 'Document not found', fr: 'Document introuvable' },
+}) satisfies Readonly<Record<string, Words>>;
+
+interface GetDocumentResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseDocumentOptions {
+  enabled?: boolean;
+}
+
+export interface UseDocumentResult {
+  document: DocumentRecord | null;
+  loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
+  error: Error | null;
+  /** Reads again; resolves to the read's error, or null when it succeeded. */
+  refetch: () => Promise<Error | null>;
+}
+
+/** Fetch a single document (with content) by id, normalized. */
+export function useDocument(
+  documentId: string | null | undefined,
+  options: UseDocumentOptions = {},
+): UseDocumentResult {
+  const runtime = useNotisRuntime();
+  const locale = runtime?.context?.locale === 'fr' ? 'fr' : 'en';
+  const query = useQuery<DocumentRecord>(['document', documentId ?? null, locale], async () => {
+    if (!runtime || !documentId) throw new Error(pick(DOCUMENT_HOOK_WORDS.notFound, locale));
+    const result = await runtime.callTool<GetDocumentResult>('LOCAL_NOTIS_DATABASE_GET_DOCUMENT', {
+      document_id: documentId,
+    }, { dedupe: true, readOnly: true });
+    if (!result.document) throw new Error(result.error ?? result.message ?? pick(DOCUMENT_HOOK_WORDS.notFound, locale));
+    return normalizeDocumentRecord(result.document, { locale });
+  }, { readOnly: true, enabled: options.enabled !== false && Boolean(documentId) });
+  return { document: query.data ?? null, loading: query.loading, isFetching: query.isFetching, hasData: query.hasData, error: query.error, refetch: query.refetch };
+}