Skip to content

Virtual whiteboard for sketching hand-drawn like diagrams

29.3 KB
Raw Blame
import {
  DEFAULT_ELEMENT_PROPS,
  DEFAULT_STICKY_NOTE_BG,
  MIN_FONT_SIZE,
  arrayToMap,
  STICKY_NOTE_BODY_INSET_Y,
  STICKY_NOTE_FALLBACK_FONT_SIZE,
  STICKY_NOTE_FOOTER,
  STICKY_NOTE_FONT_STEP,
  STICKY_NOTE_MAX_FONT_SIZE,
  STICKY_NOTE_MIN_SIZE,
  STICKY_NOTE_MIN_FONT_SIZE,
  STICKY_NOTE_PADDING,
  STICKY_NOTE_SHADOW_OFFSET,
  getFontString,
  getLineHeight,
  isTransparent,
  seededRandom,
} from "@excalidraw/common";

import { clamp } from "@excalidraw/math";

import { updateBoundElements } from "./binding";
import { newElementWith } from "./mutateElement";
import { getPositionAfterHeightChange } from "./sizeHelpers";
import { computeBoundTextPosition, getBoundTextElement } from "./textElement";
import { measureText } from "./textMeasurements";
import { wrapText } from "./textWrapping";
import { isStickyNoteElement, isTextElement } from "./typeChecks";

import type { RenderEnvironment } from "./renderEnvironment";
import type { Scene } from "./Scene";
import type { VerticalResizeAnchor } from "./sizeHelpers";
import type { TransformHandleDirection } from "./transformHandles";
import type {
  ElementsMap,
  ExcalidrawElement,
  ExcalidrawStickyNoteElement,
  ExcalidrawTextElement,
  ExcalidrawTextElementWithContainer,
  NonDeletedExcalidrawElement,
} from "./types";

export type StickyNoteRenderPoint = {
  x: number;
  y: number;
};

export type StickyNotePathCommand =
  | {
      type: "move";
      point: StickyNoteRenderPoint;
    }
  | {
      type: "line";
      point: StickyNoteRenderPoint;
    }
  | {
      type: "quadratic";
      control: StickyNoteRenderPoint;
      point: StickyNoteRenderPoint;
    };

const STICKY_NOTE_RENDER_ROUGHNESS = [0, 1.5, 8] as const;
const STICKY_NOTE_CORNER_RADIUS_RATIO = 0.04;
const STICKY_NOTE_MAX_CORNER_RADIUS = 16;

export const normalizeStickyNoteStrokeColor = (
  strokeColor: string | null | undefined,
) => {
  return !strokeColor || isTransparent(strokeColor)
    ? DEFAULT_ELEMENT_PROPS.strokeColor
    : strokeColor;
};

export const normalizeStickyNoteBackgroundColor = (
  backgroundColor: string | null | undefined,
) => {
  return !backgroundColor || isTransparent(backgroundColor)
    ? DEFAULT_STICKY_NOTE_BG
    : backgroundColor;
};

/**
 * The update that applies a picked color to an element under the sticky
 * note policy: a note is always filled and its label — the visible text,
 * which the note's own `strokeColor` seeds — never goes transparent. Every
 * color surface (actions, both eyedroppers, paste styles, bind) routes
 * through this instead of re-deriving the rule.
 */
/**
 * The element a color pick on `element` lands on. A note's label has no fill
 * of its own, so a background pick on the label — the styles panel while
 * editing it — goes to the note; everything else colors itself.
 */
export const getColorTargetElement = (
  element: ExcalidrawElement,
  property: "strokeColor" | "backgroundColor",
  elementsMap: ElementsMap,
): ExcalidrawElement => {
  if (
    property === "backgroundColor" &&
    isTextElement(element) &&
    isStickyNoteBoundText(element, elementsMap)
  ) {
    return elementsMap.get(element.containerId!) ?? element;
  }
  return element;
};

export const getColorUpdate = (
  element: ExcalidrawElement,
  property: "strokeColor" | "backgroundColor",
  color: string,
  elementsMap: ElementsMap,
): { strokeColor: string } | { backgroundColor: string } => {
  if (isStickyNoteElement(element)) {
    return property === "backgroundColor"
      ? { backgroundColor: normalizeStickyNoteBackgroundColor(color) }
      : { strokeColor: normalizeStickyNoteStrokeColor(color) };
  }
  if (
    property === "strokeColor" &&
    isTextElement(element) &&
    isStickyNoteBoundText(element, elementsMap)
  ) {
    const container = elementsMap.get(element.containerId!);
    return {
      strokeColor: isTransparent(color)
        ? normalizeStickyNoteStrokeColor(container?.strokeColor)
        : color,
    };
  }
  return property === "backgroundColor"
    ? { backgroundColor: color }
    : { strokeColor: color };
};

/**
 * A note's ink is one color: the container's `strokeColor` — the seed for a
 * new label and what the creation-date footer paints with — and its label's.
 * Run after a property write to copy the side that changed onto the other;
 * when both changed, or neither (data that drifted), the label wins: it is
 * the text the user styled. A transparent label always takes the note's
 * color. Returns the same array when nothing needs to change.
 */
export const syncStickyNoteInk = <T extends ExcalidrawElement>(
  elements: readonly T[],
  prevElementsMap: ElementsMap,
): readonly T[] => {
  const elementsMap = arrayToMap(elements);
  const inkById = new Map<string, string>();
  for (const container of elements) {
    if (!isStickyNoteElement(container) || container.isDeleted) {
      continue;
    }
    const label = getBoundTextElement(container, elementsMap);
    if (!label || label.strokeColor === container.strokeColor) {
      continue;
    }
    const containerChanged =
      prevElementsMap.get(container.id)?.strokeColor !== container.strokeColor;
    const labelChanged =
      prevElementsMap.get(label.id)?.strokeColor !== label.strokeColor;
    if (
      isTransparent(label.strokeColor) ||
      (containerChanged && !labelChanged)
    ) {
      inkById.set(
        label.id,
        normalizeStickyNoteStrokeColor(container.strokeColor),
      );
    } else {
      inkById.set(
        container.id,
        normalizeStickyNoteStrokeColor(label.strokeColor),
      );
    }
  }
  if (!inkById.size) {
    return elements;
  }
  return elements.map((element) => {
    const strokeColor = inkById.get(element.id);
    return strokeColor === undefined
      ? element
      : (newElementWith(element as ExcalidrawElement, { strokeColor }) as T);
  });
};

const jitter = (random: () => number, amount: number) =>
  (random() * 2 - 1) * amount;

const pointAtDistance = (
  from: StickyNoteRenderPoint,
  to: StickyNoteRenderPoint,
  distance: number,
) => {
  const dx = to.x - from.x;
  const dy = to.y - from.y;
  const length = Math.hypot(dx, dy);

  if (!length) {
    return from;
  }

  const ratio = Math.min(distance / length, 1);
  return {
    x: from.x + dx * ratio,
    y: from.y + dy * ratio,
  };
};

export const getStickyNoteCornerRadius = (
  element: ExcalidrawStickyNoteElement,
) => {
  if (!element.roundness) {
    return 0;
  }

  return Math.min(
    Math.min(element.width, element.height) * STICKY_NOTE_CORNER_RADIUS_RATIO,
    STICKY_NOTE_MAX_CORNER_RADIUS,
  );
};

export const getStickyNoteRenderPoints = (
  element: ExcalidrawStickyNoteElement,
  {
    offsetX = 0,
    offsetY = 0,
    seedOffset = 0,
  }: {
    offsetX?: number;
    offsetY?: number;
    seedOffset?: number;
  } = {},
): StickyNoteRenderPoint[] => {
  const roughness = Math.max(0, Math.min(2, Math.round(element.roughness)));
  const amount = Math.min(
    STICKY_NOTE_RENDER_ROUGHNESS[roughness],
    Math.min(element.width, element.height) * 0.012,
  );

  if (!amount) {
    return [
      { x: offsetX, y: offsetY },
      { x: offsetX + element.width, y: offsetY },
      { x: offsetX + element.width, y: offsetY + element.height },
      { x: offsetX, y: offsetY + element.height },
    ];
  }

  const random = seededRandom(element.seed + seedOffset);

  return [
    {
      x: offsetX + jitter(random, amount),
      y: offsetY + jitter(random, amount),
    },
    {
      x: offsetX + element.width + jitter(random, amount),
      y: offsetY + jitter(random, amount),
    },
    {
      x: offsetX + element.width + jitter(random, amount),
      y: offsetY + element.height + jitter(random, amount),
    },
    {
      x: offsetX + jitter(random, amount),
      y: offsetY + element.height + jitter(random, amount),
    },
  ];
};

export const getStickyNotePathCommands = (
  element: ExcalidrawStickyNoteElement,
  { shadow = false }: { shadow?: boolean } = {},
): StickyNotePathCommand[] => {
  const points = getStickyNoteRenderPoints(
    element,
    shadow
      ? {
          offsetX: STICKY_NOTE_SHADOW_OFFSET,
          offsetY: STICKY_NOTE_SHADOW_OFFSET,
          seedOffset: 1,
        }
      : undefined,
  );
  const radius = getStickyNoteCornerRadius(element);
  // The note's seed keeps the same corner for the paper and shadow through
  // redraws and resizes.
  const liftedCorner =
    element.roughness === 2
      ? Math.floor(seededRandom(element.seed)() * points.length)
      : -1;

  if (!radius && liftedCorner === -1) {
    return [
      { type: "move", point: points[0] },
      ...points.slice(1).map(
        (point): StickyNotePathCommand => ({
          type: "line",
          point,
        }),
      ),
    ];
  }

  const corners = points.map((point, index): StickyNotePathCommand[] => {
    const prev = points[(index + points.length - 1) % points.length];
    const next = points[(index + 1) % points.length];
    const cornerRadius = Math.min(
      radius,
      Math.hypot(point.x - prev.x, point.y - prev.y) / 2,
      Math.hypot(point.x - next.x, point.y - next.y) / 2,
    );

    if (index === liftedCorner) {
      const size = Math.min(element.width, element.height);
      const reach = Math.min(size * 0.18, 40);
      // The shadow follows the paper inward at half the bend, keeping its
      // usual down-right offset from the light at the top left.
      const lift = Math.min(size * 0.02, 5) * (shadow ? 0.5 : 1);
      // The bend joins the straight edges before the corner, keeping it local.
      const tip = {
        x: point.x + (index === 1 || index === 2 ? -lift : lift),
        y: point.y + (index >= 2 ? -lift : lift),
      };
      const start = pointAtDistance(point, prev, reach);
      const end = pointAtDistance(point, next, reach);
      return [
        { type: "line", point: start },
        {
          type: "quadratic",
          control: pointAtDistance(point, prev, reach / 2),
          point: pointAtDistance(tip, start, cornerRadius),
        },
        {
          type: "quadratic",
          control: tip,
          point: pointAtDistance(tip, end, cornerRadius),
        },
        {
          type: "quadratic",
          control: pointAtDistance(point, next, reach / 2),
          point: end,
        },
      ];
    }

    return [
      { type: "line", point: pointAtDistance(point, prev, cornerRadius) },
      {
        type: "quadratic",
        control: point,
        point: pointAtDistance(point, next, cornerRadius),
      },
    ];
  });

  const commands: StickyNotePathCommand[] = [
    { type: "move", point: corners[0][corners[0].length - 1].point },
  ];

  for (let index = 1; index <= corners.length; index++) {
    commands.push(...corners[index % corners.length]);
  }

  return commands;
};

// -----------------------------------------------------------------------------
// font size — `baseFontSize` is the size the user picked, `fontSize` the fitted one
// -----------------------------------------------------------------------------

// clamping the ceiling: the fit steps down from it in `STICKY_NOTE_FONT_STEP`
// increments, and for values >= ~2^56 (1e20 - 2 === 1e20) that would never
// progress and hang the editor
export const normalizeStickyNoteFontSize = (fontSize: number) => {
  if (!Number.isFinite(fontSize)) {
    return STICKY_NOTE_FALLBACK_FONT_SIZE;
  }
  return Math.min(STICKY_NOTE_MAX_FONT_SIZE, Math.max(MIN_FONT_SIZE, fontSize));
};

/** whether the text element is the label of a sticky note */
export const isStickyNoteBoundText = (
  textElement: ExcalidrawTextElement,
  elementsMap: ElementsMap,
) => {
  return (
    !!textElement.containerId &&
    isStickyNoteElement(elementsMap.get(textElement.containerId))
  );
};

/**
 * The font size the user picked: the ceiling the auto-fit shrinks from for a
 * sticky note label, plain `fontSize` for any other text.
 *
 * Container-aware on purpose — generic binding repair (duplication, history)
 * rewrites `containerId` without touching the ceiling, so a numeric
 * `baseFontSize` alone does not prove the text is still sticky-bound.
 */
export const getBaseFontSize = (
  textElement: ExcalidrawTextElement,
  elementsMap: ElementsMap,
) => {
  return isStickyNoteBoundText(textElement, elementsMap)
    ? textElement.baseFontSize ?? textElement.fontSize
    : textElement.fontSize;
};

/** the update that applies a user-picked font size (see `getBaseFontSize`) */
export const getBaseFontSizeUpdate = (
  textElement: ExcalidrawTextElement,
  fontSize: number,
  elementsMap: ElementsMap,
): { fontSize: number } | { baseFontSize: number } => {
  return isStickyNoteBoundText(textElement, elementsMap)
    ? { baseFontSize: normalizeStickyNoteFontSize(fontSize) }
    : { fontSize };
};

const MONTHS = [
  "Jan",
  "Feb",
  "Mar",
  "Apr",
  "May",
  "Jun",
  "Jul",
  "Aug",
  "Sep",
  "Oct",
  "Nov",
  "Dec",
];

/**
 * The creation-date label: absolute, so painting needs no clock and exports
 * don't go stale, and short ("7 Sep") while the year is the current one.
 * `null` when the note has no usable timestamp (files restored without one).
 * Fixed English in the viewer's local time zone — the element package has no
 * locale, and the footer is chosen by width bucket rather than measured.
 */
export const getStickyNoteDateLabel = (
  created: ExcalidrawStickyNoteElement["created"],
  { short = false, now = Date.now() }: { short?: boolean; now?: number } = {},
): string | null => {
  if (created === null || !Number.isFinite(created)) {
    return null;
  }
  const date = new Date(created);
  if (Number.isNaN(date.getTime())) {
    return null;
  }
  const label = `${date.getDate()} ${MONTHS[date.getMonth()]}`;
  const year = date.getFullYear();
  return short || year === new Date(now).getFullYear()
    ? label
    : `${label} ${year}`;
};

/**
 * What the footer paints and where, in note-local coordinates — shared by the
 * canvas and SVG renderers, which take the font and opacity from
 * `STICKY_NOTE_FOOTER`. `null` for the 0×0 creation draft and anything under
 * the data floor, where the band would overlap the top padding.
 */
export const getStickyNoteFooter = (
  element: Pick<ExcalidrawStickyNoteElement, "created" | "width" | "height">,
  now = Date.now(),
) => {
  if (
    element.width < STICKY_NOTE_MIN_SIZE ||
    element.height < STICKY_NOTE_MIN_SIZE
  ) {
    return null;
  }
  const text = getStickyNoteDateLabel(element.created, {
    short:
      element.width - STICKY_NOTE_PADDING * 2 <
      STICKY_NOTE_FOOTER.minBodyWidthForYear,
    now,
  });
  if (!text) {
    return null;
  }
  return {
    text,
    x: element.width - STICKY_NOTE_PADDING,
    y: element.height - STICKY_NOTE_FOOTER.baselineFromBottom,
  };
};

/**
 * The smallest note the UI lets a user create or resize to: one line at the
 * label's font ceiling plus padding (and, vertically, the footer), never below
 * `STICKY_NOTE_MIN_SIZE`. Without the font term a fresh note would grow on
 * the very first keystroke. Data-level passes (restore, action post-passes)
 * only enforce the constant floor — the layout grows a note as needed.
 */
export const getStickyNoteMinSize = ({
  fontSize,
  fontFamily,
}: Pick<ExcalidrawTextElement, "fontSize" | "fontFamily">) => {
  const lineHeightPx = Math.ceil(
    normalizeStickyNoteFontSize(fontSize) * getLineHeight(fontFamily),
  );
  return {
    width: Math.max(
      STICKY_NOTE_MIN_SIZE,
      lineHeightPx + STICKY_NOTE_PADDING * 2,
    ),
    height: Math.max(
      STICKY_NOTE_MIN_SIZE,
      lineHeightPx + STICKY_NOTE_BODY_INSET_Y,
    ),
  };
};

// -----------------------------------------------------------------------------
// layout — one pure calculation, two ways of applying it
// -----------------------------------------------------------------------------

export type StickyNoteLayoutAnchor = VerticalResizeAnchor;

export type StickyNoteLayoutOpts = {
  /** unwrapped text to lay out; defaults to the label's `originalText` */
  originalText?: string;
  /**
   * absolute base-height intent — the gesture-start value to preserve, or the
   * height a resize asked for. Omitted = keep the note's live `baseHeight`
   * (typing, style changes, restore).
   */
  baseHeight?: number;
  /**
   * absolute font-ceiling intent (a proportional resize passes
   * `gesture-start ceiling × scale`). Omitted = keep the label's live ceiling.
   * Never a multiplier on the live value — that compounds across pointer-moves.
   */
  baseFontSize?: number;
  /** the edge that stays put when the content correction changes the height */
  anchor?: StickyNoteLayoutAnchor;
  /**
   * the host whose text metrics the fit measures with; omitted = the global
   * environment. An editor passes its own so a note laid out in one window
   * (or headlessly) is measured with that realm's fonts and canvas.
   */
  renderEnvironment?: RenderEnvironment;
};

export type StickyNoteLayout = {
  container: Pick<
    ExcalidrawStickyNoteElement,
    "x" | "y" | "width" | "height" | "baseHeight"
  >;
  text: Pick<
    ExcalidrawTextElement,
    | "text"
    | "fontSize"
    | "baseFontSize"
    | "width"
    | "height"
    | "x"
    | "y"
    | "angle"
  > | null;
};

type FontFit = {
  text: string;
  fontSize: number;
  width: number;
  height: number;
};

// `computeBoundTextPosition` only consults the map for arrow containers
const NO_ELEMENTS: ElementsMap = new Map();

const getStickyNoteBaseWidth = (container: ExcalidrawStickyNoteElement) => {
  return Math.max(container.width, STICKY_NOTE_MIN_SIZE);
};

/**
 * Largest font size on the grid `{ceiling − k·STEP} ∪ {min}` whose wrapped
 * text fits the note; `min` when nothing fits (the note then grows). The grid
 * is anchored at the ceiling so the result never depends on earlier edits.
 * Warm-started from the previously fitted size: the common keystroke costs one
 * or two wrap+measure passes, a cold search at most log2(steps) + 2.
 */
const fitStickyNoteFont = (
  fit: (fontSize: number) => FontFit,
  {
    baseFontSize,
    fontSizeMin,
    maxWidth,
    maxHeight,
    warmStart,
  }: {
    baseFontSize: number;
    fontSizeMin: number;
    maxWidth: number;
    maxHeight: number;
    warmStart: number;
  },
): FontFit => {
  const steps = Math.max(
    0,
    Math.ceil((baseFontSize - fontSizeMin) / STICKY_NOTE_FONT_STEP),
  );
  const sizeAt = (index: number) =>
    index >= steps ? fontSizeMin : baseFontSize - index * STICKY_NOTE_FONT_STEP;

  const fits = new Map<number, FontFit>();
  const at = (index: number) => {
    let result = fits.get(index);
    if (!result) {
      result = fit(sizeAt(index));
      fits.set(index, result);
    }
    return result;
  };
  const doesFit = (index: number) => {
    const result = at(index);
    return result.width <= maxWidth && result.height <= maxHeight;
  };

  if (steps === 0) {
    return at(0);
  }

  // the previous fitted size, snapped onto the grid and clamped into the
  // current interval (a lowered ceiling must not keep the old larger size)
  const warm = clamp(
    Math.round((baseFontSize - warmStart) / STICKY_NOTE_FONT_STEP),
    0,
    steps,
  );

  // binary search for the smallest index (largest font) that fits
  let lo: number;
  let hi: number;
  if (doesFit(warm)) {
    if (warm === 0 || !doesFit(warm - 1)) {
      return at(warm);
    }
    lo = 0;
    hi = warm - 1;
  } else {
    if (warm === steps) {
      return at(steps);
    }
    lo = warm + 1;
    hi = steps;
  }
  while (lo < hi) {
    const mid = (lo + hi) >> 1;
    if (doesFit(mid)) {
      hi = mid;
    } else {
      lo = mid + 1;
    }
  }
  return at(lo);
};

/**
 * The single source of truth for a sticky note's geometry: wraps the label at
 * the note's width, fits the font under the ceiling, grows the note past
 * `baseHeight` only when the text still overflows at the minimum size, and
 * positions the label inside. Pure — returns the updates for both elements.
 */
export const getStickyNoteLayout = (
  container: ExcalidrawStickyNoteElement,
  textElement: ExcalidrawTextElement | null,
  opts: StickyNoteLayoutOpts = {},
): StickyNoteLayout => {
  const baseWidth = getStickyNoteBaseWidth(container);
  const baseHeight = Math.max(
    opts.baseHeight ?? (container.baseHeight || container.height),
    STICKY_NOTE_MIN_SIZE,
  );
  const anchor = opts.anchor ?? "top";
  const { renderEnvironment } = opts;

  if (!textElement) {
    // an empty note sits at its base height
    return {
      container: {
        ...getPositionAfterHeightChange(container, baseHeight, anchor),
        width: baseWidth,
        height: baseHeight,
        baseHeight,
      },
      text: null,
    };
  }

  const originalText = opts.originalText ?? textElement.originalText;
  const baseFontSize = normalizeStickyNoteFontSize(
    opts.baseFontSize ?? textElement.baseFontSize ?? textElement.fontSize,
  );
  const fontSizeMin = Math.min(STICKY_NOTE_MIN_FONT_SIZE, baseFontSize);
  const maxWidth = Math.max(baseWidth - STICKY_NOTE_PADDING * 2, 1);
  const maxHeight = Math.max(baseHeight - STICKY_NOTE_BODY_INSET_Y, 0);
  const { fontFamily, lineHeight } = textElement;

  const fit = (fontSize: number): FontFit => {
    const font = getFontString({ fontFamily, fontSize });
    const text = wrapText(originalText, font, maxWidth, renderEnvironment);
    return {
      text,
      fontSize,
      ...measureText(text, font, lineHeight, renderEnvironment),
    };
  };

  const isBlank = !originalText.trim();
  const fitted: FontFit = isBlank
    ? {
        text: "",
        fontSize: baseFontSize,
        ...measureText(
          "",
          getFontString({ fontFamily, fontSize: baseFontSize }),
          lineHeight,
          renderEnvironment,
        ),
      }
    : fitStickyNoteFont(fit, {
        baseFontSize,
        fontSizeMin,
        maxWidth,
        maxHeight,
        warmStart: textElement.fontSize,
      });

  const height = isBlank
    ? baseHeight
    : Math.max(baseHeight, fitted.height + STICKY_NOTE_BODY_INSET_Y);
  const nextContainer = {
    ...getPositionAfterHeightChange(container, height, anchor),
    width: baseWidth,
    height,
    baseHeight,
  };
  const { x, y } = computeBoundTextPosition(
    { ...container, ...nextContainer },
    {
      ...textElement,
      text: fitted.text,
      fontSize: fitted.fontSize,
      width: fitted.width,
      height: fitted.height,
    } as ExcalidrawTextElementWithContainer,
    NO_ELEMENTS,
  );

  return {
    container: nextContainer,
    text: {
      text: fitted.text,
      fontSize: fitted.fontSize,
      baseFontSize,
      width: fitted.width,
      height: fitted.height,
      x,
      y,
      angle: container.angle,
    },
  };
};

/**
 * Resize intents for a sticky note — the §3.3 matrix of the plan. Every value
 * is absolute and derived from the gesture-start snapshot on each pointer-move,
 * so releasing Shift (or Alt) mid-gesture restores the original base height
 * and ceiling instead of keeping values a previous move scaled.
 *
 * - width-only gestures (free E/W, Stats W) preserve the base height
 * - height-changing gestures use the requested height as the new base
 * - proportional gestures (Shift on any handle, aspect-locked multi-select,
 *   Stats group) additionally scale the font ceiling with the note
 * - flips preserve everything
 * - the content correction anchors at the edge the gesture holds still
 */
export const getStickyNoteResizeIntent = (
  /** the note with the requested geometry already applied */
  container: ExcalidrawStickyNoteElement,
  originalElementsMap: ElementsMap,
  handleDirection: TransformHandleDirection,
  {
    proportional,
    fromCenter,
    flip = false,
  }: { proportional: boolean; fromCenter: boolean; flip?: boolean },
): Pick<StickyNoteLayoutOpts, "baseHeight" | "baseFontSize" | "anchor"> => {
  const origContainer = originalElementsMap.get(container.id);
  const origSticky = isStickyNoteElement(origContainer)
    ? origContainer
    : container;
  const origText = getBoundTextElement(origSticky, originalElementsMap);
  const ceiling = origText
    ? origText.baseFontSize ?? origText.fontSize
    : undefined;

  if (flip) {
    return { baseHeight: origSticky.baseHeight, baseFontSize: ceiling };
  }

  const changesHeight =
    proportional ||
    handleDirection.includes("n") ||
    handleDirection.includes("s");
  const scale =
    proportional && origSticky.width ? container.width / origSticky.width : 1;
  const isSideHandle = handleDirection.length === 1;

  return {
    baseHeight: changesHeight ? container.height : origSticky.baseHeight,
    baseFontSize: ceiling === undefined ? undefined : ceiling * scale,
    anchor: fromCenter
      ? "center"
      : handleDirection.includes("n")
      ? "bottom"
      : proportional &&
        isSideHandle &&
        (handleDirection === "e" || handleDirection === "w")
      ? // Shift+E/W holds the opposite side's midpoint, i.e. the vertical center
        "center"
      : "top",
  };
};

/**
 * Applies `getStickyNoteLayout` to a live scene, then runs the bound-arrow
 * pass unless the caller already owns one (`bindings: false`) or needs to
 * forward its context (`bindings: { simultaneouslyUpdated }` — arrows resized
 * in the same gesture must not be moved by the pass, `updateBoundElements`
 * skips them only when told).
 */
export const updateStickyNoteLayout = (
  container: ExcalidrawStickyNoteElement,
  scene: Scene,
  {
    text,
    bindings,
    ...layoutOpts
  }: StickyNoteLayoutOpts & {
    /** the label to lay out when it is an uncommitted clone (font actions clone before install) */
    text?: ExcalidrawTextElement | null;
    bindings?:
      | { simultaneouslyUpdated?: readonly NonDeletedExcalidrawElement[] }
      | false;
  } = {},
): StickyNoteLayout => {
  const elementsMap = scene.getNonDeletedElementsMap();
  const textElement =
    text === undefined ? getBoundTextElement(container, elementsMap) : text;
  const layout = getStickyNoteLayout(container, textElement, layoutOpts);

  scene.mutateElement(container, layout.container);
  if (textElement && layout.text) {
    scene.mutateElement(textElement, layout.text);
  }
  if (bindings !== false && !container.isDeleted) {
    updateBoundElements(container as NonDeletedExcalidrawElement, scene, {
      ...bindings,
      renderEnvironment: layoutOpts.renderEnvironment,
    });
  }

  return layout;
};

const STICKY_NOTE_LAYOUT_INPUTS = {
  container: ["x", "y", "width", "baseHeight", "angle"],
  text: [
    "originalText",
    "baseFontSize",
    "fontFamily",
    "lineHeight",
    "textAlign",
    "verticalAlign",
  ],
} as const;

const hasStickyNoteLayoutInputChanged = (
  container: ExcalidrawStickyNoteElement,
  textElement: ExcalidrawTextElement | null,
  prevElementsMap: ElementsMap,
) => {
  const prevContainer = prevElementsMap.get(container.id);
  const prevText = textElement ? prevElementsMap.get(textElement.id) : null;
  if (
    !prevContainer ||
    (textElement && !prevText) ||
    (!textElement &&
      prevContainer.boundElements?.some(({ type }) => type === "text"))
  ) {
    return true;
  }
  return (
    STICKY_NOTE_LAYOUT_INPUTS.container.some(
      (key) => (prevContainer as any)[key] !== container[key],
    ) ||
    (!!textElement &&
      STICKY_NOTE_LAYOUT_INPUTS.text.some(
        (key) => (prevText as any)[key] !== textElement[key],
      ))
  );
};

/**
 * Applies `getStickyNoteLayout` inside an immutable elements array (property
 * actions, paste styles, restore): the notes among `affectedIds` — or the
 * notes whose labels are — get both halves merged into their clones. Elements
 * that need no change keep their identity and version; when `prevElementsMap`
 * is given, notes whose layout inputs did not change skip the fit entirely.
 * Bound arrows are the caller's job once the result is installed.
 */
export const relayoutStickyNotes = <T extends ExcalidrawElement>(
  elements: readonly T[],
  affectedIds: ReadonlySet<ExcalidrawElement["id"]>,
  opts?: {
    prevElementsMap?: ElementsMap;
    renderEnvironment?: RenderEnvironment;
  },
): readonly T[] => {
  if (!affectedIds.size) {
    return elements;
  }
  const elementsMap = arrayToMap(elements);
  const containerIds = new Set<ExcalidrawElement["id"]>();
  for (const id of affectedIds) {
    const element = elementsMap.get(id);
    if (!element || element.isDeleted) {
      continue;
    }
    if (isStickyNoteElement(element)) {
      containerIds.add(element.id);
    } else if (isTextElement(element) && element.containerId) {
      const container = elementsMap.get(element.containerId);
      if (container && !container.isDeleted && isStickyNoteElement(container)) {
        containerIds.add(container.id);
      }
    }
  }
  if (!containerIds.size) {
    return elements;
  }

  const replacements = new Map<ExcalidrawElement["id"], T>();
  for (const id of containerIds) {
    const container = elementsMap.get(id) as ExcalidrawStickyNoteElement;
    const textElement = getBoundTextElement(container, elementsMap);
    if (
      opts?.prevElementsMap &&
      !hasStickyNoteLayoutInputChanged(
        container,
        textElement,
        opts.prevElementsMap,
      )
    ) {
      continue;
    }
    const layout = getStickyNoteLayout(container, textElement, {
      renderEnvironment: opts?.renderEnvironment,
    });
    const nextContainer = newElementWith(container, layout.container);
    if (nextContainer !== container) {
      replacements.set(id, nextContainer as unknown as T);
    }
    if (textElement && layout.text) {
      const nextText = newElementWith(textElement, layout.text);
      if (nextText !== textElement) {
        replacements.set(textElement.id, nextText as unknown as T);
      }
    }
  }
  if (!replacements.size) {
    return elements;
  }
  return elements.map((element) => replacements.get(element.id) ?? element);
};