Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

12.8 KB
Raw Blame
import { GO_TO_COMMAND_SCOPE, GO_TO_LEADER_KEY } from '@app/constants/hotkeys';
import { createHotkeyGroup, registerHotkey } from '@core/hotkey/hotkeys';
import { TOKENS } from '@core/hotkey/tokens';
import { isScopeInActiveBranch } from '@core/hotkey/utils';
import { type Accessor, onCleanup } from 'solid-js';
import type { ListController } from './create-list-controller';
import type { ListItemResult, ListNavigationOptions } from './types';

/** Minimal scrolling contract implemented by virtualized list handles. */
export type ListScrollHandle = {
  scrollToIndex: (
    index: number,
    options?: { align?: 'start' | 'center' | 'end' | 'nearest' }
  ) => void;
};

type ListInteractionConditions = Partial<
  Record<
    | 'move'
    | 'extendSelection'
    | 'open'
    | 'toggleSelection'
    | 'toggleAllVisible'
    | 'clearSelection'
    | 'disclosure',
    () => boolean
  >
>;

export type ListInteractionNavigation<TItem> = {
  /**
   * Return false to consume a move without changing focus.
   * Useful when a list must load more rows before crossing a boundary.
   */
  onBeforeMove?: (event: ListInteractionBeforeMoveEvent<TItem>) => boolean;
  move?: ListNavigationOptions<TItem>;
  first?: ListNavigationOptions<TItem>;
  last?: ListNavigationOptions<TItem>;
  extendSelection?: ListNavigationOptions<TItem>;
  onNavigate?: (event: ListInteractionNavigationEvent<TItem>) => void;
};

export type ListInteractionBeforeMoveEvent<TItem> = {
  direction: 1 | -1;
  current: ListItemResult<TItem> | undefined;
};

export type ListInteractionNavigationEvent<TItem> =
  | {
      kind: 'move';
      direction: 1 | -1;
      result: ListItemResult<TItem> | undefined;
    }
  | {
      kind: 'first' | 'last';
      result: ListItemResult<TItem> | undefined;
    };

export type ListInteractionActivationIntent = 'primary' | 'alternate';

export type ListInteractionActivation<TMetadata> = {
  /** Let a native control own its key event before document capture consumes it. */
  shouldHandleKeyEvent?: (event: KeyboardEvent | undefined) => boolean;
  createMetadata?: (intent: ListInteractionActivationIntent) => TMetadata;
  alternateDescription?: string;
};

export type ListInteractionDisclosure<TItem> = {
  /** H collapses only structural headers; entity rows keep their own actions. */
  isHeader: (item: TItem) => boolean;
  getKey: (item: TItem) => string | undefined;
  isExpanded: (key: string) => boolean;
  setExpanded: (key: string, expanded: boolean) => void;
  getFocusKey?: (key: string, item: TItem) => string | undefined;
};

export type UseListInteractionsOptions<TItem, TMetadata> = {
  controller: ListController<TItem, TMetadata>;
  scopeId: string;
  scrollHandle: Accessor<ListScrollHandle | undefined>;
  /** Optional view-level gate in addition to hotkey-scope ownership. */
  enabled?: () => boolean;
  conditions?: ListInteractionConditions;
  navigation?: ListInteractionNavigation<TItem>;
  activation?: ListInteractionActivation<TMetadata>;
  disclosure?: ListInteractionDisclosure<TItem>;
};

/**
 * Connects a headless list controller to standard navigation, range selection,
 * scrolling, activation, and hotkeys. Domain-specific row activation remains
 * on the controller supplied by the consuming view.
 */
export function useListInteractions<TItem, TMetadata = unknown>(
  options: UseListInteractionsOptions<TItem, TMetadata>
) {
  const list = options.controller;

  const canHandle = (condition?: () => boolean) =>
    (options.enabled?.() ?? true) && (condition?.() ?? true);

  const scrollFocusedIntoView = () => {
    const index = list.focus.index();
    if (index >= 0) {
      options.scrollHandle()?.scrollToIndex(index, { align: 'nearest' });
    }
  };

  const finishNavigation = (result: ListItemResult<TItem>) => {
    list.selection.setAnchor(result.key);
    scrollFocusedIntoView();
  };

  const move = (offset: 1 | -1) => {
    if (
      options.navigation?.onBeforeMove?.({
        direction: offset,
        current: list.focus.result(),
      }) === false
    ) {
      return true;
    }

    const result = list.navigate.by(offset, options.navigation?.move);
    options.navigation?.onNavigate?.({
      kind: 'move',
      direction: offset,
      result,
    });
    if (!result) return false;

    finishNavigation(result);
    return true;
  };

  const first = () => {
    const result = list.navigate.toFirst(options.navigation?.first);
    options.navigation?.onNavigate?.({ kind: 'first', result });
    if (!result) return false;

    finishNavigation(result);
    return true;
  };

  const last = () => {
    const result = list.navigate.toLast(options.navigation?.last);
    options.navigation?.onNavigate?.({ kind: 'last', result });
    if (!result) return false;

    finishNavigation(result);
    return true;
  };

  const selectionNavigationOptions = (): ListNavigationOptions<TItem> => {
    const configured = options.navigation?.extendSelection;
    return {
      ...configured,
      isNavigable: (item, index) => {
        const rowKey = list.items.keyOf(item);
        return (
          list.selection.isSelectable(rowKey) &&
          (configured?.isNavigable?.(item, index) ?? true)
        );
      },
    };
  };

  const extendSelection = (offset: 1 | -1) => {
    const currentKey = list.focus.key();
    if (currentKey === undefined) return false;

    if (!list.selection.isSelectable(currentKey)) {
      const firstSelectable = list.navigate.by(
        offset,
        selectionNavigationOptions()
      );
      if (!firstSelectable) return false;

      list.selection.set(firstSelectable.key, true);
      scrollFocusedIntoView();
      return true;
    }

    const anchor = list.selection.anchor();
    if (anchor === undefined || !list.selection.isSelectable(anchor)) {
      list.selection.setAnchor(currentKey);
    }

    const result = list.navigate.by(offset, selectionNavigationOptions());
    if (!result || !list.selection.extendRange(result.key, true)) return false;

    scrollFocusedIntoView();
    return true;
  };

  const toggleAllVisible = () => list.selection.toggleAllVisible();

  const clearSelection = () => list.selection.clear();

  const group = createHotkeyGroup();

  if (options.disclosure) {
    const disclosure = options.disclosure;
    const setExpanded = (expanded: boolean) => {
      const item = list.focus.item();
      if (item === undefined) return false;

      const key = disclosure.getKey(item);
      if (key === undefined || disclosure.isExpanded(key) === expanded) {
        return false;
      }

      disclosure.setExpanded(key, expanded);
      if (expanded) return true;

      const focusKey = disclosure.getFocusKey?.(key, item);
      if (focusKey === undefined) return true;

      list.focus.set(focusKey, { reason: 'keyboard' });
      scrollFocusedIntoView();
      return true;
    };

    registerHotkey({
      hotkey: ['h'],
      hotkeyToken: TOKENS.unifiedList.navigation.collapseGroup,
      scopeId: options.scopeId,
      description: 'Collapse group',
      condition: () => canHandle(options.conditions?.disclosure),
      keyDownHandler: () => {
        const item = list.focus.item();
        if (item === undefined || !disclosure.isHeader(item)) return false;
        setExpanded(false);
        return true;
      },
      registrationType: 'add',
      handlerPriority: 4,
      hide: true,
    }).withGroup(group);

    registerHotkey({
      hotkey: ['arrowleft'],
      hotkeyToken: TOKENS.unifiedList.navigation.parent,
      scopeId: options.scopeId,
      description: 'Collapse item',
      condition: () => canHandle(options.conditions?.disclosure),
      keyDownHandler: () => setExpanded(false),
      registrationType: 'add',
      handlerPriority: 4,
      hide: true,
    }).withGroup(group);

    registerHotkey({
      hotkey: ['l', 'arrowright'],
      hotkeyToken: TOKENS.unifiedList.navigation.child,
      scopeId: options.scopeId,
      description: 'Expand item',
      condition: () => canHandle(options.conditions?.disclosure),
      keyDownHandler: () => setExpanded(true),
      registrationType: 'add',
      handlerPriority: 4,
      hide: true,
    }).withGroup(group);
  }

  registerHotkey({
    hotkey: ['arrowdown', 'j'],
    hotkeyToken: TOKENS.entity.step.end,
    scopeId: options.scopeId,
    description: 'Move down',
    condition: () => canHandle(options.conditions?.move),
    hide: true,
    keyDownHandler: () => {
      move(1);
      return true;
    },
  }).withGroup(group);

  registerHotkey({
    hotkey: ['arrowup', 'k'],
    hotkeyToken: TOKENS.entity.step.start,
    scopeId: options.scopeId,
    description: 'Move up',
    condition: () => canHandle(options.conditions?.move),
    hide: true,
    keyDownHandler: () => {
      move(-1);
      return true;
    },
  }).withGroup(group);

  registerHotkey({
    hotkey: ['home', 'cmd+arrowup'],
    hotkeyToken: TOKENS.entity.jump.home,
    scopeId: options.scopeId,
    description: 'Go to first item',
    condition: () => canHandle(options.conditions?.move),
    hide: true,
    keyDownHandler: first,
  }).withGroup(group);

  registerHotkey({
    hotkey: GO_TO_LEADER_KEY,
    scopeId: GO_TO_COMMAND_SCOPE,
    description: 'Go to first item',
    condition: () =>
      canHandle(options.conditions?.move) &&
      isScopeInActiveBranch(options.scopeId),
    keyDownHandler: first,
    registrationType: 'add',
  }).withGroup(group);

  registerHotkey({
    hotkey: ['end', 'shift+g', 'cmd+arrowdown'],
    hotkeyToken: TOKENS.entity.jump.end,
    scopeId: options.scopeId,
    description: 'Go to last item',
    condition: () => canHandle(options.conditions?.move),
    hide: true,
    keyDownHandler: last,
  }).withGroup(group);

  registerHotkey({
    hotkey: ['shift+arrowdown', 'shift+j'],
    scopeId: options.scopeId,
    description: 'Extend selection down',
    condition: () => canHandle(options.conditions?.extendSelection),
    hide: true,
    keyDownHandler: () => {
      extendSelection(1);
      return true;
    },
  }).withGroup(group);

  registerHotkey({
    hotkey: ['shift+arrowup', 'shift+k'],
    scopeId: options.scopeId,
    description: 'Extend selection up',
    condition: () => canHandle(options.conditions?.extendSelection),
    hide: true,
    keyDownHandler: () => {
      extendSelection(-1);
      return true;
    },
  }).withGroup(group);

  const canOpen = () =>
    canHandle(options.conditions?.open) && list.focus.key() !== undefined;
  const open = (intent: ListInteractionActivationIntent) => {
    const metadata = options.activation?.createMetadata?.(intent);
    const activation = list.activate.current({
      reason: 'keyboard',
      ...(metadata === undefined ? {} : { metadata }),
    });
    return activation !== undefined;
  };

  registerHotkey({
    hotkey: 'enter',
    hotkeyToken: TOKENS.entity.open,
    scopeId: options.scopeId,
    description: 'Open item',
    condition: canOpen,
    keyDownHandler: (event) =>
      options.activation?.shouldHandleKeyEvent?.(event) === false
        ? false
        : open('primary'),
  }).withGroup(group);

  registerHotkey({
    hotkey: 'shift+enter',
    scopeId: options.scopeId,
    description:
      options.activation?.alternateDescription ?? 'Open item alternatively',
    condition: canOpen,
    hide: true,
    keyDownHandler: (event) =>
      options.activation?.shouldHandleKeyEvent?.(event) === false
        ? false
        : open('alternate'),
  }).withGroup(group);

  const canToggleSelection = () => {
    if (!canHandle(options.conditions?.toggleSelection)) return false;
    const key = list.focus.key();
    return key !== undefined && list.selection.isSelectable(key);
  };

  registerHotkey({
    hotkey: 'x',
    scopeId: options.scopeId,
    description: 'Toggle item selection',
    condition: canToggleSelection,
    keyDownHandler: () => {
      const key = list.focus.key();
      return key === undefined ? false : list.selection.toggle(key);
    },
  }).withGroup(group);

  registerHotkey({
    hotkey: 'cmd+a',
    scopeId: options.scopeId,
    description: 'Toggle all visible items',
    condition: () =>
      canHandle(options.conditions?.toggleAllVisible) &&
      list.selection.visibleKeys().size > 0,
    keyDownHandler: () => {
      toggleAllVisible();
      return true;
    },
  }).withGroup(group);

  registerHotkey({
    hotkey: 'escape',
    hotkeyToken: TOKENS.soup.dismiss,
    scopeId: options.scopeId,
    description: 'Clear selection',
    condition: () =>
      canHandle(options.conditions?.clearSelection) &&
      list.selection.count() > 0,
    keyDownHandler: () => {
      clearSelection();
      return true;
    },
    registrationType: 'add',
  }).withGroup(group);

  onCleanup(() => group.dispose());

  return {
    navigation: {
      move,
      first,
      last,
      scrollFocusedIntoView,
    },
    selection: {
      anchor: list.selection.anchor,
      set: list.selection.set,
      toggle: list.selection.toggle,
      extend: extendSelection,
      toggleAllVisible,
      clear: clearSelection,
      clearAnchor: list.selection.clearAnchor,
    },
  };
}