Skip to content

Papermark is the open-source DocSend alternative and secure data rooms with built-in analytics and custom domains.

11.7 KB
Raw Blame
import { ItemType } from "@prisma/client";

/**
 * Pure helpers for computing dataroom permission diffs from the in-memory tree
 * shown in the group-permissions UI. Extracted from
 * `components/datarooms/groups/group-permissions.tsx` so the parent-cascade
 * behaviour can be unit tested without React.
 *
 * The server (`/api/.../permissions`) still re-derives ancestors via a
 * recursive CTE as a safety net, but these helpers are what produce the
 * payload from a user toggle and what backs the optimistic UI.
 */

export const VIRTUAL_ROOT_ID = "__dataroom_root__";

export type TreeNodePermissions = {
  view: boolean;
  download: boolean;
};

export type TreeNode = {
  id: string;
  itemType: ItemType;
  permissions: TreeNodePermissions;
  subItems?: TreeNode[];
};

export type PermissionChange = {
  view: boolean;
  download: boolean;
  itemType: ItemType;
};

export type PermissionChanges = Record<string, PermissionChange>;

/**
 * Enforce the "download requires view" invariant. Mirrors the behaviour the
 * UI relied on inline before extraction.
 */
export function normalizePermissions(input: {
  view: boolean;
  download: boolean;
}): TreeNodePermissions {
  if (!input.view) {
    return { view: false, download: false };
  }
  return { view: true, download: input.download };
}

export function findItemAndParents(
  items: TreeNode[],
  targetId: string,
  parents: TreeNode[] = [],
): { item: TreeNode; parents: TreeNode[] } | null {
  for (const item of items) {
    if (item.id === targetId) {
      return { item, parents };
    }
    if (item.subItems) {
      const result = findItemAndParents(item.subItems, targetId, [
        ...parents,
        item,
      ]);
      if (result) return result;
    }
  }
  return null;
}

/**
 * Build the change set produced when the user toggles permissions on a single
 * item (folder or document). Cascades:
 *   - the item itself
 *   - all descendants (set to the new permission)
 *   - all ancestors:
 *       - if turning view/download ON: ancestors are forced visible (download
 *         only forced ON if the user explicitly turned download ON)
 *       - if turning view OFF: ancestors are recomputed from their *remaining*
 *         siblings (the toggled item is treated as if it already has the new
 *         permission). View AND download both get recomputed from siblings.
 *       - if turning download OFF while view stays on: ancestors keep their
 *         view=true but their download is recomputed from remaining
 *         siblings, so a folder whose only downloadable descendant just went
 *         away no longer has a stale `canDownload=true` row.
 *
 * The virtual `__dataroom_root__` node is never written to the DB.
 */
export function collectChangesForItem(
  item: TreeNode,
  parents: TreeNode[],
  rawPermissions: { view: boolean; download: boolean },
): PermissionChanges {
  const updated = normalizePermissions(rawPermissions);
  const changes: PermissionChanges = {};

  if (item.id !== VIRTUAL_ROOT_ID) {
    changes[item.id] = {
      view: updated.view,
      download: updated.download,
      itemType: item.itemType,
    };
  }

  const cascadeDown = (subItems: TreeNode[] | undefined) => {
    if (!subItems) return;
    for (const subItem of subItems) {
      if (subItem.id !== VIRTUAL_ROOT_ID) {
        changes[subItem.id] = {
          view: updated.view,
          download: updated.download,
          itemType: subItem.itemType,
        };
      }
      cascadeDown(subItem.subItems);
    }
  };
  cascadeDown(item.subItems);

  // Diff against the pre-toggle snapshot (the tree we were handed reflects
  // state *before* the user's click) so we can tell apart the three
  // ancestor-update modes below.
  const previousDownload = item.permissions.download;
  const downloadTurnedOff =
    previousDownload && !updated.download && updated.view;

  if (!updated.view) {
    // Turning view (and therefore download) off. Walk parents bottom-up and
    // recompute view+download from the remaining siblings.
    //
    // We track ancestors that have already flipped to view=false in this
    // pass so higher-level parents don't *still* see them as viewable in the
    // pre-toggle snapshot — otherwise a chain like `f1 > f1a > doc1` where
    // doc1 is the only viewable item would correctly flip f1a to invisible
    // but leave f1 visible (because f1a still has view=true in the snapshot
    // we hold by reference).
    const flippedToInvisible = new Set<string>([item.id]);
    for (const parent of [...parents].reverse()) {
      if (parent.id === VIRTUAL_ROOT_ID) continue;
      const otherChildren =
        parent.subItems?.filter(
          (sub) => !flippedToInvisible.has(sub.id),
        ) ?? [];
      const someSubItemViewable = otherChildren.some(
        (sub) => sub.permissions.view,
      );
      const someSubItemDownloadable = otherChildren.some(
        (sub) => sub.permissions.download,
      );
      changes[parent.id] = {
        view: someSubItemViewable,
        download: someSubItemDownloadable,
        itemType: parent.itemType,
      };
      if (!someSubItemViewable) {
        flippedToInvisible.add(parent.id);
      }
    }
  } else if (downloadTurnedOff) {
    // View stays on, download was just turned off. Walk parents bottom-up
    // and recompute download from the remaining siblings — same shape as
    // the view-off branch but only for the download flag. Without this, a
    // folder whose *only* downloadable descendant just got turned off
    // would silently keep `canDownload=true` in the DB, even though the
    // optimistic UI correctly shows it as no-longer-downloadable.
    const flippedToNonDownloadable = new Set<string>([item.id]);
    for (const parent of [...parents].reverse()) {
      if (parent.id === VIRTUAL_ROOT_ID) continue;
      const otherChildren =
        parent.subItems?.filter(
          (sub) => !flippedToNonDownloadable.has(sub.id),
        ) ?? [];
      const someSubItemDownloadable = otherChildren.some(
        (sub) => sub.permissions.download,
      );
      changes[parent.id] = {
        // The toggled item kept view=true, so by the "download requires
        // view" invariant every ancestor must have view=true too. We don't
        // need to recompute view here.
        view: true,
        download: someSubItemDownloadable,
        itemType: parent.itemType,
      };
      if (!someSubItemDownloadable) {
        flippedToNonDownloadable.add(parent.id);
      }
    }
  } else {
    // Turning view and/or download ON (or a no-op toggle). Force ancestors
    // visible; bump their download to true only when the user explicitly
    // turned download on, otherwise preserve their existing download flag
    // so we don't clobber an ancestor's previously-granted download grant.
    for (const parent of parents) {
      if (parent.id === VIRTUAL_ROOT_ID) continue;
      changes[parent.id] = {
        view: true,
        download: updated.download ? true : parent.permissions.download,
        itemType: parent.itemType,
      };
    }
  }

  return changes;
}

/**
 * Build the change set for a "set permissions on the virtual root" toggle.
 * Every real item in the tree gets the new permission. The virtual root is
 * never written to the DB.
 */
export function collectChangesForRoot(
  treeRootedAtVirtualRoot: TreeNode[],
  rawPermissions: { view: boolean; download: boolean },
): PermissionChanges {
  const updated = normalizePermissions(rawPermissions);
  const changes: PermissionChanges = {};

  const walk = (items: TreeNode[]) => {
    for (const item of items) {
      if (item.id !== VIRTUAL_ROOT_ID) {
        changes[item.id] = {
          view: updated.view,
          download: updated.download,
          itemType: item.itemType,
        };
      }
      if (item.subItems) walk(item.subItems);
    }
  };
  walk(treeRootedAtVirtualRoot);

  return changes;
}

/**
 * Translate a fresh `(view, download)` pair coming out of the multi-select
 * ToggleGroup in the group-permissions UI into the user's actual intent,
 * using the previous state to disambiguate which button they pressed.
 *
 * The "download requires view" invariant goes in two directions:
 *   - turning view OFF must also turn download OFF
 *   - turning download ON must also turn view ON (otherwise clicking the
 *     download icon on a hidden item is a no-op, which feels broken)
 *
 * Without comparing to the previous state we cannot tell a user *adding*
 * download from a user *removing* view: both can produce `["download"]`
 * from a multi-select toggle group.
 */
export function resolveToggleIntent(
  previous: { view: boolean; download: boolean },
  next: { view: boolean; download: boolean },
): { view: boolean; download: boolean } {
  const userTurnedViewOff = previous.view && !next.view;
  if (userTurnedViewOff) {
    return { view: false, download: false };
  }

  const userTurnedDownloadOn = !previous.download && next.download;
  if (userTurnedDownloadOn && !next.view) {
    return { view: true, download: true };
  }

  return next;
}

/**
 * Aggregate state for a folder row in the group-permissions UI: in addition
 * to the persisted `view`/`download` flags, the UI also renders an
 * "indeterminate" (gray) state when *some* but not *all* of the folder's
 * descendants are visible/downloadable.
 */
export type AggregatePermissions = {
  view: boolean;
  download: boolean;
  partialView: boolean;
  partialDownload: boolean;
};

/**
 * A child row's contribution to its parent folder's aggregate state. The
 * `partial*` flags are what let the indeterminate state propagate *up* the
 * tree: a folder is partial whenever any direct child is partial OR any
 * direct child is fully off, even if every direct child reports
 * `view=true` (because each of those children is itself partial).
 *
 * Without this, a folder like `Company Information` whose only-hidden item
 * is several levels deep would render as fully visible, because each of its
 * direct subfolders has `view=true` (they have *some* viewable descendant).
 */
export type AggregateChild = {
  view: boolean;
  download: boolean;
  partialView?: boolean;
  partialDownload?: boolean;
};

/**
 * Compute a folder's aggregate permission state from its direct children.
 * Returns `null` if there are no children (caller should fall back to the
 * folder's own persisted permissions).
 *
 * Rules:
 *  - `view` is true iff at least one direct child contributes view=true.
 *  - `partialView` is true iff `view` is true AND at least one direct child
 *    is either view=false or itself partial. The same holds for download.
 */
export function aggregateFolderPermissions(
  children: AggregateChild[],
): AggregatePermissions | null {
  if (children.length === 0) return null;

  const someViewable = children.some((c) => c.view);
  const allViewable = children.every((c) => c.view);
  const someChildPartialView = children.some((c) => c.partialView === true);

  const someDownloadable = children.some((c) => c.download);
  const allDownloadable = children.every((c) => c.download);
  const someChildPartialDownload = children.some(
    (c) => c.partialDownload === true,
  );

  return {
    view: someViewable,
    partialView: someViewable && (!allViewable || someChildPartialView),
    download: someDownloadable,
    partialDownload:
      someDownloadable && (!allDownloadable || someChildPartialDownload),
  };
}

/**
 * Returns the ids of all real ancestor folders of `targetId` in `tree`,
 * skipping the virtual root. Used to assert (in tests) that
 * `collectChangesForItem` includes a complete ancestor chain when toggling
 * a permission on.
 */
export function ancestorFolderIdsOf(
  tree: TreeNode[],
  targetId: string,
): string[] {
  const found = findItemAndParents(tree, targetId);
  if (!found) return [];
  return found.parents
    .filter((p) => p.id !== VIRTUAL_ROOT_ID)
    .map((p) => p.id);
}