uhuu-components 0.4.5 → 0.4.7

package/index.d.ts

@@ -721,6 +721,50 @@ export interface FrameBlockProps extends FrameDeclaration, Omit<ImageBlockProps,
  */
 export const FrameBlock: ComponentType<FrameBlockProps>;
 
+/**
+ * A neutral, brand-free empty image (outline and icon in Text mixed into Paper) for `ImageBlock`'s
+ * `placeholder`, so templates never borrow placeholder photos from a client folder.
+ */
+export const ImagePlaceholder: ComponentType<{ label?: string; className?: string; style?: CSSProperties }>;
+
+/** A position on the sheet in mm: `left` or `right`, and `top` or `bottom`. */
+export interface FurniturePosition { left?: number; right?: number; top?: number; bottom?: number }
+
+/**
+ * The printed page number of sheet `pageNo` (1-based, deck order), or `null` when it is not numbered.
+ * Counting starts at the first numbered sheet and skips unnumbered sheets after it; `offset` is subtracted.
+ */
+export function folioNumber(input: {
+  pageNo: number;
+  sheetKeys: readonly string[];
+  numbered: readonly string[] | ((key: string) => boolean);
+  offset?: number;
+}): number | null;
+
+/** The page number in the brand's body font and muted colour, at the verso (even) or recto (odd) position. */
+export const PageFolio: ComponentType<{
+  number: number | null | undefined;
+  pageNo: number;
+  verso: FurniturePosition;
+  recto: FurniturePosition;
+  /** pt, default 9. */
+  size?: number;
+  className?: string;
+  style?: CSSProperties;
+}>;
+
+/** A running header: title, the brand's logo (default the mark on Paper) and a `border` or `accent` rule. */
+export const RunningHeader: ComponentType<{
+  position: FurniturePosition;
+  children?: ReactNode;
+  logo?: false | { kind?: "primary" | "mark" | "wordmark"; background?: "light" | "dark"; name?: string; locale?: string };
+  /** mm, default 6. */
+  logoHeight?: number;
+  rule?: "border" | "accent" | false;
+  className?: string;
+  style?: CSSProperties;
+}>;
+
 // --- Brand-kit runtime (src/uhuu/brand-kit/). See docs/brand-kit-runtime.md. ---
 
 export interface BrandKitFontFile {
@@ -768,30 +812,57 @@ export interface BrandKitJson {
     [token: string]: unknown;
   };
   colorMode?: "light" | "manual" | "shade";
-  /** Template variables Brand Kit precomputed at publish. Applied as is when `version` is 2. */
+  /** Template variables Brand Kit precomputed at publish for current public 3.x documents. */
   runtime?: BrandKitRuntimeBlock;
+  /** What wrote the document; a published version names itself in `release`. */
+  generator?: { name?: string; release?: BrandKitRelease; [key: string]: unknown };
   [key: string]: unknown;
 }
 
 /**
- * `brandkit.json.runtime` (brandkit.json "2.0"): shadcn role variables (`--primary`, `--color-primary`),
- * `--color-kit-*` / `--font-*` / `--font-kit-*` values, ready to apply, and the fonts to load.
+ * `generator.release` of a published version's document (older documents have none): it lets
+ * `?brand=v9` and `uhuu-components brand status | activate v9` name another version of the brand a
+ * template's `src/brand/brandkit.json` holds.
+ */
+export interface BrandKitRelease {
+  teamId: string;
+  kitId: string;
+  /** `v1`, `v2`… */
+  version: string;
+  /** This version's immutable `…/versions/vN/brandkit.json`. */
+  url: string;
+  /** The Brand Kit app's origin, which says which version is newest. */
+  appUrl?: string;
+}
+
+/**
+ * `brandkit.json.runtime` (public 3.x): canonical semantic and font-role variables, ready to
+ * apply, and the fonts to load. It cannot carry template layout or decoration tokens.
  */
 export interface BrandKitRuntimeBlock {
-  version: 2;
+  version: 3;
   light: Record<string, string>;
   fontStylesheets?: string[];
-  fontFaces?: Array<{ family: string; src: string; weight?: number; style?: "normal" | "italic"; format?: string }>;
+  fontFaces?: Array<{
+    family: string;
+    src: string;
+    weight?: number;
+    style?: "normal" | "italic";
+    format?: string;
+    ascentOverride?: number;
+    descentOverride?: number;
+    lineGapOverride?: number;
+  }>;
 }
 
 export interface BrandKitLogo {
-  /** Absolute URL (SVG preferred, else PNG). */
+  /** Absolute SVG URL. */
   src: string;
   alt?: string;
   kind: "primary" | "mark" | "wordmark";
   background?: "light" | "dark" | "any";
-  minWidth?: { value: number; unit: "px" | "mm" };
-  clearSpace?: { value: number; unit: "px" | "mm" | "mark" };
+  /** The language a named or language version is for. */
+  locale?: string;
 }
 
 export interface BrandKitCollectionItem {
@@ -817,7 +888,7 @@ export interface BrandKitCollection {
 export interface BrandKitMapStyle {
   url: string;
   name?: string;
-  source: "config.maps" | "config.env";
+  source: "extensions.maps" | "extensions.env";
 }
 
 export type BrandKitLogoKind = "primary" | "logo" | "lockup" | "mark" | "icon" | "symbol" | "wordmark";
@@ -827,34 +898,47 @@ export type BrandKitMediaKind = "photos" | "icons" | "graphics" | "backgrounds"
 export interface BrandKitRuntime {
   /** The kit being rendered: the fetched one, else the `brandKit` prop. */
   brandKit: BrandKitJson | null;
-  /** `--<role>`, `--color-<role>`, `--color-kit-*`, `--font-*` and `--font-kit-*`, as the provider's scope element carries them. */
+  /** Canonical semantic, extension-colour and font-role variables as the provider's scope element carries them. */
   cssVars: Record<string, string>;
   /** Where the rendered kit came from (`src` once fetched, else the `sourceUrl` prop). */
   sourceUrl?: string;
-  /** `idle` without `src`; `loading` until it arrives; `ready`; `error` (the `brandKit` prop renders). */
+  /** `idle` without `src` (the `brandKit` prop renders); `loading` until it arrives; `ready`; `error`. */
   status: "idle" | "loading" | "ready" | "error";
-  /** A logo, resolved: `logoSystem` first, then `logos`. Default `{ kind: "primary", background: "light" }`. */
-  logo(options?: { kind?: BrandKitLogoKind; background?: "light" | "dark" }): BrandKitLogo | null;
-  /** The assigned media collection's promoted version, items resolved. */
-  collection(kind: BrandKitMediaKind | string, options?: { versionId?: string }): BrandKitCollection | null;
+  /**
+   * A logo resolved from `logoSystem`. Default `{ kind: "primary", background: "light" }`.
+   * `name` and `locale` pick a named or language version, falling back to the standard logo.
+   */
+  logo(options?: { kind?: BrandKitLogoKind; background?: "light" | "dark"; name?: string; locale?: string }): BrandKitLogo | null;
+  /** The brand's chart colors as hex when it set them, else `fallback` (the template's). */
+  chartPalette(options?: { fallback?: string[]; count?: number }): BrandChartPalette;
+  /** The brand's default locale and currency (`extensions.locale`); `payload.locale` wins over it. */
+  locale: { locale?: string; currency?: string };
+  /** Public 3.x: canonical kind/id and active-version selection. */
+  collection(kindOrId: BrandKitMediaKind | string, options?: { versionId?: string }): BrandKitCollection | null;
   mapStyle(mode: "micro" | "macro"): BrandKitMapStyle | null;
-  /** A `config.env` value; keys compare case- and punctuation-insensitively, first present wins. */
+  /** An `extensions.env.strings` value; keys compare case- and punctuation-insensitively. */
   env(keys: string | string[]): string | undefined;
   /** A kit-relative asset path made absolute. */
   resolveUrl(path: unknown): string | undefined;
 }
 
 export interface BrandKitProviderProps {
-  /** The kit to render; with `src`, the fallback until the fetched kit arrives or when the fetch fails. */
+  /**
+   * The kit to render, usually the template's own `src/brand/brandkit.json`; with `src`, the fallback
+   * until the fetched kit arrives or when the fetch fails.
+   */
   brandKit?: BrandKitJson | null;
-  /** A brandkit.json URL to fetch, usually `brandKitSourceUrl(payload)`. */
+  /** A brandkit.json URL to fetch, usually `brandKitSelection(payload).src`. */
   src?: string | null;
+  /** Brand values the template opts into beyond colours and fonts: `{ radius: true }` adds `--radius*`. Stable object. */
+  adopt?: { radius?: boolean };
   /** Custom properties for whatever the kit leaves out; the kit wins. Pass a stable object. */
   defaults?: Record<string, string>;
   /** Where a `brandKit` passed in came from; its directory resolves relative URLs when the kit has no `baseUrl`. */
   sourceUrl?: string;
+  /** Called with each kit fetched from `src`; never for a development preview (`?brand=`). */
   onLoad?: (brandKit: BrandKitJson) => void;
-  /** Default: `console.error`. */
+  /** Called when `src` fails to load; never for a development preview. Default: `console.error`. */
   onError?: (error: unknown) => void;
   /** For the scope element. `style` is applied last, so `{ display: "block" }` gives it a box. */
   className?: string;
@@ -867,6 +951,10 @@ export interface BrandKitProviderProps {
  * element (`data-uhuu-brand-kit-status` tells a print step when a fetched kit has arrived), and
  * loads the fonts the kit declares. Colours are hex, `rgb()`/`rgba()`, `oklch()`/`oklab()` or
  * keywords: HSL is converted, anything else is skipped as if absent.
+ *
+ * On a development host, and never when `$uhuu_renderer` is set, `?brand=` on the page URL (`v9`, a
+ * `…/versions/vN/brandkit.json` link, or a same-origin path) renders that candidate instead, under a
+ * bar with what changed and Stop. It is written nowhere and never printed.
  */
 export const BrandKitProvider: ComponentType<BrandKitProviderProps>;
 
@@ -877,20 +965,60 @@ export function useBrandKit(): BrandKitRuntime | null;
 export const BRAND_KIT_PUBLIC_BASE_URL: string;
 
 /**
- * The brandkit.json URL a payload points at: `brandKitUrl` (URL or `kit-…` id), `brandKitId`, or
- * `brandKit.storage.publicUrl`. Ids need `brandKitTeamId` (or `teamId`) and resolve under `publicBaseUrl`.
+ * Which brand a document renders: a pinned `payload.brand` (unpinned warns), then none: the
+ * template's own current `brandkit.json` (`brandKit` prop) renders.
+ * `pinned` is true when `src` is an immutable `…/versions/vN/brandkit.json` (and for a preset, which
+ * fetches nothing). A `version: "vN"` beside a kit's root `…/kits/<kit>/brandkit.json` selects that
+ * version's URL; a version alone pins nothing.
  */
-export function brandKitSourceUrl(
+export function brandKitSelection(
   payload: Record<string, unknown> | null | undefined,
-  options?: { publicBaseUrl?: string; teamId?: string | number },
-): string | null;
+): { source: "payload" | "none"; src: string | null; pinned: boolean; presetId?: string };
+
+export interface BrandChartPalette {
+  colors: string[];
+  source: "brand" | "template";
+}
+
+/** Chart colors as `#rrggbb`: the brand's when it set them (Brand Kit publishes them only then), else `fallback`. */
+export function brandChartPalette(brandKit: BrandKitJson | null | undefined, options?: { fallback?: string[]; count?: number }): BrandChartPalette;
+
+/**
+ * The chart dialog's `config.brand` (`ChartDialogBrand`): the series palette from `brandChartPalette`
+ * and ink, line, muted and surface, all `#rrggbb`. Missing roles are left for the dialog's defaults.
+ */
+export function brandChartDialogBrand(
+  brandKit: BrandKitJson | null | undefined,
+  options?: { fallback?: string[]; count?: number },
+): { palette?: string[]; ink?: string; line?: string; muted?: string; surface?: string };
+
+/** `#rrggbb` for hex, `rgb()`, HSL, `oklch()` or `oklab()`; `undefined` otherwise. */
+export function colorToHex(value: unknown): string | undefined;
+
+/** The brand's default locale and currency (`extensions.locale.strings`). */
+export function brandKitLocale(brandKit: BrandKitJson | null | undefined): { locale?: string; currency?: string };
+
+/** A number in the locale (`payload.locale`, else the brand's); Swiss locales group with `'`. */
+export function formatNumber(
+  value: number,
+  options?: { locale?: string; brandKit?: BrandKitJson | null; apostrophe?: "straight" | "typographic" } & Intl.NumberFormatOptions,
+): string;
+
+/** Money; Swiss locales print `CHF 3'600'000.–` (whole) and `CHF 1'250.50`. Currency: option, brand, `CHF`. */
+export function formatMoney(
+  value: number,
+  options?: { locale?: string; currency?: string; brandKit?: BrandKitJson | null; wholeDash?: boolean; apostrophe?: "straight" | "typographic" },
+): string;
+
+/** A date in the locale; `dateStyle: "long"` unless date fields are given. */
+export function formatDate(value: Date | string | number, options?: { locale?: string; brandKit?: BrandKitJson | null } & Intl.DateTimeFormatOptions): string;
 
 /** Fetches a brandkit.json; rejects on network errors, non-2xx and non-object bodies. */
 export function loadBrandKit(url: string, options?: { fetch?: typeof fetch; signal?: AbortSignal }): Promise<BrandKitJson>;
 
 export function brandKitLogo(
   brandKit: BrandKitJson | null | undefined,
-  options?: { kind?: BrandKitLogoKind; background?: "light" | "dark"; sourceUrl?: string },
+  options?: { kind?: BrandKitLogoKind; background?: "light" | "dark"; name?: string; locale?: string; sourceUrl?: string },
 ): BrandKitLogo | null;
 
 export function brandKitCollection(
@@ -1293,6 +1421,8 @@ export interface PageEditorProps {
   /**
    * Development only: the brand-kit switcher in the dev tools menu (dev tools on). It lists
    * `brandKits` and calls back; it does not load a kit: wire the choice to `BrandKitProvider`.
+   * Inside a `BrandKitProvider` on a development host the Brand Kit submenu also offers
+   * *Preview a version…* (`?brand=`), with or without `brandKits`.
    */
   brandKits?: BrandKitOption[];
   /** Development only: the kit the dev switcher marks as active. */

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.5",
+  "version": "0.4.7",
   "name": "uhuu-components",
   "main": "uhuu-components.umd.cjs",
   "module": "uhuu-components.es.js",
@@ -15,6 +15,9 @@
     }
   },
   "license": "https://uhuu.io/license",
+  "bin": {
+    "uhuu-components": "cli.js"
+  },
   "scripts": {
     "prepublishOnly": "node verify-release.cjs"
   },
@@ -23,7 +26,8 @@
     "uhuu-components.es.js.map",
     "uhuu-components.umd.cjs",
     "uhuu-components.umd.cjs.map",
-    "index.d.ts"
+    "index.d.ts",
+    "cli.js"
   ],
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",