Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
/**
* Everything the editor can do, as named commands shared by the ribbon,
* context menus, and keyboard shortcuts. Each command reads the current
* selection (shapes, text, or table cells) and turns intent into engine
* operations.
*/
import type {
AnimationClass,
AnimationSpec,
BorderEdges,
BulletSpec,
CellRef,
ChartGrouping,
ChartSeriesData,
CropOutline,
EditableChartKind,
EditOp,
FillSpec,
LinePatch,
MergeMode,
NewShape,
ParaPatch,
RunPatch,
ShapeOutline,
SlideOutline,
TextDirection,
TextPos,
TransitionPatch,
} from '@core/pptx-engine/types';
import { fireAndForget } from '@core/util/fireAndForget';
import type { PptxEditorContext } from '../context/pptx-editor-context';
import { effectInfo, specOf } from '../core/animation-catalog';
import { orderRange, textInRange } from '../core/caret';
import { formatState, stepFontSize } from '../core/formatting';
import { linkSpan } from '../core/links';
import { mediaBox, mediaType } from '../core/media';
import { modulate } from '../core/palette';
import { aspectCrop, NO_CROP } from '../core/picture';
import {
type AlignMode,
alignOps,
reorderOps,
rotateOps,
sizeOps,
} from '../core/selection';
import { moveSlidesOps } from '../core/slide-selection';
import {
formatCommand,
isCollapsed,
paragraphCommand,
} from '../core/text-commands';
import { createDeckCommands } from './create-deck-commands';
import type { PresentationSession } from './create-presentation-session';
import type { SlideEditor } from './create-slide-editor';
import { audioPoster, videoPoster } from './media-poster';
export interface EditorCommandsOptions {
session: PresentationSession;
editor: SlideEditor;
context: PptxEditorContext;
slideSize: () => { w: number; h: number };
/** Returns keyboard focus to the text being edited, or the stage. */
refocus: () => void;
/** Starts typing into a shape (after inserting a text box). */
startEditing: (shape: number) => void;
/** The table cells commands act on: the edited cell or a selected range. */
tableTarget: () => TableTarget | undefined;
/** Ids of the slides selected in the rail or sorter (slide commands act on all). */
slideSelection?: () => number[];
/** Whether other people edit the presentation live (media must stay small). */
collaborative?: () => boolean;
}
/** A table and the cell range table commands act on (inclusive). */
export interface TableTarget {
shape: ShapeOutline;
from: CellRef;
to: CellRef;
}
async function fileToBase64(file: Blob): Promise<string> {
const buffer = new Uint8Array(await file.arrayBuffer());
let binary = '';
for (let i = 0; i < buffer.length; i += 0x8000) {
binary += String.fromCharCode(...buffer.subarray(i, i + 0x8000));
}
return btoa(binary);
}
export type TextToggle = 'bold' | 'italic' | 'underline' | 'strike';
/** What the link dialog edits (`linkTarget`). */
export interface LinkTarget {
kind: 'text' | 'cells' | 'shapes';
/** The text range, for `text`. */
start?: TextPos;
end?: TextPos;
/** The shapes, for `shapes`. */
shapes?: number[];
/** The current link and ScreenTip. */
link?: string;
tip?: string;
/** The linked (or selected) text. */
text?: string;
/** Whether "Text to display" can replace the text. */
canSetText: boolean;
}
export function createEditorCommands(options: EditorCommandsOptions) {
const { session, editor, context } = options;
const slide = () => session.currentSlide();
const canEdit = () => context.canEdit();
/** The selected slides in deck order, or the current one. */
const selectedSlides = (): SlideOutline[] => {
const ids = options.slideSelection?.() ?? [];
const list = session.outline()?.slides.filter((s) => ids.includes(s.id));
const current = slide();
return list && list.length > 0 ? list : current ? [current] : [];
};
const apply = async (ops: EditOp[], group?: string) => {
if (ops.length === 0) return null;
return session.apply(ops, group);
};
// ---- text ----------------------------------------------------------------
const format = () => {
const src = editor.formatSource();
return formatState(src.layout, src.range);
};
/** The paragraph style at the caret (or the shape's first paragraph). */
const paragraphStyle = () => {
const src = editor.formatSource();
const p = src.range?.[0].paragraph ?? 0;
return src.layout?.styles[p];
};
/** Text formatting applies: text is edited, or text shapes or cells are selected. */
const textActive = () =>
!!editor.editing() ||
editor.selection().some((s) => s.textEditable) ||
!!options.tableTarget();
/** The selected cell range, when formatting goes to cells. */
const cellRange = () =>
editor.editing() ? undefined : options.tableTarget();
const runs = (props: RunPatch) => {
if (cellRange()) return formatCells(props);
return editor
.formatWith((t, range) => formatCommand(t, range, props))
.then(options.refocus);
};
const paragraphs = (props: ParaPatch) => {
if (cellRange())
return tableOp((slideId, t) =>
cellsOf(t).map((cell) => ({
op: 'formatParagraphs' as const,
slide: slideId,
shape: t.shape.id,
cell,
props,
}))
);
return editor
.formatWith((t, range) => paragraphCommand(t, range, props))
.then(options.refocus);
};
const toggle = (key: TextToggle) => runs({ [key]: !format()[key] });
const setFont = (font: string) => runs({ font });
const setFontSize = (size: number) =>
runs({ size: Math.max(1, Math.min(4000, size)) });
const stepSize = (direction: 1 | -1) =>
setFontSize(stepFontSize(format().size ?? 18, direction));
const setTextColor = (color: string) => runs({ color });
const setHighlight = (color: string | null) =>
runs({ highlight: color ?? '' });
const toggleBaseline = (kind: 'super' | 'sub') => {
const current = format().baseline ?? 0;
const target = kind === 'super' ? 30 : -25;
return runs({
baseline: Math.sign(current) === Math.sign(target) ? 0 : target,
});
};
const clearFormatting = () =>
runs({
bold: false,
italic: false,
underline: false,
strike: false,
baseline: 0,
highlight: '',
});
const setLink = (url: string) => runs({ link: url });
const setCharSpacing = (spacing: number) =>
runs({ spacing: Math.max(-100, Math.min(400, spacing)) });
// ---- links -----------------------------------------------------------------
/**
* What Insert Link edits: the edited text's selection (or the whole link
* around the caret), the selected cells, or the selected shapes themselves.
*/
const linkTarget = (): LinkTarget | undefined => {
const edit = editor.editing();
if (edit?.layout) {
const { layout, selection } = edit;
const span = isCollapsed(selection)
? linkSpan(layout, selection.focus)
: undefined;
const [start, end] = span
? [span.start, span.end]
: orderRange(selection.anchor, selection.focus);
const style = layout.styles[start.paragraph];
const run = style?.runs.find(
(r) => r.link && r.end > start.offset && r.start <= start.offset
);
return {
kind: 'text',
start,
end,
link: span?.link ?? run?.link,
tip: span?.tip ?? run?.linkTip,
text: textInRange(layout, start, end),
canSetText: start.paragraph === end.paragraph,
};
}
if (cellRange()) return { kind: 'cells', canSetText: false };
const shapes = editor.selection();
if (shapes.length === 0) return undefined;
return {
kind: 'shapes',
shapes: shapes.map((x) => x.id),
link: shapes[0].link,
tip: shapes[0].linkTip,
canSetText: false,
};
};
/** Links (or with `link` `""` unlinks) what `linkTarget` names. */
const applyLink = async (
target: LinkTarget,
link: string,
tip?: string,
text?: string
) => {
const s = slide();
if (!s) return;
const linkTip = link ? (tip ?? '') : undefined;
if (target.kind === 'text' && target.start && target.end) {
await editor.linkText(target.start, target.end, link, tip, text);
options.refocus();
} else if (target.kind === 'cells') {
await formatCells({ link, linkTip });
} else if (target.kind === 'shapes' && target.shapes)
await apply([
{
op: 'setShapeLink',
slide: s.id,
shapes: target.shapes,
link,
tip: linkTip,
},
]);
};
const align = (value: NonNullable<ParaPatch['align']>) =>
paragraphs({ align: value });
const setBullets = (bullet: BulletSpec) => paragraphs({ bullet });
const toggleBullets = () =>
setBullets(
format().bullet ? { kind: 'none' } : { kind: 'char', char: '•' }
);
const toggleNumbering = () =>
setBullets(
format().bullet
? { kind: 'none' }
: { kind: 'number', scheme: 'arabicPeriod', start: 1 }
);
const indent = (direction: 1 | -1) => {
const level = paragraphStyle()?.level ?? 0;
return paragraphs({
level: Math.max(0, Math.min(8, level + direction)),
});
};
const lineSpacing = (multiple: number) =>
paragraphs({ lineSpacing: multiple });
const spacing = (before?: number, after?: number) =>
paragraphs({
...(before !== undefined ? { spaceBefore: before } : {}),
...(after !== undefined ? { spaceAfter: after } : {}),
});
/** Text box settings for the edited shape (or cell), or every selected one. */
const body = async (
props: Extract<EditOp, { op: 'formatBody' }>['props']
) => {
const s = slide();
if (!s) return;
if (cellRange()) {
await tableOp((slideId, t) =>
cellsOf(t).map((cell) => ({
op: 'formatBody' as const,
slide: slideId,
shape: t.shape.id,
cell,
props,
}))
);
return;
}
const edit = editor.editing();
if (edit) {
await apply([
{
op: 'formatBody',
slide: s.id,
shape: edit.shape,
...(edit.cell ? { cell: edit.cell } : {}),
props,
},
]);
await editor.refreshEditing();
options.refocus();
return;
}
await apply(
editor
.selection()
.filter((x) => x.textEditable)
.map((x) => ({
op: 'formatBody' as const,
slide: s.id,
shape: x.id,
props,
}))
);
};
/** The text direction Text Direction shows: the edited or first target's. */
const textDirection = (): TextDirection => {
const edit = editor.editing();
const t = options.tableTarget();
if (t && (!edit || edit.cell))
return (
t.shape.table?.cells?.[t.from.row]?.[t.from.col]?.textDirection ??
'horz'
);
const shape = edit
? editor.findShape(edit.shape)
: editor.selection().find((s) => s.textEditable);
return shape?.textDirection ?? 'horz';
};
/** Home ▸ Text Direction (and the table Layout tab's) for the targets. */
const setTextDirection = (direction: TextDirection) => body({ direction });
// ---- shapes ----------------------------------------------------------------
/** The shapes shape formatting applies to. */
const targets = (): ShapeOutline[] => {
const edit = editor.editing();
if (edit) {
const shape = editor.findShape(edit.shape);
return shape && !edit.cell ? [shape] : [];
}
return editor.selection();
};
const each = (build: (slide: number, shape: ShapeOutline) => EditOp) => {
const s = slide();
if (!s) return Promise.resolve(null);
return apply(targets().map((shape) => build(s.id, shape)));
};
const setFill = (fill: FillSpec) =>
each((s, shape) => ({ op: 'setFill', slide: s, shape: shape.id, fill }));
const fillColor = (color: string | null) =>
setFill(color ? { kind: 'solid', color } : { kind: 'none' });
const setLine = (line: LinePatch) =>
each((s, shape) => ({ op: 'setLine', slide: s, shape: shape.id, line }));
const setGeometry = (preset: string) =>
each((s, shape) => ({
op: 'setGeometry',
slide: s,
shape: shape.id,
preset,
}));
const arrange = (to: 'front' | 'back' | 'forward' | 'backward') => {
const s = slide();
if (!s) return;
fireAndForget(
apply(reorderOps(s.id, targets(), s.shapes, to)),
'pptx-editor'
);
};
/** Moves one shape `steps` places toward the front (negative: back). */
const moveInZOrder = (shape: number, steps: number) => {
const s = slide();
if (!s || steps === 0) return;
const to = steps > 0 ? 'forward' : 'backward';
return apply(
Array.from({ length: Math.abs(steps) }, () => ({
op: 'reorderShape' as const,
slide: s.id,
shape,
to,
}))
);
};
const renameShape = (shape: number, name: string) => {
const s = slide();
if (s) return apply([{ op: 'setShapeName', slide: s.id, shape, name }]);
};
const setShapesHidden = (shapes: number[], hidden: boolean) => {
const s = slide();
if (s)
return apply(
shapes.map((shape) => ({
op: 'setShapeHidden' as const,
slide: s.id,
shape,
hidden,
}))
);
};
const alignShapes = (mode: AlignMode, toSlide = false) => {
const s = slide();
if (!s) return;
fireAndForget(
apply(alignOps(s.id, targets(), mode, options.slideSize(), toSlide)),
'pptx-editor'
);
};
const rotate = (change: 'right90' | 'left90' | 'flipH' | 'flipV') => {
const s = slide();
if (!s) return;
fireAndForget(apply(rotateOps(s.id, targets(), change)), 'pptx-editor');
};
const resize = (size: { w?: number; h?: number }) => {
const s = slide();
if (!s) return;
fireAndForget(apply(sizeOps(s.id, targets(), size)), 'pptx-editor');
};
const move = (at: { x?: number; y?: number }) =>
each((s, shape) => ({
op: 'setTransform',
slide: s,
shape: shape.id,
...at,
}));
const setRotation = (rotation: number) =>
each((s, shape) => ({
op: 'setTransform',
slide: s,
shape: shape.id,
rotation: ((rotation % 360) + 360) % 360,
}));
/** PowerPoint-like quick styles from a theme color. */
const styleShapes = async (
kind: 'solid' | 'outline' | 'light',
color: string
) => {
const s = slide();
const deck = session.outline();
if (!s || !deck) return;
const css =
deck.themeColors.find(
([slot]) => slot === (color === 'tx1' ? 'dk1' : color)
)?.[1] ?? '#000000';
const hex = css.replace('#', '');
const ops: EditOp[] = [];
for (const shape of targets()) {
const fill: FillSpec =
kind === 'solid'
? { kind: 'solid', color }
: kind === 'light'
? { kind: 'solid', color: modulate(hex, 0.2, 0.8) }
: { kind: 'solid', color: 'bg1' };
ops.push({ op: 'setFill', slide: s.id, shape: shape.id, fill });
ops.push({
op: 'setLine',
slide: s.id,
shape: shape.id,
line: {
color: kind === 'solid' ? modulate(hex, 0.75) : color,
width: 1,
},
});
if (shape.textEditable)
ops.push({
op: 'formatText',
slide: s.id,
shape: shape.id,
props: {
color:
kind === 'solid' ? 'bg1' : kind === 'outline' ? color : 'tx1',
},
});
}
await apply(ops);
};
const selectAll = () => {
if (editor.editing()) editor.selectAllText();
else editor.selectAll();
};
// ---- insertion -------------------------------------------------------------
const centered = (w: number, h: number) => {
const size = options.slideSize();
return { x: (size.w - w) / 2, y: (size.h - h) / 2, w, h };
};
const insert = async (
shape: NewShape,
box: { x: number; y: number; w: number; h: number }
) => {
const s = slide();
if (!s) return undefined;
const result = await apply([
{ op: 'addShape', slide: s.id, shape, ...box },
]);
return result?.created[0]?.shape;
};
const insertTextBox = async (box = centered(300, 40)) => {
const id = await insert({ kind: 'textBox', text: '' }, box);
if (id !== undefined) options.startEditing(id);
};
const insertShape = async (preset: string, box = centered(200, 120)) => {
const id =
preset === 'line' || preset === 'arrow'
? await insert({ kind: 'line', arrow: preset === 'arrow' }, box)
: await insert({ kind: 'shape', preset }, box);
if (id !== undefined) editor.select(id);
options.refocus();
return id;
};
const insertImage = async (file: Blob, name = 'Picture') => {
try {
const bitmap = await createImageBitmap(file);
const natural = { w: bitmap.width * 0.75, h: bitmap.height * 0.75 };
bitmap.close();
const size = options.slideSize();
const fit = Math.min(
1,
(size.w * 0.6) / natural.w,
(size.h * 0.6) / natural.h
);
const data = await fileToBase64(file);
const id = await insert(
{ kind: 'image', data, description: name },
centered(natural.w * fit, natural.h * fit)
);
if (id !== undefined) editor.select(id);
} catch {
context.notifyError('That picture could not be inserted.');
}
};
/** Insert ▸ Video or Audio: embeds the clip with a poster, centered. */
const insertMedia = async (file: File, kind: 'video' | 'audio') => {
const checked = mediaType(file, kind, options.collaborative?.() ?? false);
if ('error' in checked) {
context.notifyError(checked.error);
return;
}
try {
const poster =
kind === 'video' ? await videoPoster(file) : await audioPoster();
const natural =
kind === 'video'
? { w: poster.width * 0.75, h: poster.height * 0.75 }
: { w: 48, h: 48 };
const box = mediaBox(natural, options.slideSize());
const id = await insert(
{
kind,
data: await fileToBase64(file),
contentType: checked.type,
poster: poster.data,
description: file.name,
},
box
);
if (id !== undefined) editor.select(id);
options.refocus();
} catch {
context.notifyError(`That ${kind} could not be inserted.`);
}
};
// ---- charts ----------------------------------------------------------------
/** The one selected chart. */
const chartShape = () => {
const shape = editor.selectedShape();
return shape?.kind === 'chart' ? shape : undefined;
};
const formatChart = (
change: Omit<
Extract<EditOp, { op: 'formatChart' }>,
'op' | 'slide' | 'shape'
>
) => {
const s = slide();
const chart = chartShape();
if (!s || !chart) return Promise.resolve(null);
return apply([
{ op: 'formatChart', slide: s.id, shape: chart.id, ...change },
]);
};
const setChartType = (kind: EditableChartKind, grouping?: ChartGrouping) => {
const s = slide();
const chart = chartShape();
if (!s || !chart) return Promise.resolve(null);
return apply([
{
op: 'setChartType',
slide: s.id,
shape: chart.id,
kind,
...(grouping ? { grouping } : {}),
},
]);
};
const setChartData = (
shape: number,
data: { categories: string[]; series: ChartSeriesData[] }
) => {
const s = slide();
if (!s) return Promise.resolve(null);
return apply([{ op: 'setChartData', slide: s.id, shape, ...data }]);
};
const insertChart = async (
chartType: EditableChartKind,
grouping: ChartGrouping | undefined,
data: { categories: string[]; series: ChartSeriesData[] }
) => {
const size = options.slideSize();
const id = await insert(
{
kind: 'chart',
chartType,
...(grouping ? { grouping } : {}),
...data,
title: 'Chart title',
},
centered(Math.min(size.w * 0.6, 560), Math.min(size.h * 0.6, 320))
);
if (id !== undefined) editor.select(id);
return id;
};
/** Replaces the selected picture's image, keeping its frame. */
const replaceImage = async (file: Blob) => {
const s = slide();
const picture = editor.selectedShape();
if (!s || picture?.kind !== 'picture') return;
try {
const data = await fileToBase64(file);
await apply([
{ op: 'replaceImage', slide: s.id, shape: picture.id, data },
]);
} catch {
context.notifyError('That picture could not be used.');
}
};
const insertTable = async (rows = 3, cols = 3) => {
const size = options.slideSize();
const cells = Array.from({ length: rows }, () =>
Array.from({ length: cols }, () => '')
);
const w = Math.min(size.w * 0.8, cols * 120);
const id = await insert({ kind: 'table', cells }, centered(w, rows * 30));
if (id !== undefined) editor.select(id);
};
// ---- slides ----------------------------------------------------------------
const goToSlideId = (id: number) => {
const index = session.outline()?.slides.findIndex((s) => s.id === id) ?? -1;
if (index >= 0) editor.goToSlide(index);
};
const addSlide = async (layout?: string, after = slide()?.id) => {
const result = await apply([
{ op: 'addSlide', after, ...(layout ? { layout } : {}) },
]);
const id = result?.created[0]?.slide;
if (id !== undefined) goToSlideId(id);
};
/** Duplicates a slide, or every selected slide when it is one of them. */
const duplicateSlide = async (id?: number) => {
const selected = selectedSlides();
const ids =
id === undefined || selected.some((s) => s.id === id)
? selected.map((s) => s.id)
: [id];
const result = await apply(
ids.map((slide) => ({ op: 'duplicateSlide' as const, slide }))
);
const created = result?.created.at(-1)?.slide;
if (created !== undefined) goToSlideId(created);
};
const deleteSlides = async (ids: number[]) => {
const deck = session.outline();
if (!deck || ids.length === 0 || ids.length >= deck.slides.length) return;
editor.goToSlide(session.slideIndex());
await apply(ids.map((slide) => ({ op: 'deleteSlide' as const, slide })));
};
/** Hides or shows a slide, and the rest of the selection with it. */
const toggleHidden = (s: SlideOutline) => {
const selected = selectedSlides();
const all = selected.some((x) => x.id === s.id) ? selected : [s];
return apply(
all.map((x) => ({
op: 'setSlideHidden' as const,
slide: x.id,
hidden: !s.hidden,
}))
);
};
const moveSlide = async (id: number, to: number) => {
await apply([{ op: 'moveSlide', slide: id, to }]);
goToSlideId(id);
};
/** Moves slides as a block before the slide now at `at`. */
const moveSlides = async (ids: number[], at: number) => {
const deck = session.outline();
const current = slide()?.id;
if (!deck) return;
await apply(
moveSlidesOps(
deck.slides.map((s) => s.id),
ids,
at
)
);
if (current !== undefined) goToSlideId(current);
};
let lastBackground: FillSpec | null = null;
const applyBackgroundToAll = () => {
const deck = session.outline();
if (!deck) return;
fireAndForget(
apply(
deck.slides.map((x) => ({
op: 'setBackground' as const,
slide: x.id,
fill: lastBackground ?? undefined,
}))
),
'pptx-editor'
);
};
const setBackground = (fill: FillSpec | null, all = false) => {
const deck = session.outline();
const s = slide();
lastBackground = fill;
if (!deck || !s) return;
const ids = all
? deck.slides.map((x) => x.id)
: selectedSlides().map((x) => x.id);
fireAndForget(
apply(
ids.map((id) => ({
op: 'setBackground' as const,
slide: id,
fill: fill ?? undefined,
}))
),
'pptx-editor'
);
};
// ---- tables ----------------------------------------------------------------
/** The rows and columns a table range covers. */
const span = (t: TableTarget) => ({
rows: [
Math.min(t.from.row, t.to.row),
Math.max(t.from.row, t.to.row),
] as const,
cols: [
Math.min(t.from.col, t.to.col),
Math.max(t.from.col, t.to.col),
] as const,
});
const tableOp = (build: (slide: number, t: TableTarget) => EditOp[]) => {
const s = slide();
const t = options.tableTarget();
if (!s || !t) return Promise.resolve(null);
editor.stopEditing();
return apply(build(s.id, t));
};
const insertRows = (where: 'above' | 'below') =>
tableOp((slideId, t) => {
const { rows } = span(t);
const count = rows[1] - rows[0] + 1;
const at = where === 'above' ? rows[0] : rows[1] + 1;
return Array.from({ length: count }, () => ({
op: 'insertTableRow' as const,
slide: slideId,
shape: t.shape.id,
at,
}));
});
const insertColumns = (where: 'left' | 'right') =>
tableOp((slideId, t) => {
const { cols } = span(t);
const count = cols[1] - cols[0] + 1;
const at = where === 'left' ? cols[0] : cols[1] + 1;
return Array.from({ length: count }, () => ({
op: 'insertTableColumn' as const,
slide: slideId,
shape: t.shape.id,
at,
}));
});
const deleteRows = () =>
tableOp((slideId, t) => {
const { rows } = span(t);
const total = t.shape.table?.rowHeights.length ?? 0;
if (rows[1] - rows[0] + 1 >= total)
return [{ op: 'deleteShape', slide: slideId, shape: t.shape.id }];
// Bottom-up, so earlier deletions don't shift later indices.
return Array.from({ length: rows[1] - rows[0] + 1 }, (_, i) => ({
op: 'deleteTableRow' as const,
slide: slideId,
shape: t.shape.id,
row: rows[1] - i,
}));
});
const deleteColumns = () =>
tableOp((slideId, t) => {
const { cols } = span(t);
const total = t.shape.table?.columnWidths.length ?? 0;
if (cols[1] - cols[0] + 1 >= total)
return [{ op: 'deleteShape', slide: slideId, shape: t.shape.id }];
return Array.from({ length: cols[1] - cols[0] + 1 }, (_, i) => ({
op: 'deleteTableColumn' as const,
slide: slideId,
shape: t.shape.id,
col: cols[1] - i,
}));
});
const deleteTable = () =>
tableOp((slideId, t) => [
{ op: 'deleteShape', slide: slideId, shape: t.shape.id },
]);
/** Every cell of the range (top-left of merges included once). */
const cellsOf = (t: TableTarget): CellRef[] => {
const { rows, cols } = span(t);
const out: CellRef[] = [];
for (let row = rows[0]; row <= rows[1]; row++)
for (let col = cols[0]; col <= cols[1]; col++) out.push({ row, col });
return out;
};
/** Paragraph alignment in each cell of the range. */
const alignCells = (align: NonNullable<ParaPatch['align']>) =>
tableOp((slideId, t) =>
cellsOf(t).map((cell) => ({
op: 'formatParagraphs' as const,
slide: slideId,
shape: t.shape.id,
cell,
props: { align },
}))
);
/** Vertical alignment in each cell of the range. */
const anchorCells = (anchor: 'top' | 'middle' | 'bottom') =>
tableOp((slideId, t) => {
const { rows, cols } = span(t);
return [
{
op: 'formatCells' as const,
slide: slideId,
shape: t.shape.id,
from: { row: rows[0], col: cols[0] },
to: { row: rows[1], col: cols[1] },
anchor,
},
];
});
/** Character formatting in each cell of the range. */
const formatCells = (props: RunPatch) =>
tableOp((slideId, t) =>
cellsOf(t).map((cell) => ({
op: 'formatText' as const,
slide: slideId,
shape: t.shape.id,
cell,
props,
}))
);
/** The range as a normalized rectangle. */
const rect = (t: TableTarget) => {
const { rows, cols } = span(t);
return {
from: { row: rows[0], col: cols[0] },
to: { row: rows[1], col: cols[1] },
};
};
const canMerge = () => {
const t = options.tableTarget();
if (!t) return false;
const { rows, cols } = span(t);
return rows[1] > rows[0] || cols[1] > cols[0];
};
const mergeCells = () =>
tableOp((slideId, t) => [
{ op: 'mergeCells', slide: slideId, shape: t.shape.id, ...rect(t) },
]);
/** Merged cells in the range (their anchors). */
const mergesIn = (t: TableTarget): CellRef[] => {
const cells = t.shape.table?.cells;
if (!cells) return [];
const { rows, cols } = span(t);
const out: CellRef[] = [];
for (let row = rows[0]; row <= rows[1]; row++)
for (let col = cols[0]; col <= cols[1]; col++) {
const c = cells[row]?.[col];
if (c && !c.merged && (c.rowSpan > 1 || c.colSpan > 1))
out.push({ row, col });
}
return out;
};
const canSplit = () => {
const t = options.tableTarget();
if (!t) return false;
const { rows, cols } = span(t);
const cells = t.shape.table?.cells;
// A cell covered by a merge counts too.
for (let row = rows[0]; row <= rows[1]; row++)
for (let col = cols[0]; col <= cols[1]; col++) {
const c = cells?.[row]?.[col];
if (c && (c.merged || c.rowSpan > 1 || c.colSpan > 1)) return true;
}
return false;
};
const splitCells = () =>
tableOp((slideId, t) => {
const anchors = mergesIn(t);
const list = anchors.length > 0 ? anchors : [rect(t).from];
return list.map((cell) => ({
op: 'splitCell' as const,
slide: slideId,
shape: t.shape.id,
cell,
}));
});
const fillCells = (color: string | null) =>
tableOp((slideId, t) => [
{
op: 'formatCells',
slide: slideId,
shape: t.shape.id,
...rect(t),
fill: color ? { kind: 'solid', color } : { kind: 'none' },
},
]);
/** The pen new borders are drawn with. */
let pen: { color?: string; width?: number } = {};
const setBorderPen = (change: { color?: string; width?: number }) => {
pen = { ...pen, ...change };
};
const borderCells = (edges: string, none = false) =>
tableOp((slideId, t) => [
{
op: 'formatCells',
slide: slideId,
shape: t.shape.id,
...rect(t),
borders: {
edges: edges as BorderEdges,
line: none
? { none: true }
: {
color: pen.color ?? 'tx1',
width: pen.width ?? 1,
dash: 'solid',
},
},
},
]);
const setTableStyle = (
change: Partial<{
style: string;
firstRow: boolean;
lastRow: boolean;
firstCol: boolean;
lastCol: boolean;
bandRow: boolean;
bandCol: boolean;
}>
) =>
tableOp((slideId, t) => [
{ op: 'setTableStyle', slide: slideId, shape: t.shape.id, ...change },
]);
/** Grid sizes with `change` applied to the range's rows/columns. */
const gridOp = (
slideId: number,
t: TableTarget,
widths: number[] | undefined,
heights: number[] | undefined
): EditOp => ({
op: 'setTableGrid',
slide: slideId,
shape: t.shape.id,
...(widths ? { columnWidths: widths } : {}),
...(heights ? { rowHeights: heights } : {}),
});
const cellSize = () => {
const t = options.tableTarget();
const table = t?.shape.table;
if (!t || !table) return undefined;
const { rows, cols } = span(t);
return {
w: table.columnWidths[cols[0]],
h: (table.laidOutRowHeights ?? table.rowHeights)[rows[0]],
};
};
const setCellSize = (size: { w?: number; h?: number }) =>
tableOp((slideId, t) => {
const table = t.shape.table;
if (!table) return [];
const { rows, cols } = span(t);
const widths =
size.w !== undefined
? table.columnWidths.map((w, i) =>
i >= cols[0] && i <= cols[1] ? size.w! : w
)
: undefined;
const heights =
size.h !== undefined
? table.rowHeights.map((h, i) =>
i >= rows[0] && i <= rows[1] ? size.h! : h
)
: undefined;
return [gridOp(slideId, t, widths, heights)];
});
/** Evens out the range's rows (the whole table when one row is picked). */
const distributeRows = () =>
tableOp((slideId, t) => {
const table = t.shape.table;
if (!table) return [];
let { rows } = span(t);
if (rows[0] === rows[1]) rows = [0, table.rowHeights.length - 1];
const drawn = table.laidOutRowHeights ?? table.rowHeights;
const picked = drawn.slice(rows[0], rows[1] + 1);
const even = picked.reduce((a, b) => a + b, 0) / picked.length;
return [
gridOp(
slideId,
t,
undefined,
table.rowHeights.map((h, i) =>
i >= rows[0] && i <= rows[1] ? even : h
)
),
];
});
const distributeColumns = () =>
tableOp((slideId, t) => {
const table = t.shape.table;
if (!table) return [];
let { cols } = span(t);
if (cols[0] === cols[1]) cols = [0, table.columnWidths.length - 1];
const picked = table.columnWidths.slice(cols[0], cols[1] + 1);
const even = picked.reduce((a, b) => a + b, 0) / picked.length;
return [
gridOp(
slideId,
t,
table.columnWidths.map((w, i) =>
i >= cols[0] && i <= cols[1] ? even : w
),
undefined
),
];
});
/**
* Drags a column border (the next column gives up the space, as in
* PowerPoint) or a row border (the row grows).
*/
const resizeGrid = (
shape: number,
axis: 'col' | 'row',
index: number,
delta: number
) => {
const s = slide();
const table = editor.findShape(shape)?.table;
if (!s || !table) return Promise.resolve(null);
if (axis === 'col') {
const widths = [...table.columnWidths];
const next = index + 1 < widths.length ? index + 1 : undefined;
const d =
next === undefined
? Math.max(delta, 8 - widths[index])
: Math.min(Math.max(delta, 8 - widths[index]), widths[next] - 8);
widths[index] += d;
if (next !== undefined) widths[next] -= d;
return apply([
{ op: 'setTableGrid', slide: s.id, shape, columnWidths: widths },
]);
}
const drawn = table.laidOutRowHeights ?? table.rowHeights;
const heights = table.rowHeights.map((h, i) =>
i === index ? Math.max(8, drawn[i] + delta) : h
);
return apply([
{ op: 'setTableGrid', slide: s.id, shape, rowHeights: heights },
]);
};
// ---- grouping, layouts, transitions -----------------------------------------
/** Groups the selected shapes (two or more). */
const group = async () => {
const s = slide();
const list = editor.selection();
if (!s || list.length < 2) return;
const result = await apply([
{ op: 'groupShapes', slide: s.id, shapes: list.map((x) => x.id) },
]);
const id = result?.created[0]?.shape;
if (id !== undefined && id !== null) editor.select(id);
};
/**
* Merges the selected shapes (Shape Format ▸ Merge Shapes): the result
* takes the first selected shape's look, and is selected.
*/
const mergeShapes = async (mode: MergeMode) => {
const s = slide();
const list = editor.selection();
if (!s || list.length < 2) return;
const result = await apply([
{ op: 'mergeShapes', slide: s.id, shapes: list.map((x) => x.id), mode },
]);
const ids = (result?.created ?? [])
.map((c) => c.shape)
.filter((id): id is number => id !== undefined && id !== null);
if (ids.length > 0) editor.setSelection(ids);
};
/** Ungroups every selected group, selecting their members. */
const ungroup = async () => {
const s = slide();
const groups = editor.selection().filter((x) => x.kind === 'group');
if (!s || groups.length === 0) return;
const result = await apply(
groups.map((g) => ({
op: 'ungroupShape' as const,
slide: s.id,
shape: g.id,
}))
);
const ids = (result?.created ?? [])
.map((c) => c.shape)
.filter((id): id is number => id !== undefined && id !== null);
if (ids.length > 0) editor.setSelection(ids);
};
/** Gives the current slide another layout. */
/** Changes the layout of the selected slides. */
const setLayout = async (layout: string) => {
await apply(
selectedSlides().map((s) => ({
op: 'setSlideLayout' as const,
slide: s.id,
layout,
}))
);
};
/** Changes the transition of the selected slides (or, with `applyToAll`, every slide). */
const setTransition = (patch: Omit<TransitionPatch, 'slide'>) =>
apply(
(patch.applyToAll ? selectedSlides().slice(0, 1) : selectedSlides()).map(
(s) => ({
op: 'setTransition' as const,
slide: s.id,
...patch,
})
)
);
/** Recolors the whole deck with a theme color set. */
const setThemeColors = (colors: Record<string, string>, name?: string) =>
apply([
{
op: 'setThemeColors',
colors: Object.entries(colors).map(([slot, color]) => ({
slot,
color,
})),
...(name ? { name } : {}),
},
]);
/** Sets the deck's heading and body fonts. */
const setThemeFonts = (major: string, minor: string, name?: string) =>
apply([{ op: 'setThemeFonts', major, minor, ...(name ? { name } : {}) }]);
/** Alt text of the one selected shape. */
const setAltText = (text: string) => {
const s = slide();
const shape = editor.selectedShape();
if (!s || !shape) return Promise.resolve(null);
return apply([{ op: 'setAltText', slide: s.id, shape: shape.id, text }]);
};
// ---- animations ------------------------------------------------------------
const animations = () => slide()?.animations ?? [];
const writeAnimations = (list: AnimationSpec[]) => {
const s = slide();
if (!s) return Promise.resolve(null);
return apply([{ op: 'setAnimations', slide: s.id, animations: list }]);
};
// Animation edits rewrite the slide's whole list, so each one waits for
// the last to land and reads the list afresh.
let animationQueue: Promise<unknown> = Promise.resolve();
const serial =
<A extends unknown[], T>(edit: (...args: A) => Promise<T>) =>
(...args: A): Promise<T> => {
const next = animationQueue.then(
() => edit(...args),
() => edit(...args)
);
animationQueue = next.catch(() => {});
return next;
};
/**
* Gives the selected shapes an effect, as the Animation gallery does:
* `replace` swaps the effect of their animations (or of the one picked
* in the pane), `add` adds one more (Add Animation), and the effect
* `none` removes their animations.
*/
const animate = serial(
(
cls: AnimationClass,
effect: string,
mode: 'replace' | 'add',
picked?: number
) => {
const ids = new Set(targets().map((t) => t.id));
if (ids.size === 0) return Promise.resolve(null);
const list = animations().map(specOf);
const holds = (a: AnimationSpec) => ids.has(a.shapeId);
if (effect === 'none')
return writeAnimations(list.filter((a) => !holds(a)));
const option = effectInfo(cls, effect)?.options?.[0]?.value;
const swap = (a: AnimationSpec): AnimationSpec => ({
shapeId: a.shapeId,
class: cls,
effect,
start: a.start,
delayMs: a.delayMs,
direction: option,
paragraph: a.paragraph,
});
const fresh = (shapeId: number): AnimationSpec => ({
shapeId,
class: cls,
effect,
start: 'onClick',
direction: option,
});
if (mode === 'add')
return writeAnimations([...list, ...[...ids].map(fresh)]);
if (picked !== undefined && list[picked] && holds(list[picked]))
return writeAnimations(
list.map((a, i) => (i === picked ? swap(a) : a))
);
const missing = [...ids].filter(
(id) => !list.some((a) => a.shapeId === id)
);
return writeAnimations([
...list.map((a) => (holds(a) ? swap(a) : a)),
...missing.map(fresh),
]);
}
);
/** Changes animations' timing or options. */
const updateAnimations = serial(
(indexes: number[], patch: Partial<AnimationSpec>) =>
writeAnimations(
animations().map((a, i) =>
indexes.includes(i) ? { ...specOf(a), ...patch } : specOf(a)
)
)
);
/** Moves an animation earlier (-1) or later (1) in the sequence. */
const moveAnimation = serial((index: number, delta: -1 | 1) => {
const list = animations().map(specOf);
const to = index + delta;
if (!list[index] || to < 0 || to >= list.length)
return Promise.resolve(null);
const [moved] = list.splice(index, 1);
list.splice(to, 0, moved);
return writeAnimations(list);
});
const removeAnimations = serial((indexes: number[]) =>
writeAnimations(
animations()
.map(specOf)
.filter((_, i) => !indexes.includes(i))
)
);
/**
* Effect Options ▸ Sequence: a text shape animates as one object, or
* paragraph by paragraph (one click each).
*/
const setSequence = serial((shape: ShapeOutline, byParagraph: boolean) => {
const list = animations().map(specOf);
const own = list.filter((a) => a.shapeId === shape.id);
const first = own[0];
if (!first) return Promise.resolve(null);
const at = list.indexOf(first);
const rest = list.filter((a) => a.shapeId !== shape.id);
const paragraphs = (shape.paragraphs ?? [])
.map((p, i) => ({ i, text: p.text }))
.filter((p) => p.text.trim() !== '')
.map((p) => p.i);
const replaced: AnimationSpec[] =
byParagraph && paragraphs.length > 0
? paragraphs.map((paragraph, n) => ({
...first,
paragraph,
start: n === 0 ? first.start : 'onClick',
}))
: [{ ...first, paragraph: undefined }];
const before = rest.slice(
0,
list.slice(0, at).filter((a) => a.shapeId !== shape.id).length
);
const after = rest.slice(before.length);
return writeAnimations([...before, ...replaced, ...after]);
});
// ---- pictures and effects (Picture Format, Shape and Text Effects) --------
/** The selected pictures, which picture commands act on. */
const pictures = () => targets().filter((s) => s.kind === 'picture');
/** Corrections, recolor, transparency, or a reset of every selected picture. */
const formatPicture = (change: PictureChange, group?: string) => {
const s = slide();
const list = pictures();
if (!s || list.length === 0) return Promise.resolve(null);
return apply(
[
{
op: 'formatPicture',
slide: s.id,
shapes: list.map((p) => p.id),
...change,
},
],
group
);
};
/** Crops each selected picture to edges (fractions of its image). */
const cropPictures = (
edges: (picture: ShapeOutline) => Partial<CropOutline>,
group?: string
) => {
const s = slide();
if (!s) return Promise.resolve(null);
return apply(
pictures().map((p) => ({
op: 'cropPicture' as const,
slide: s.id,
shape: p.id,
...edges(p),
})),
group
);
};
/** Crops each selected picture to the largest centered `ratio` (w/h) part. */
const cropToAspect = (ratio: number) =>
cropPictures((p) =>
aspectCrop(p.w, p.h, p.picture?.crop ?? NO_CROP, ratio)
);
/** Fills or fits each selected picture to its frame (Crop ▸ Fill / Fit). */
const fitPictures = (mode: 'fill' | 'fit') => {
const s = slide();
if (!s) return Promise.resolve(null);
return apply(
pictures().map((p) => ({
op: 'cropPicture' as const,
slide: s.id,
shape: p.id,
mode,
}))
);
};
/**
* Removes the pictures' adjustments and effects (Reset Picture); with
* `size`, their crop too, the frame growing back (Reset Picture & Size).
*/
const resetPictures = (size: boolean) => {
const s = slide();
const ids = pictures().map((p) => p.id);
if (!s || ids.length === 0) return Promise.resolve(null);
return apply([
size
? { op: 'formatPicture', slide: s.id, shapes: ids, reset: true }
: {
op: 'formatPicture',
slide: s.id,
shapes: ids,
brightness: 0,
contrast: 0,
recolor: 'none',
transparency: 0,
},
{
op: 'setShapeEffects',
slide: s.id,
shapes: ids,
shadow: 'none',
glow: 'none',
softEdge: 'none',
reflection: 'none',
},
]);
};
/** Shadow, glow, soft edges, or reflection of every selected shape, as one step. */
const setShapeEffects = (change: EffectsChange, group?: string) => {
const s = slide();
const list = targets();
if (!s || list.length === 0) return Promise.resolve(null);
return apply(
[
{
op: 'setShapeEffects',
slide: s.id,
shapes: list.map((x) => x.id),
...change,
},
],
group
);
};
/** Text shadow and glow of the selected text (whole shapes when none is). */
const setTextEffects = (change: Pick<RunPatch, 'shadow' | 'glow'>) =>
runs(change);
const pictureCommands = {
pictures,
formatPicture,
cropPictures,
cropToAspect,
fitPictures,
resetPictures,
setShapeEffects,
setTextEffects,
};
// ---- end pictures and effects -----------------------------------------------
return {
canEdit,
animate,
updateAnimations,
moveAnimation,
removeAnimations,
setSequence,
insertRows,
insertColumns,
deleteRows,
deleteColumns,
deleteTable,
cellsOf,
alignCells,
anchorCells,
formatCells,
tableOp,
mergeCells,
canMerge,
splitCells,
canSplit,
fillCells,
borderCells,
distributeRows,
distributeColumns,
setTableStyle,
setBorderPen,
cellSize,
setCellSize,
resizeGrid,
deleteSelection: () => editor.deleteSelected(),
duplicateSelection: () => editor.duplicateSelected(),
format,
paragraphStyle,
textActive,
toggle,
setFont,
setFontSize,
stepSize,
setTextColor,
setHighlight,
toggleBaseline,
clearFormatting,
setLink,
setCharSpacing,
linkTarget,
applyLink,
moveInZOrder,
renameShape,
setShapesHidden,
align,
setBullets,
toggleBullets,
toggleNumbering,
indent,
lineSpacing,
spacing,
body,
textDirection,
setTextDirection,
targets,
setFill,
fillColor,
setLine,
setGeometry,
arrange,
alignShapes,
rotate,
resize,
move,
setRotation,
styleShapes,
selectAll,
group,
ungroup,
mergeShapes,
setLayout,
setTransition,
setAltText,
setThemeColors,
setThemeFonts,
insertTextBox,
insertShape,
insertImage,
insertMedia,
insertTable,
replaceImage,
formatChart,
setChartType,
setChartData,
insertChart,
goToSlideId,
addSlide,
duplicateSlide,
deleteSlides,
toggleHidden,
moveSlide,
moveSlides,
setBackground,
applyBackgroundToAll,
paragraphs,
apply,
// ---- deck setup: header & footer, slide size, sections ----
...createDeckCommands({ apply, outline: session.outline }),
...pictureCommands,
};
}
export type EditorCommands = ReturnType<typeof createEditorCommands>;
/** The fields of a `formatPicture` op a command sets. */
export type PictureChange = Omit<
Extract<EditOp, { op: 'formatPicture' }>,
'op' | 'slide' | 'shapes'
>;
/** The fields of a `setShapeEffects` op a command sets. */
export type EffectsChange = Omit<
Extract<EditOp, { op: 'setShapeEffects' }>,
'op' | 'slide' | 'shapes'
>;