Skip to Content
PackagesCoreCommandsCommands: 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 text blocks whose effective alignment is one of applyOnAlignments. The effective alignment is the block’s own textAlign, else its style’s (left/right read as start/end), else start. 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 lineHeightAtLeast 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 lineHeightAtLeast.

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;
}): 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