Skip to Content
CommandsCommands: Formatting

Commands: Formatting

Paragraph-level commands: alignment, direction, spacing, line height, indentation and pagination attributes. Unless noted, they act on the blocks in the selection. null in an attr means “inherit from the stylesheet”.

import { setTextAlign, setSpacing, indent, outdent, setLineHeight } from "@stesura/core/commands";

Text Alignment

Alignment values are logical: "start" and "end" follow the block’s text direction.

setTextAlign

Set textAlign on the blocks in the selection. Returns false when the selection holds no textblock.

setTextAlign(align: "justify" | "start" | "end" | "center"): Command

setTextAlignOnlyOn

Rewrite textAlign across the whole document, but only on blocks currently set to one of applyOnAlignments. Returns false when no block matches.

setTextAlignOnlyOn({
  applyOnAlignments: string[],
  newAlignment: string
}): Command

Two prebuilt factories: alignJustifyLeftRight() justifies every start- or end-aligned block, and alignJustifyLeftOnly() justifies every start-aligned block.

resetAlignment

Clear textAlign back to the stylesheet. With no ids it acts on the selection; with ids it acts on every node in the document whose id or styleId is in the list.

resetAlignment(ids?: string[]): Command

Direction

setDirection

Set the dir attr on the blocks in the selection. null clears the override, so direction inherits from the section, then the document.

setDirection(dir: "ltr" | "rtl" | null): Command

setDocDirection(dir) sets the document-level default.

toggleDirection

Flip the selection’s resolved direction (the one the toolbar shows). It writes null when the target matches what the block would inherit anyway.

toggleDirection: Command

Spacing

Spacing values are in px.

setSpacing

Merge before/after spacing into the blocks in the selection. Sides you don’t pass keep their current value. When a whole table is selected, only the table is written.

setSpacing(spacing: { before?: number | null; after?: number | null; contextual?: boolean | null }): Command

contextual is Word’s “don’t add space between paragraphs of the same style”.

setSpacingBeforeAfter

Set spacing on one side, leaving the other untouched.

setSpacingBeforeAfter({
  position: "before" | "after",
  value: number
}): Command

incrementSpacing

Add value to the effective spacing on one side (resolved through the stylesheet), floored at 0. Only that side is written.

incrementSpacing({
  position: "before" | "after",
  value: number  // negative to decrease
}): Command

resetSpacing

Clear spacing, lineHeight and lineHeightRule back to the stylesheet. ids works as in resetAlignment.

resetSpacing(ids?: string[]): Command

Line Height

setLineHeight

Set lineHeight on the blocks in the selection, clearing lineHeightRule.

setLineHeight(lineHeight: number): Command
// Common values: 1, 1.15, 1.5, 2, 3

resetLineHeight

Clear the lineHeight override in the selection, back to the stylesheet.

resetLineHeight: Command

Indentation

indent

Indent by one step (0.5in), Word-style. A block without a first-line indent gets one first; later presses move the whole block, up to 8 steps. On a numbered block it demotes the list level instead and leaves the paragraph indent alone, since the level definition supplies it.

indent: Command

outdent

Reverse one indent step: the first-line indent goes first, then start. On a numbered block it promotes the list level. Returns false once the block is fully outdented.

outdent: Command

resetIndent

Clear the indent attr back to the stylesheet. ids works as in resetAlignment.

resetIndent(ids?: string[]): Command

Complete Formatting

setFormatting

Merge a partial indent attr into every block in the selection (values in px). Keys you don’t pass keep their current value. You can also pass a resolver, which is called per block with that block’s resolved indent. When a whole table is selected, only the table is written.

setFormatting(
  update:
    | Partial<IndentAttrs>
    | ((current: ResolvedIndentAttrs) => Partial<IndentAttrs>)
): Command
 
type IndentAttrs = {
  start?: number | null;   // indent from the start edge
  end?: number | null;     // indent from the end edge
  special?: "none" | "first-line" | "hanging" | null;
  by?: number | null;      // amount for the special indent
};

Pagination Attributes

setPaginationAttrs

Merge pagination overrides into the selected blocks. null for a key clears that override so it inherits from the stylesheet again. When every key ends up null, the attr collapses back to null.

setPaginationAttrs(partial: {
  widowOrphan?: boolean | null;
  pageBreakBefore?: boolean | null;
  keepWithNext?: boolean | null;
  keepLines?: boolean | null; // kept for DOCX round trips; pagination doesn't honor it yet
}): Command

resetPagination

Clear every pagination override in the selection.

resetPagination(): Command

Transaction Variants

@stesura/core/commands/internal exports *Tr variants. That entry point is not public API.

setTextAlignTr(align): TransactionFn
setSpacingTr(spacing): TransactionFn
setSpacingBeforeAfterTr({ position, value }): TransactionFn
incrementSpacingTr({ position, value }): TransactionFn
setLineHeightTr(lineHeight): TransactionFn
setFormattingTr(formatting): TransactionFn

Example: Apply Heading Style

To group commands, use composeCommands:

import { composeCommands, setTextAlign, setSpacing, setLineHeight } from "@stesura/core/commands";
 
const applyHeadingStyle = composeCommands(
  setTextAlign("center"),
  setSpacing({ before: 24, after: 12 }),
  setLineHeight(1.5)
);

Next Steps

Last updated on
Commands: CoreCommands: Highlight & Links