@nextgensoftwares/folio-plugin-layers

Layered pages: positioned shapes, text boxes, pictures and groups with Word's wrap modes and z-order, page backgrounds and borders, section master objects and page objects. Guide: Layered pages.

Plugin

Export	Signature	Description
layersPlugin	(options?: LayersPluginOptions) => LayersPlugin	schema, drawing renderer, painters, page layers, wrapLayout, commands, keymap, UI items, overlay and sidebar slots, exporters.pdf / .canvas / .docx
type LayersPluginOptions		resolveSrc? (stored image src → URL, e.g. plugin-media's), insert?: boolean (toolbar Shapes menu, default true), sidebar?: boolean | { slot?, order?, label? } (Format shape panel, default the sidebar slot)
type LayersPlugin		FolioPlugin plus pageLayers and controller: LayersController
LAYER_ICONS		SVG path icons of the plugin's items (shapes, textBox, editText, wrap, arrange, format)

Schema

Export	Description
DRAWING, drawingSpec	the drawing block node (atom): object (a validated DrawingObject), wrap, float (side), alignment, distT/B/L/R, relH (column/margin/page), relV (paragraph/margin/page), offsetX/Y, z, lockAnchor
WRAPS	inline, square, tight, through, topBottom, behind, front
layersSchema	the node plus the layers document attribute
isDrawingObject(v), isLayersSettings(v)	attr validators: true when the value is exactly what the sanitizers would store
LAYERS_ATTR	'layers': page-level settings on doc.attrs

Object model

Export	Description
type DrawingObject	ShapeObject | ImageObject | GroupObject
type ObjectBase	id, x, y, w, h, rot? (degrees, clockwise), flipH?, flipV?, opacity?, name?, locked?
type ShapeObject	geom: Geometry, fill?, stroke? (null = none), shadow?, text?: TextBody
type ImageObject	src, alt?, crop? ({ l, t, r, b } fractions), geom? (clip outline), stroke?
type GroupObject	children, child space cx?, cy?, cw?, ch? (DrawingML chOff/chExt)
type Geometry, PRESETS, type Preset	DrawingML preset name (rect, roundRect, ellipse, stars, arrows, callouts, line...) or custom (path SVG data in a pw × ph box); adj adjustments (radius, inner, tailX/Y, head, shaft, inset)
type Fill, type GradientStop	none, solid, gradient (linear with angle / radial), image
type Stroke, type Dash, type ArrowEnd	colour, width, dash, line ends (arrow, triangle, oval, diamond)
type Shadow	color, blur, dx, dy
type TextBody	content (Folio blocks), pad?, vAlign?, autofit? (none/grow/shrink), next? (linked box id: any text box of the document, in another drawing or on another page), dir?
type LayerWrap	the seven wrap modes (tight and through follow the object's outline)
type LayersSettings, type SectionLayers, type PageBackground, type PageBorder, type PlacedObject, type PlacedWrap, type PageObject	page-level layers: per-section background, border, masters (hideMastersOnFirst), page objects by page number or section first page, hideMasters; a placed object's wrap? (square, tight, through, topBottom), dist? (top, right, bottom, left) and side? (both, left, right) make the body text wrap around it

Validation (untrusted input)

Export	Description
sanitizeObject(raw, taken?)	a valid object tree or null: known fields only, clamped numbers, canonical colours, checked paths and sources, bounded counts/nesting/text (LIMITS), unique ids
readObject(raw)	sanitizeObject memoized by identity (layout and painters read through it)
sanitizeSettings(raw), readSettings(raw)	the same for page-level settings
sanitizeFill, sanitizeStroke, sanitizeShadow, sanitizeText, sanitizeGeometry	field validators
sanitizeContent(raw), contentText(blocks), paragraphOf(text?)	text bodies
isSafeSrc(v), newId(prefix?)	image source check (http(s), data: images, blob:, paths, host schemes); fresh ids
LIMITS	objects 500, depth 8, coordinates 20,000 px, 16 gradient stops, 400 text blocks / 200,000 characters, data: images 30 M characters...
parseColor, normalizeColor, isColor, docxHex, alphaOf, type Rgba	the colour syntaxes accepted (hex, rgb(a), a few names)

Creating objects

Export	Description
SHAPE_GALLERY, type GalleryItem	Insert ▸ Shapes entries in Word's order (lines, basic shapes, arrows, stars, callouts) with default sizes
createShape(item, overrides?), DEFAULT_SHAPE_STYLE	a shape with Word's default look (blue fill, darker outline; lines: stroke + ends)
createTextBox(content?, w?, h?, overrides?)	Word's Insert ▸ Text Box (white fill, thin outline, text at the top)
createImage(src, w, h, overrides?), createGroup(children, w, h)	pictures and groups
shapeText(text?)	centred white text for a shape

Tree and geometry

Export	Description
walk, findObject, pathTo, updateObject, idsOf, countObjects, jsonEqual	tree helpers (updates keep untouched subtrees' identity)
geometryPath(g, w, h), ellipsePath, roundRectPath	outlines as PathCmd[], shared by every renderer
parsePath, toSvgPath, toPdfPath, scalePath, isPathData, isOpenPath, PATH_LIMITS, type PathCmd	SVG path data ↔ absolute M/L/C/Z commands
arrowHeads(cmds, stroke), dashArray(stroke)	line ends as filled paths; dash patterns
boxMatrix, boundsOf, rotatedBounds, multiply, invert, applyMatrix, cssMatrix, IDENTITY, type Matrix	2D affine helpers
wrapOutline(root), flattenPath(cmds, m?)	the tight-wrap outline of a drawing (its shape outline, rotated; a group's convex hull) and path flattening (curves sampled)

Layout

Export	Description
drawingRenderer	the drawing block renderer: inline/reflow blocks, top-and-bottom blocks, square floats and tight/through floats (polygon exclusions from the outline), behind/front overlays from the paragraph, margin (the text area, also in columns) or page edge
layersRenderer, layersPageObjects	the renderer the plugin registers: drawingRenderer carrying pageObjects (masters and page objects as layout page objects: z stacks shared with anchored drawings, text wraps around wrapped ones)
objectsOnPage, sectionOfPage, placedFragment, placedZone, outlineOf	page objects of a page, their fragments and wrap zones, a view's outline (memoized)
threadDocument, THREAD_IN, type ThreadIn, overflowOf, threadRemainder, sliceTextblock, type ThreadBox	text threads across drawings and pages: the layout-only threadIn attr, what each box leaves the next (content, re-laid out at the next box's width; paragraphs continue mid-paragraph)
viewFor(object, ctx), buildView, objectBoxes, type DrawingView, type ObjectView	the resolved drawing (matrices, outlines, laid-out text), memoized by object/theme/measurer
drawingFragment, DRAWING_FRAGMENT, type DrawingFragmentAttrs, type DrawingSource	the layers.drawing custom fragment
drawingPlacement, type DrawingPlacement, isPositioned, affectsText	placement attrs with Word's defaults
layoutText, measureText, splitFlow, DEFAULT_PAD, type TextView	text bodies: insets, autofit, vertical alignment, overflow, linked boxes
pageLayerFragments(page, z), attachPageLayers, pageLayersInput, pageSection, pageObjectsOf, sectionLayers, type PageLayersInput, BACKGROUND_FRAGMENT, BORDER_FRAGMENT	page-level layers per page (background and border; masters and page objects are in page.fragments); pageObjectsOf(page) lists a laid-out page's masters and page objects

Commands (one transaction, one undo step each)

Export	Description
type ObjectRef, type Holder, readHolder, writeHolder, updateRef, settingsOf, writeSettings, sameHolder	addressing an object in a drawing node, a master or a page object
type Frame, type DrawingGeo, frameOf, childAt, chainMatrix, resizedRoot	page-space frames ↔ stored geometry (through groups' child spaces)
setFrame, setFrames, applyFrame	move / resize / rotate (roots change anchor offsets, and an anchored drawing dragged over another paragraph is re-anchored to it unless lockAnchor; children change in their group)
setObjectProps, type ObjectPatch, setPlacement, deleteObjects, insertDrawing, applyText	style, placement, delete, insert, text
arrangeZ, type ZMove, alignFrames, distributeFrames, arrangeFrames, type AlignMode, visualBox	z-order, align, distribute
groupObjects, ungroupObject, type Selected	group / ungroup

Interaction

Export	Description
class LayersController, type SelectedObject, type Resolved, type Preview	selection, drag preview, guides, marquee, master mode, text editing state
hitDrawing, drawingsOn, objectAt, originOf, isDrawing, textAt, type PlacedDrawing	hit testing in Word's order (front, flow, behind where no text)
snapMove, snapTargets, snapAngle, resizeFrame, type SnapTargets, type Handle, type Box	smart guides, 15° steps, handle resizing
class TextSession, type TextTarget, startTextEditing, canHoldText	in-place text editing (an editor delegate, like header editing): rotated boxes stay rotated and shrink-to-fit text is edited at its displayed size; carets and selection boxes carry the box transform (Caret.matrix)
layersKeymap(ctrl)	arrows nudge, Delete, Escape, Tab, Enter, Mod-G / Mod-Shift-G
insertItems, objectItems, insertObject	UI items
createOverlay, layersHook, noteAltPress	the overlay slot component, its pointer hook, and the Alt state of a press (Alt+drag = marquee)
startMove, startResize, startRotate, startMarquee, marqueePick, marqueeSelect, pageMapper, type GestureEnv	pointer gestures (one transaction on release) and the rubber band's selection
createPainters, createDrawingPainter, ObjectNode, ResolveContext, useImageSrc, type SrcResolver	React painters
FormatPanel, createFormatControl, useLayers, WRAP_OPTIONS	Format shape panel

Output

Export	Description
paintPlan, type PaintStep, fragmentMatrix, imageBox, gradientAt	the drawing as steps shared by PDF and canvas
drawingPdf, backgroundPdf, borderPdf, layersPdfPainters, type LayersPdfContext	vector PDF
drawingCanvas, backgroundCanvas, borderCanvas, layersCanvasPainters, type LayersCanvasContext	canvas
drawingDocx, drawingRun, floatingOf, Z_BASE	DOCX DrawingML (wps:wsp + wps:txbx, wpg:wgp, wp:anchor with wrap, behindDoc, relativeHeight)
shapeOptions, fillOf, lineOf, groupChildren, type LayersDocxContext	the docx/shapes options builders
docxPageLayers, DOCX_PAGE_FRAGMENT	page-level layers as header shapes (masters keep their wrap)
docxPageObjects, DOCX_PAGE_OBJECTS, placedRun	page objects anchored (from the page edge) in a paragraph on their page (attrs.anchor: 'body'; needs layout in the DOCX export)