@nextgensoftwares/folio-plugin-callout

Callout / admonition blocks. Guide: Callouts.

Plugin

Export	Signature	Description
calloutPlugin	(options?: CalloutPluginOptions) => FolioPlugin	schema, renderer, painters, commands, keymap, UI items, exporters.pdf / exporters.docx
type CalloutPluginOptions		CalloutRendererOptions and NestOptions plus wrapKey?: string | false (default Mod-Alt-k), toolbar?: boolean, slash?: boolean
type NestOptions		{ allowNested?: boolean } (default false: no callout inside a callout)

Schema and attributes

Export	Description
calloutSpec	NodeSpec: group: 'block', content: 'block+', attrs CALLOUT_ATTRS
CALLOUT_ATTRS	variant, tone (legacy alias), title, icon, appearance, fill, border, accent, collapsible, dir, each with a validator
type CalloutAttrName	keys of CALLOUT_ATTRS
TITLE_MAX	200 characters
validAttr(name, value)	true when the value is acceptable for that attribute
cleanAttrs(patch)	keeps declared, valid attributes only
resolveCallout(attrs, dark?)	ResolvedCallout: variant, appearance, icon, title, colours, collapsible, dir, with fallbacks for missing or invalid values
type ResolvedCallout	{ variant, appearance, icon: CalloutIconName | null, title: string | null, colors: CalloutColors, collapsible, dir }
variantOf(attrs)	effective variant (tone wins while set)

Variants, styles and colours

Export	Description
VARIANTS, type CalloutVariant	info, note, tip, success, warning, danger, quote, custom
APPEARANCES, type CalloutAppearance	soft, outline, accent
VARIANT_STYLES, type VariantStyle	per variant: label, icon, default appearance, light and dark CalloutColors
type CalloutColors	{ fill, border, accent, title }
isVariant(v), isAppearance(v)	type guards
type PaletteChoice	'auto' | 'light' | 'dark'
parseCssColor(v), type Rgba	hex, rgb()/rgba(), hsl()/hsla() and common names → [r, g, b, a], else null
isCssColor(v)	accepted by parseCssColor
toHex(v)	#rrggbb (alpha dropped) or null
luminance(v)	WCAG relative luminance, or null

Icons

Export	Description
CALLOUT_ICONS, type CalloutIconName	the safe set: info, note, tip, success, warning, danger, quote, star, question, flag, bookmark, heart (24×24 stroke paths, absolute M/L/C/Z only)
ICON_NAMES, isIconName(v)	names; type guard
iconPath(name)	one SVG d string (usable as a UI item icon)
parsePath(d), type PathOp	the path subset as operations (used for PDF drawing)

Layout

Export	Signature	Description
createCalloutRenderer	(options?: CalloutRendererOptions) => BlockRenderer	padded children, title and icon, page-split box
calloutRenderer	BlockRenderer	with default options
type CalloutRendererOptions		palette?: PaletteChoice (default auto), metrics?: Partial<CalloutMetrics>
type CalloutMetrics, DEFAULT_METRICS		padX, padY, icon, iconGap, radius, accentRadius, border, outline, accentWidth, titleGap (px)
type CapAttrs, type CapIcon		attrs of a calloutCap custom fragment (one rounded end; the top one carries the icon)
isDarkTheme(theme)	(theme: Theme) => boolean	body text lighter than mid-grey

Fragments: rect roles callout (fill), callout-border, callout-accent; custom type calloutCap (the rounded ends; the top one also draws the icon, so no hit-test atom sits beside the text); the title is decorative lines.

Commands and keys

Export	Signature	Description
calloutAt	(state) => CalloutRef | null	the selection's callout: the selected one, else the innermost holding the whole selection, else the one at a crossing range's start/end
insideCallout	($pos) => boolean	any callout ancestor
wouldNest	(range: NodeRange) => boolean	wrapping the range would put a callout in a callout
nestedCallouts	(doc) => CalloutRef[]	callouts inside callouts, in document order
type CalloutRef		{ node, pos, depth }
insertCallout	(attrs?, opts?: NestOptions) => Command	wraps a selection or an empty line, else inserts after the current block; inside a callout it restyles it (unless allowNested)
wrapInCallout	(attrs?, opts?: NestOptions) => Command	wraps the selected blocks (widens to a whole list when needed); refuses to nest unless allowNested
unwrapCallout	() => Command	content back to plain blocks; a title becomes a bold paragraph
toggleCallout	(attrs?, opts?) => Command	unwrap inside (or touching) a callout, else wrap (Mod-Alt-K)
flattenNestedCallouts	() => Command	repair: unwraps every callout inside a callout into its parent
unwrapInto, unwrapTr	(tr, ref) => Transaction, (state, ref) => Transaction	the unwrap step (title → bold paragraph)
removeCallout	() => Command	deletes the callout and its content
setCalloutAttrs	(patch) => Command	merges validated attributes
setCalloutVariant	(variant) => Command	clears custom colours and tone
setCalloutAppearance, setCalloutIcon, setCalloutTitle, toggleCalloutTitle, setCalloutColors, toggleCalloutCollapsible	Command factories
calloutBackspace	Command	at the start of the first block: unwrap
calloutEnter	Command	empty last line: leave the callout; other empty lines: add a line

UI

Export	Description
barItems()	context-bar items (defaultSurfaces: ['contextBar']) with rich render controls and children fallbacks
contextMenuItems(bar, opts?)	a "Callout" submenu with the same entries, plus "Wrap in callout" and "Merge nested callouts" (repair, shown in a nested callout)
toolbarItems(opts?)	Insert group menu of variants (restyles when inside a callout; the current variant is marked)
slashItems(opts?)	/callout, /warning callout…
inCalloutContext(state)	the bar's visibility rule (not over a nested table or a selected image)
VariantControl, AppearanceControl, IconControl, TitleControl, ColorsControl	React controls (UIRenderProps)
FILL_PALETTE, ACCENT_PALETTE	colour picker swatches

Painters and export

Export	Description
calloutPainters	@nextgensoftwares/folio-react painters: calloutCap, rect:callout-border, rect:callout-accent
CalloutCapPainter, CalloutLinePainter, CalloutIconSvg	the components
calloutPdfPainters, calloutCapPdf	exporters.pdf entry for calloutCap (vector paths)
iconPdfOps(name, color, x, y, size)	PDF operators for an icon of the safe set
type CalloutPdfContext, type CalloutPdfPainter	structural subset of export-pdf's paint context
calloutDocx, calloutDocxExporters	exporters.docx: a one-cell table
createCalloutDocx(metrics?)	factory behind calloutDocx: the DOCX exporter with the renderer's box metrics (Partial<CalloutMetrics>: padding, border, bar widths) so Word matches the screen; unset metrics use the defaults
type CalloutDocxContext, type CalloutDocxExporter	structural subset of export-docx's context
ICON_GLYPHS	symbols standing in for icons in Word