API reference

Every export of active-helpers, per entry point - the package's own reference, and every export generated from the source.

Three subpaths, no root entry point. Every module is dependency-free and runs in any JavaScript runtime (browser, Node.js, worker). The source TSDoc is the detailed contract; this page lists every export and what it guarantees.

`./serialization`#

Machine serialization for exports. Nothing here depends on a language: a value is written the way a file or a clipboard needs it, not the way a reader reads it.

neutralizeFormula

Kind: function

(text: string) => string. Prefixes an apostrophe when a spreadsheet would otherwise execute the value: two or more characters starting with = or @, or with + or - followed by text, or by digits and an operator. A lone sign, and a signed plain number such as -12, stay unchanged.

DEFAULT_CSV_DELIMITER

Kind: constant

',': the RFC 4180 delimiter, used when a caller names none.

csvField

Kind: function

(value: unknown) => string. One CSV field: formula-neutralized and always quoted (embedded quotes doubled, newlines kept), so it is safe with any delimiter. null and undefined become empty text.

csvRow

Kind: function

(values: readonly unknown[], delimiter?: string) => string. The fields of csvField joined with delimiter (default DEFAULT_CSV_DELIMITER), verbatim: which delimiters a user may choose is the caller's policy.

tsvField

Kind: function

(value: unknown) => string. One TSV field: formula-neutralized, quoted only when a tab, newline or quote would break the structure; never stripped or replaced.

tsvRow

Kind: function

(values: readonly unknown[]) => string. The fields of tsvField joined with a tab.

serializeDecimals

Kind: function

<T>(obj: T) => T. Replaces every Decimal.js-style instance (an object with toNumber() and the fields d, e and s) by toNumber(), recursively through arrays and objects, so a query result crosses a server-to-client boundary. Lossy beyond double precision. Date and RegExp are returned unchanged.

`./export-fonts`#

The backend-neutral mechanics of an embedded-font PDF export with a jsPDF-class backend (no shaping, no bidi, UTF-16 code units). How a product loads, parses and draws fonts stays with the product.

PdfFontBucket

Kind: type

'normal' | 'bold' | 'italic' | 'bolditalic': the four styles such a backend registers per family.

PDF_FONT_BUCKETS

Kind: constant

Every bucket, regular first.

pdfFontBucket

Kind: function

The bucket of a CSS weight and style: weight 600 and up is bold.

resolvePdfFontBucket

Kind: function

(available, requested): the bucket a family draws requested in: the exact bucket, else the same style in the other weight, else the same weight in the other style, else regular; undefined when the family has no regular face. Nothing is synthesised.

FontByteFormat

Kind: type

What the leading bytes of a font file say it is.

classifyFontBytes

Kind: function

(bytes: Uint8Array) => FontByteFormat. Classifies by signature without parsing. Only truetype is embeddable; CFF OpenType, WOFF, WOFF2 and collections are recognised so a refusal can name them. Fewer than twelve bytes is unknown.

isWinAnsiCodePoint

Kind: function

Whether a PDF standard font with WinAnsi encoding can draw a code point.

isCollapsedWhitespace

Kind: function

Tab, line feed and carriage return: collapsed to spaces, never drawn.

PdfTextRefusalReason

Kind: type

'complex-script' | 'combining-mark' | 'joiner-or-selector' | 'emoji' | 'supplementary-plane'.

PdfTextRefusal

Kind: type

The first code point a backend cannot draw, why, the script (for complex-script) and, for combining-mark, whether NFC would remove every mark.

findPdfTextRefusal

Kind: function

(text: string) => PdfTextRefusal | null. The first code point that a backend without shaping cannot draw, or null. Never returns the text itself.

PdfTextSegment

Kind: type

One run of a text unit, drawn in one bucket.

CoveringFamilyResult

Kind: type

{covered: true; index} or {covered: false; codePoint}.

selectCoveringFamily

Kind: function

(segments, families, covers): the first family, in the host's order, that covers every drawn code point of a unit in the bucket each segment is drawn in. One unit is drawn in one family; there is no per-glyph fallback.

`./menu-items`#

The menu item contract and the one resolution every Active menu runs through before it renders. How a menu renders, and what an action receives, stays with the product.

MenuSeparator

Kind: type

'separator': a line between groups.

MenuEntry<TArg, TIcon>

Kind: interface

label, action, icon, variant ('default' | 'destructive'), disabled with disabledReason, shortcut, keepOpen, visible(arg), separatorBefore, children.

MenuItem<TArg, TIcon>

Kind: type

MenuSeparator | MenuEntry<TArg, TIcon>.

MenuEntryShape<TArg>

Kind: interface

The part of an entry the pipeline reads; a product's own entry type satisfies it structurally.

ResolveMenuOptions<TEntry, TArg>

Kind: interface

arg (what visible is evaluated against; absent, visible is not evaluated) and keep(entry) (a product's own filter, asked first).

normalizeMenuSeparators

Kind: function

Drops separators that no longer separate anything: no leading, trailing or doubled line. Order is preserved.

ensureDestructiveTailSeparator

Kind: function

When a menu ends on destructive entries, puts one line before that tail (within the last segment). Idempotent.

resolveMenuItems

Kind: function

The pipeline, at every submenu depth: filter (keep, then visible), expand separatorBefore into lines, give the destructive tail its line, clean up the lines. Idempotent. A submenu whose children all filter away keeps its trigger with an empty children.

All exports, from the source#

`@workspace/active-helpers/serialization`#

Functions, hooks and constants

csvField

Type: (value: unknown) => string

Render one CSV field. Always quoted, header fields included, so a header containing the delimiter cannot produce more columns than the data rows. Embedded quotes are doubled per RFC 4180; embedded newlines are legal inside a quoted field and are kept as-is, so multi-line cell content survives the round trip.

Quoting is UNCONDITIONAL and therefore delimiter-independent: a field that contains the separator, a quote or a newline is already safe whichever separator the row ends up joined with. That is why this function takes no delimiter — there is no decision here that depends on one.

csvRow

Render one CSV row from its fields.

delimiter is the separator between fields and defaults to a comma. It is joined verbatim: the caller owns which separators it permits, because "which delimiter may a user choose" is a product question and this is the serialisation boundary. What the boundary DOES guarantee is that any separator is safe — see csvField on unconditional quoting.

(values: readonly unknown[], delimiter?: string) => string

DEFAULT_CSV_DELIMITER

Type: ","

The delimiter a CSV row uses when the caller names none: RFC 4180's comma.

neutralizeFormula

Type: (text: string) => string

Prefix a leading apostrophe when a spreadsheet would otherwise execute the value. Measured: the apostrophe is NOT consumed on either the CSV or the paste route, so it stays visible in the cell. That is accepted — it reads as a deliberate marker, where a leading space would read as a defect.

tsvField

Type: (value: unknown) => string

Render one clipboard TSV field.

Quoting on the paste route was MEASURED to be honoured by Excel and to be lossless: "mid<TAB>dle" arrives as one cell containing the tab, a quoted newline stays inside its cell, and "plain" arrives without its quotes. That is why this does not strip or replace anything: collapsing tab, CR or LF to a space would be a silent, lossy data change.

Quoting is MINIMAL: only fields that would otherwise break the structure are quoted, so plain values stay plain when pasted into a text editor. A field containing a " is quoted too — an unquoted field starting with a quote was measured to swallow the following delimiter and merge two columns.

tsvRow

Type: (values: readonly unknown[]) => string

Render one clipboard TSV row from its fields.

serializeDecimals

Type: <T>(obj: T) => T

Recursively convert decimal.js instances (Prisma Decimal) to plain numbers, so a query result can cross the server-to-client boundary, which does not serialize class instances. The conversion is toNumber() and therefore lossy beyond double precision; a caller that needs exact digits must convert to a string itself.

Arrays and plain objects are rebuilt recursively (a __proto__ key stays an own property); Date and RegExp instances are returned unchanged.

`@workspace/active-helpers/export-fonts`#

Functions, hooks and constants

PDF_FONT_BUCKETS

Type: readonly PdfFontBucket[]

Every bucket, regular first.

pdfFontBucket

The bucket of a CSS weight and style: weight 600 and up is bold, the rest normal (the rule the charts' PDF export has kept since FAM-V2-T6).

(weight: number, style: "normal" | "italic") => PdfFontBucket

resolvePdfFontBucket

The bucket a family draws requested in, given the buckets it has: the exact bucket, else the same style in the other weight, else the same weight in the other style, else regular. Nothing is synthesised: a family without bold draws bold text in its regular face. undefined only when the family has no regular face either.

(available: ReadonlySet<PdfFontBucket>, requested: PdfFontBucket) => PdfFontBucket | undefined

classifyFontBytes

Type: (bytes: Uint8Array) => FontByteFormat

Classifies font bytes by their signature, without parsing them. Only truetype (00 01 00 00 or true) is embeddable by a jsPDF-class backend; CFF-flavoured OpenType (OTTO), WOFF, WOFF2 and collections (ttcf) are recognised so a refusal can name them. Fewer than twelve bytes (an sfnt header) is unknown.

isWinAnsiCodePoint

Type: (codePoint: number) => boolean

Whether a PDF standard font (Helvetica, Times, Courier with WinAnsi encoding) can draw codePoint: printable ASCII, U+00A0–U+00FF and the twenty-seven Windows-1252 additions (€, curly quotes, dashes, …).

isCollapsedWhitespace

Type: (codePoint: number) => boolean

Tab, line feed and carriage return: SVG and table text collapses them to spaces, so they are never drawn and need no glyph.

findPdfTextRefusal

Type: (text: string) => PdfTextRefusal | null

The first code point of text that a PDF backend without shaping, bidi and supplementary-plane encoding cannot draw correctly, or null.

Refused, in this order per code point: emoji (default emoji presentation, or a supplementary-plane pictograph; a text-presentation pictograph such as ©, ® or ™ stays text), joiners and variation selectors (ZWNJ, ZWJ, VS1–VS256), a complex or right-to-left script (the list above, and conjoining Hangul jamo), any combining mark, and any code point beyond the Basic Multilingual Plane. Everything else is left to glyph coverage.

The analysis reads the text as it will be drawn. NFC is used only to tell the host whether a refused combining mark would compose away.

selectCoveringFamily

The first family, in the host's order, that covers EVERY drawn code point of a text unit in the bucket each segment is drawn in. One unit is drawn in one family: there is no per-glyph fallback, so a unit that mixes scripts needs one family that covers all of them.

covers(family, bucket, codePoint) answers for the face the family draws bucket in. Collapsed whitespace (tab, LF, CR) needs no glyph.

<F>(segments: readonly PdfTextSegment[], families: readonly F[], covers: (family: F, bucket: PdfFontBucket, codePoint: number) => boolean) => CoveringFamilyResult

Types

PdfFontBucket

The four styles a jsPDF-class backend registers per family.

type PdfFontBucket = 'normal' | 'bold' | 'italic' | 'bolditalic';

FontByteFormat

What the leading bytes of a font file say it is.

type FontByteFormat =
  'truetype' | 'cff' | 'woff' | 'woff2' | 'collection' | 'unknown';

PdfTextRefusalReason

Why a PDF backend without shaping cannot draw a text.

type PdfTextRefusalReason =
  | 'complex-script'
  | 'combining-mark'
  | 'joiner-or-selector'
  | 'emoji'
  | 'supplementary-plane';

PdfTextRefusal

The first code point of a text that a PDF backend cannot draw, and why.

interface PdfTextRefusal {
  reason: PdfTextRefusalReason;
  codePoint: number;
  script?: string;
  normalizable?: boolean;
}

PdfTextSegment

One run of a text unit, drawn in one requested bucket.

interface PdfTextSegment {
  text: string;
  bucket: PdfFontBucket;
}

CoveringFamilyResult

The outcome of selectCoveringFamily.

type CoveringFamilyResult =
  | {covered: true; index: number}
  | {
      covered: false;
      codePoint: number;
    };

`@workspace/active-helpers/menu-items`#

Functions, hooks and constants

normalizeMenuSeparators

Drop separators that no longer separate anything: no leading separator, no trailing separator, never two in a row.

A caller declares separators between groups, then filtering removes the entries a viewer may not see or that are not relevant; without this, the menus seen least often open on a rule, end on one, or show two with nothing between them. Order is preserved; only separators are removed.

<TEntry>(items: ReadonlyArray<MenuSeparator | TEntry>) => Array<MenuSeparator | TEntry>

ensureDestructiveTailSeparator

THE DESTRUCTIVE TAIL GETS ITS SEPARATOR, even without a declaration.

A menu that ends in destructive entries is separated from the ordinary entries above by one line. Only within the last segment (after the last line the caller set), the tail is the run from the FIRST destructive entry, provided the menu ends on a destructive entry: so a mixed lifecycle group (Delete → Restore → Delete permanently) stays one group.

It does nothing when the menu does not end on a destructive entry (only the caller knows that boundary: separatorBefore), when the segment already begins at the tail, or when nothing stands before the tail. It only adds a line, and running it twice changes nothing further.

<TEntry extends { variant?: "default" | "destructive"; }>(items: ReadonlyArray<MenuSeparator | TEntry>) => Array<MenuSeparator | TEntry>

resolveMenuItems

THE ONE PIPELINE. Four steps, in this order, at every submenu depth:

1. filter: the product's keep, then visible against arg; 2. expand `separatorBefore` into lines; 3. give the destructive tail its line; 4. clean up: no leading, trailing or doubled line.

Filtering comes first because filtering orphans lines. A submenu whose children all filter away keeps its trigger with an empty children; a renderer renders an entry with no children as an ordinary entry.

It is idempotent, so a product may run it in a factory and again at its renderer boundary over whatever it receives.

<TEntry extends MenuEntryShape<TArg>, TArg>(items: ReadonlyArray<MenuSeparator | TEntry>, options?: ResolveMenuOptions<TEntry, TArg>) => Array<MenuSeparator | TEntry>

Types

MenuEntry

The fields every Active menu entry shares, with the same meaning in every product. TArg is what the product's actions and predicates receive (a grid row, a chart menu context); TIcon the product's icon type.

interface MenuEntry<TArg, TIcon = unknown> {
  label: string;
  action?: (arg: TArg) => void;
  icon?: TIcon;
  variant?: 'default' | 'destructive';
  disabled?: boolean;
  disabledReason?: string;
  shortcut?: string;
  keepOpen?: boolean;
  visible?: (arg: TArg) => boolean;
  separatorBefore?: boolean;
  children?: MenuItem<TArg, TIcon>[];
}

MenuEntryShape

The part of an entry the pipeline reads. A product's own entry type (with its extra fields) satisfies it structurally.

interface MenuEntryShape<TArg> {
  variant?: 'default' | 'destructive';
  visible?: (arg: TArg) => boolean;
  separatorBefore?: boolean;
  children?: ReadonlyArray<MenuSeparator | MenuEntryShape<TArg>>;
}

./serialization#

./export-fonts#

./menu-items#

All exports, from the source#

@workspace/active-helpers/serialization#

Functions, hooks and constants

@workspace/active-helpers/export-fonts#

Functions, hooks and constants

Types

@workspace/active-helpers/menu-items#

Functions, hooks and constants

Types

`./serialization`#

`./export-fonts`#

`./menu-items`#

`@workspace/active-helpers/serialization`#

`@workspace/active-helpers/export-fonts`#

`@workspace/active-helpers/menu-items`#