@datatechsolutions/tympan-tokens 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -109,6 +109,29 @@ export interface ThemeConfig {
   elevation?: Elevation;
   /** Arbitrary string variables (e.g. for textures) */
   strings?: Record<string, string>;
+  /**
+   * String variables per mode (`--ty-<name>`), for values that differ
+   * between light and dark: a glass edge, a fill gradient, a brand mark
+   * gradient. Like pins, they are exact design values: the generated
+   * high-contrast variant leaves them out, so components fall back.
+   */
+  modeStrings?: Partial<Record<Mode, Record<string, string>>>;
+  /** Backdrop saturation of glass surfaces per mode (1.15 when omitted). */
+  glassSaturate?: Partial<Record<Mode, number>>;
+  /** Exact shadow layers per mode, replacing the generated ones by name. */
+  shadowPins?: Partial<Record<Mode, Partial<Record<ShadowName, ShadowPin[]>>>>;
+  /** Card and sheet radii in px, when they do not follow the control radius. */
+  radii?: Partial<Record<'card' | 'sheet', number>>;
+}
+export type ShadowName = 'sheet' | 'raised' | 'floating' | 'modal' | 'sheet-inset';
+/** One shadow layer of `shadowPins`, its colour as a CSS colour string. */
+export interface ShadowPin {
+  x: number;
+  y: number;
+  blur: number;
+  spread: number;
+  color: string;
+  inset?: boolean;
 }
 export declare const RAMP_STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
 export type RampStep = (typeof RAMP_STEPS)[number];
@@ -156,7 +179,7 @@ export interface ResolvedTheme {
     angle: number;
     stops: Rgba[];
   };
-  shadows: Record<'sheet' | 'raised' | 'floating' | 'modal' | 'sheet-inset', ShadowLayer[]>;
+  shadows: Record<ShadowName, ShadowLayer[]>;
   /** Pixel dimensions (radius, glass blur, focus width). */
   dimensions: Record<string, number>;
   /** Font stacks keyed by token name (`serif`, `sans`, `mono`); empty when the theme keeps the base stacks. */
@@ -201,8 +224,10 @@ export declare const fakhirPreset: ThemeConfig;
 /**
  * The Astrlabe workflow engine's look (`data-ty-theme="astrlabe"`): slate
  * neutrals, an indigo brand (indigo 500 as the accent family, one step darker
- * where text needs 4.5:1 on light grounds), translucent glass surfaces and the
- * rounder corners of that app (12 px controls, about 20 px cards). The call to
+ * where text needs 4.5:1 on light grounds), liquid-glass surfaces (gradient
+ * fills, specular edges, a strong saturation boost at night), the rounder
+ * corners of that app (12 px controls, 20 px cards, 24 px sheets), its
+ * compact type scale and the sky, indigo and violet mark. The call to
  * action is the indigo to purple gradient its primary buttons fill with, and
  * text (headings included) uses the platform's own system fonts. The state
  * contract holds on every ground: running is a cyan clearly off the indigo
@@ -349,7 +374,9 @@ export type RenderizadorGrafico = 'limpo' | 'mao' | 'isotype' | 'gravura' | 'pra
 export type MarcaProva = 'pilula' | 'carimbo' | 'circulo' | 'sublinhado' | 'barra' | 'etiqueta' | 'formas' | 'ponto';
 export type EstadoProva = 'sustentada' | 'refutada' | 'nao-da-para-afirmar' | 'pendente' | 'sem-dado' | 'nao-testada';
 export declare const ESTADOS_PROVA: readonly EstadoProva[];
-/** The word printed for each proof state (always visible, whatever the mark's shape). */
+/** The word printed for each proof state in English (tympan-print picks by the book's `lang`). */
+export declare const ROTULOS_PROVA_EN: Record<EstadoProva, string>;
+/** The word printed for each proof state (always visible, whatever the mark's shape); pt-BR. */
 export declare const ROTULOS_PROVA: Record<EstadoProva, string>;
 export interface PrintFontes {
   titulo: string;
@@ -372,6 +399,16 @@ export interface PrintCores {
   prova: Record<EstadoProva, string>;
   /** Colours of page ornaments only (frames, tiles, waves); never data. Up to four. */
   ornamento?: string[];
+  /** Colours by category key (official party colours…): used by categorical maps, parliament and bars. */
+  categorias?: Record<string, string>;
+  /** Colours of data themes (blocks of a panel page: economia, saude…); --ty-print-tema-<id>. */
+  temas?: Record<string, string>;
+  /** The series of interest in maps and charts (default: `destaque`), when the accent of the page differs from the data ink. */
+  interesse?: string;
+  /** Data palette, diverging: the low and the high side (default destaque2 × destaque). */
+  divergente?: [string, string];
+  /** Data palette, qualitative (party, category: no implied order), up to eight (default: a colour-blind-safe set). */
+  categorica?: string[];
 }
 /** Partial colours: any role, and any subset of the proof states. */
 export type PrintCoresParciais = Partial<Omit<PrintCores, 'prova'>> & {
@@ -455,6 +492,16 @@ export interface PrintEstrutura {
    */
   realce?: 'serie' | 'linha';
   /** Head of each small multiple: plain title (default), a band in the highlighter colour with an arrow (Schiphol), a dark band (Vignelli), a band in the ornament colour (Aicher), each multiple on its own tinted card (Le Corbusier, Bayer). */
+  /**
+   * Long runs (one page per unit, thousands of pages): no page ornaments, no tinted panel fills, the 'bolso'
+   * panel as a rule instead of a filled box. The style's type, colours and frames stay.
+   */
+  economiaTinta?: boolean;
+  /**
+   * Pages without a molde fill the type area: panels widen to close their row of the six columns and rows of
+   * panels share the free height (dashboard). A page can turn it on or off with `preencher`.
+   */
+  preencher?: boolean;
   cabecaMultiplo?: 'titulo' | 'faixa' | 'faixa-escura' | 'faixa-cor' | 'caixa-cor';
 }
 /**
@@ -478,7 +525,7 @@ export type Emblema = 'pictogramas' | 'formas' | 'circulo-bicolor' | 'figura-mod
 export type FormaGrafico = 'barras' | 'colunas' | 'eixo-central' | 'ziguezague' | 'fluxo' | 'predios' | 'cartoes' | 'halteres';
 /** Page ornaments (optional, CONTRATO §1). */
 export type Moldura = 'nenhuma' | 'dupla' | 'regua' | 'azulejo' | 'ondas' | 'ramos' | 'recortes' | 'reticula' | 'memphis' | 'diagonais' | 'formas' | 'quartos';
-export interface PrintStyle {
+export interface PrintStyle extends PrintTemaExtras {
   /** Stable id, e.g. 'jornal'. */
   name: string;
   /** Human label, e.g. "Editorial de jornal". */
@@ -516,9 +563,89 @@ export interface PrintStyle {
    * has approved variations (ink, duotone, per style), see LogoDatatech.
    */
   logo?: 'cor' | 'mono';
+  /** Typesetting options a book may need against the style's idiom (see PrintTexto). */
+  texto?: PrintTexto;
+}
+/**
+ * Typesetting switches for books whose content fights the style: a style in lower case (bauhaus,
+ * diagrama-modernista) would print "boa vista" for a proper name; a style with old-style figures would
+ * misalign table columns.
+ */
+export interface PrintTexto {
+  /**
+   * 'estilo' (default): page titles and eyebrows follow the style's casing. 'preservar': the level-1 title,
+   * eyebrows and table cells keep the casing written in the content (proper names, codes), while panel labels
+   * and running heads keep the style's.
+   */
+  nomesProprios?: 'estilo' | 'preservar';
+  /** Figures in table cells: 'tabular' (default, lining and equal width, columns align) or 'proporcional'. */
+  numerosTabela?: 'tabular' | 'proporcional';
+  /** Font weight per role (titles, key numbers, labels, body, notes, mono), e.g. { titulo: 600, numero: 600 }. */
+  pesos?: Partial<Record<keyof PrintFontes, number>>;
+  /** Figures per role: 'tabular' (equal width, lining) or 'proporcional'. Tables follow `numerosTabela`. */
+  algarismos?: Partial<Record<'numero' | 'rotulo' | 'corpo', 'tabular' | 'proporcional'>>;
+}
+/** A mark the theme prints (publisher logo, collection seal): an image URL (data: URIs work offline) and its text alternative. */
+export interface PrintMarca {
+  src: string;
+  alt: string;
+  /** Width in mm where the mark is placed (default 18 for the logo, 12 for the seal). */
+  largura?: number;
+  /** Image used in black and white print (default: the same `src`, greyed by CSS). */
+  srcPb?: string;
+}
+/** Page format and print finishing. */
+export interface PrintPagina {
+  /** Trim width in mm (default 170). */
+  largura?: number;
+  /** Trim height in mm (default 240). */
+  altura?: number;
+  /** Bleed in mm added around every page when the book prints for the press (default 3). */
+  sangria?: number;
+  /** Crop marks in the slug, outside the bleed (default false). */
+  marcasCorte?: boolean;
+}
+/** Running head and folio. */
+export interface PrintFolio {
+  /** Where the folio sits: outer corner (default) or centred. */
+  folio?: 'externo' | 'centro';
+  /** Where the running head sits: outer corner (default), centred, or not printed. */
+  cabeco?: 'externo' | 'centro' | 'nenhum';
+  /** Text before the folio number, e.g. "p. ". */
+  prefixoFolio?: string;
+}
+/** A local font file (offline, deterministic builds and EPUB): one @font-face. */
+export interface PrintFonteLocal {
+  /** Family name as used in the theme's font stacks. */
+  familia: string;
+  /** URL or path of the .woff2 (relative to the HTML, absolute, or a data: URI). */
+  src: string;
+  peso?: number | string;
+  estilo?: 'normal' | 'italic';
+}
+/** What a theme adds to a preset beyond the style tokens. */
+export interface PrintTemaExtras {
+  marcas?: {
+    editora?: PrintMarca;
+    selo?: PrintMarca;
+  };
+  pagina?: PrintPagina;
+  folio?: PrintFolio;
+  /** Local font files; with them PrintBook can run without network (`fontes="locais"`). */
+  fontesLocais?: PrintFonteLocal[];
+  /**
+   * Trace of a number (Rastro): sign it with the theme's seal (`marcas.selo`) or the lakebrasil mark, and add
+   * the lake version seal when the version carries a date. Default: neutral (neither).
+   */
+  rastro?: {
+    assinatura?: 'selo' | 'lakebrasil' | 'nenhuma';
+    seloLake?: boolean;
+  };
+  /** Texts the print components write by themselves, by key (see tympan-print i18n: TEXTOS_PT / TEXTOS_EN). */
+  textos?: Record<string, string>;
 }
 /** Any token of a style may be overridden by the editor (partial, nested). */
-export interface PrintStyleOverrides {
+export interface PrintStyleOverrides extends PrintTemaExtras {
   label?: string;
   fontes?: Partial<PrintFontes>;
   googleFonts?: string[];
@@ -532,6 +659,7 @@ export interface PrintStyleOverrides {
   pb?: PrintCoresParciais;
   estrutura?: Partial<PrintEstrutura>;
   logo?: 'cor' | 'mono';
+  texto?: PrintTexto;
 }
 /** The 39 book styles, by name. */
 export declare const printPresets: {
@@ -608,6 +736,20 @@ export interface PrintCssOptions {
  * current style (`resolvePrintStyle('economist').name === 'semanario'`).
  */
 export declare function resolvePrintStyle(style: PrintStyle | PrintStyleId, options?: Omit<PrintCssOptions, 'seletor'>): PrintStyle;
+/**
+ * `cor` moved along OKLCH lightness (hue and chroma kept) until it reaches `min`:1 against `papel`: the
+ * context grey of a theme stays visible on cream paper (areas ≥ 1.5:1, strokes ≥ 3:1).
+ */
+export declare function contrasteMinimo(cor: string, papel: string, min: number): string;
+/**
+ * Unlayered rules (they win over `@layer tympan-print`) for a theme's per-role font weights and figures,
+ * scoped to `seletor`; '' when the theme sets neither.
+ */
+export declare function printTextoRolesCss(style: Pick<PrintStyle, 'texto'>, seletor: string): string;
+/** Qualitative palette (Okabe & Ito 2008, colour-blind safe) used when a style defines none. */
+export declare const CATEGORICA_PADRAO: readonly ['#0072b2', '#e69f00', '#009e73', '#cc79a7', '#56b4e9', '#d55e00', '#f0e442', '#555555'];
+/** The eight qualitative data colours of a style: its own `categorica`, completed by CATEGORICA_PADRAO. */
+export declare function categoricaDoEstilo(style: Pick<PrintStyle, 'cor'>): string[];
 /** Custom properties of a resolved style, in a stable order. */
 export declare function printStyleVariables(style: PrintStyle): Array<[string, string]>;
 /**
@@ -621,58 +763,6 @@ export declare function googleFontsUrl(style: Pick<PrintStyle, 'googleFonts'>):
 /** True when the paper is dark (the brand seal and logo then use the light mono version). */
 export declare function papelEscuro(style: Pick<PrintStyle, 'cor'>): boolean;
 //#endregion
-//#region src/print-themes.d.ts
-/** Per-style adjustments where the derivation misjudges; merged over the derived config. */
-export interface PrintThemeOverride {
-  /** Brand colour to use instead of the derived one. */
-  brand?: string;
-  glass?: boolean;
-  cta?: ThemeConfig['cta'];
-  elevation?: ThemeConfig['elevation'];
-  /** Radius in px. */
-  radius?: number;
-  /** Extra pins per mode (applied before the contrast check, dropped if they fail like any pin). */
-  pins?: ThemeConfig['pins'];
-}
-/**
- * Where the derivation reads a style differently from its tradition. Kept
- * short on purpose: every entry is a judgement the data cannot express.
- */
-export declare const PRINT_THEME_OVERRIDES: Partial<Record<PrintPresetName, PrintThemeOverride>>;
-/** The colour moved along OKLCH lightness (hue and chroma kept) until it reaches `min` against `over`. */
-export declare function legibleOn(colour: string, over: string, min?: number): string;
-/**
- * The accent that represents a style, before any legibility adjustment: the
- * first chromatic accent that nearly reads on the paper (3:1), else the most
- * legible chromatic accent, else the first chromatic ornament, else the ink
- * (or, on dark paper, the paper itself).
- */
-export declare function printStyleAccent(style: PrintStyle): string;
-/**
- * The UI theme of a book style, in light and dark. The name is
- * `print-<style name>`; the label is the style's own.
- */
-export declare function printStyleToTheme(style: PrintStyle, override?: PrintThemeOverride): ThemeConfig;
-/**
- * Exact print colours the derivation had to give up for contrast, per mode
- * (role -> the print colour that was dropped and regenerated).
- */
-export declare function printThemeDroppedPins(style: PrintStyle, override?: PrintThemeOverride): Record<Mode, Partial<Record<RoleName, string>>>;
-/** Every book style as a UI theme, in the order of `printPresets`. */
-export declare const printThemePresets: readonly ThemeConfig[];
-/**
- * Legacy: Google Fonts stylesheet URL of the families of each print theme, by
- * theme name. The print theme sheets now declare the bundled fonts
- * (`printThemeFontSpecs`), so ThemeProvider needs no `fonts` map; this stays
- * for hosts that prefer Google's CDN.
- */
-export declare const printThemeFontUrls: Readonly<Record<string, string>>;
-/**
- * Google Fonts specs of each print theme, by theme name: the families its
- * stacks name, bundled under fonts/ and declared in the theme's sheet.
- */
-export declare const printThemeFontSpecs: Readonly<Record<string, readonly string[]>>;
-//#endregion
 //#region src/fonts.d.ts
 /** Base stacks of every preset: Source Serif 4, IBM Plex Sans, IBM Plex Mono. */
 export declare const BASE_FONT_SPECS: readonly string[];
@@ -725,6 +815,115 @@ export interface FontManifest {
  */
 export declare function fontFaceCss(manifest: FontManifest, specs: readonly string[], base: string): string;
 //#endregion
+//#region src/print-book-themes.d.ts
+/** A book theme: an id, a base and overrides. */
+export interface PrintBookTheme extends PrintStyleOverrides {
+  /** Registry id, e.g. 'lakebrasil-editorial'. Use it as PrintBook's `estilo`. */
+  id: string;
+  /** A preset name (or deprecated alias) or the id of another registered theme. */
+  base: string;
+  /** What the theme interprets (shown in galleries). */
+  referencia?: string;
+}
+/** The JSON form of a theme: the same fields, colours as hex strings or DTCG colour objects. */
+export type PrintBookThemeJson = Omit<PrintBookTheme, 'cor' | 'pb'> & {
+  cor?: Record<string, unknown>;
+  pb?: Record<string, unknown>;
+};
+/** A style with overrides and theme extras applied (same as mergePrintStyle, kept for readability). */
+export declare const mergePrintTheme: typeof mergePrintStyle;
+/** Resolves a theme id or a preset id to a complete PrintStyle (`name` = the theme id). */
+export declare function printThemeById(id: string, visitados?: string[]): PrintStyle;
+/** True when `id` names a registered theme or a preset. */
+export declare function isPrintThemeId(id: string): boolean;
+/** Validates and normalises a theme read from JSON (colours may be hex or DTCG colour objects). */
+export declare function printThemeFromJson(json: PrintBookThemeJson | string): PrintBookTheme;
+type No = Record<string, unknown>;
+/**
+ * A theme from a DTCG (2025.10) tree. The tree mirrors PrintStyleOverrides: each group is a field
+ * (`label`, `fontes.<role>`, `googleFonts`, `cor.<role>`, `cor.prova.<state>`, `cor.categorica.<n>`,
+ * `cor.divergente.<n>`, `traco.largura`, `pb.*`, `estrutura.*`, `texto.*`, `marcas.*`, `pagina.*`, `folio.*`,
+ * `fontesLocais`…) and each `{ "$type", "$value" }` leaf becomes its value (colours as hex or DTCG colour
+ * objects, `fontFamily` arrays become CSS stacks, dimensions become mm). The theme's id and base come from
+ * the root `$extensions["dev.tympan.print"]` (or `["br.com.datatechsolutions.tympan"]`) as `name`/`id` and
+ * `extends`/`base`.
+ */
+export declare function printThemeFromDtcg(tree: No | string): PrintBookTheme;
+/** Registers (or replaces) a theme; accepts the theme object, its JSON or a DTCG tree. Returns the theme. */
+export declare function registerPrintTheme(tema: PrintBookTheme | PrintBookThemeJson | No | string): PrintBookTheme;
+/** Removes a registered theme (tests, hot reload). */
+export declare function unregisterPrintTheme(id: string): boolean;
+/** Ids of the registered themes, in registration order. */
+export declare function registeredPrintThemes(): string[];
+/** `@font-face` rules for a style's local font files ('' when it has none). */
+export declare function fontesLocaisCss(style: Pick<PrintStyle, 'fontesLocais'>): string;
+/** Trim and bleed of a style (defaults 170 × 240 mm, 3 mm bleed). */
+export declare function paginaDoEstilo(style: Pick<PrintStyle, 'pagina'>): Required<PrintPagina>;
+/** A neutral example theme (registered nowhere by default): a small press over `semanario`, in two inks. */
+export declare const TEMA_EXEMPLO_EDITORA: PrintBookTheme;
+/** Families named in a style's font stacks (quotes removed), in role order, without generic and system faces. */
+export declare function familiasDoEstilo(style: Pick<PrintStyle, 'fontes'>): string[];
+/** Families the style names (first of each stack) that have neither a bundled file nor a theme `fontesLocais`. */
+export declare function familiasSemArquivo(style: Pick<PrintStyle, 'fontes' | 'fontesLocais'>, manifest: FontManifest): string[];
+/**
+ * @font-face rules for a style from the fonts bundled in this package (`fonts/manifest.json`): every face of
+ * every family its font stacks name (so a mono or label family outside `googleFonts` is not forgotten), with
+ * URLs `<base><file>`, then the theme's own `fontesLocais`, which win for their family.
+ */
+export declare function fontesEmpacotadasCss(style: Pick<PrintStyle, 'fontes' | 'googleFonts' | 'fontesLocais'>, manifest: FontManifest, base: string): string;
+//#endregion
+//#region src/print-themes.d.ts
+/** Per-style adjustments where the derivation misjudges; merged over the derived config. */
+export interface PrintThemeOverride {
+  /** Brand colour to use instead of the derived one. */
+  brand?: string;
+  glass?: boolean;
+  cta?: ThemeConfig['cta'];
+  elevation?: ThemeConfig['elevation'];
+  /** Radius in px. */
+  radius?: number;
+  /** Extra pins per mode (applied before the contrast check, dropped if they fail like any pin). */
+  pins?: ThemeConfig['pins'];
+}
+/**
+ * Where the derivation reads a style differently from its tradition. Kept
+ * short on purpose: every entry is a judgement the data cannot express.
+ */
+export declare const PRINT_THEME_OVERRIDES: Partial<Record<PrintPresetName, PrintThemeOverride>>;
+/** The colour moved along OKLCH lightness (hue and chroma kept) until it reaches `min` against `over`. */
+export declare function legibleOn(colour: string, over: string, min?: number): string;
+/**
+ * The accent that represents a style, before any legibility adjustment: the
+ * first chromatic accent that nearly reads on the paper (3:1), else the most
+ * legible chromatic accent, else the first chromatic ornament, else the ink
+ * (or, on dark paper, the paper itself).
+ */
+export declare function printStyleAccent(style: PrintStyle): string;
+/**
+ * The UI theme of a book style, in light and dark. The name is
+ * `print-<style name>`; the label is the style's own.
+ */
+export declare function printStyleToTheme(style: PrintStyle, override?: PrintThemeOverride): ThemeConfig;
+/**
+ * Exact print colours the derivation had to give up for contrast, per mode
+ * (role -> the print colour that was dropped and regenerated).
+ */
+export declare function printThemeDroppedPins(style: PrintStyle, override?: PrintThemeOverride): Record<Mode, Partial<Record<RoleName, string>>>;
+/** Every book style as a UI theme, in the order of `printPresets`. */
+export declare const printThemePresets: readonly ThemeConfig[];
+/**
+ * Legacy: Google Fonts stylesheet URL of the families of each print theme, by
+ * theme name. The print theme sheets now declare the bundled fonts
+ * (`printThemeFontSpecs`), so ThemeProvider needs no `fonts` map; this stays
+ * for hosts that prefer Google's CDN.
+ */
+export declare const printThemeFontUrls: Readonly<Record<string, string>>;
+/**
+ * Google Fonts specs of each print theme, by theme name: the families its
+ * stacks name, bundled under fonts/ and declared in the theme's sheet.
+ */
+export declare const printThemeFontSpecs: Readonly<Record<string, readonly string[]>>;
+//#endregion
 //#region src/index.d.ts
 export declare const allThemes: readonly ThemeConfig[];
 //#endregion