uhuu-components 0.2.98 → 0.3.1

package/index.d.ts

@@ -329,23 +329,95 @@ export interface BrandKitJson {
     primitives?: { typography?: Record<string, unknown>; [key: string]: unknown };
     [token: string]: unknown;
   };
+  colorMode?: "light" | "manual" | "shade";
+  /** Template variables Brand Kit precomputed at publish. Applied as is when `version` is 2. */
+  runtime?: BrandKitRuntimeBlock;
   [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.
+ */
+export interface BrandKitRuntimeBlock {
+  version: 2;
+  light: Record<string, string>;
+  fontStylesheets?: string[];
+  fontFaces?: Array<{ family: string; src: string; weight?: number; style?: "normal" | "italic"; format?: string }>;
+}
+
+export interface BrandKitLogo {
+  /** Absolute URL (SVG preferred, else PNG). */
+  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" };
+}
+
+export interface BrandKitCollectionItem {
+  key: string;
+  /** Absolute URL. */
+  src: string;
+  label?: string;
+  name?: string;
+  type?: string;
+  mimeType?: string;
+  tags?: string[];
+  [key: string]: unknown;
+}
+
+export interface BrandKitCollection {
+  id: string;
+  name?: string;
+  type?: string;
+  versionId?: string;
+  items: BrandKitCollectionItem[];
+}
+
+export interface BrandKitMapStyle {
+  url: string;
+  name?: string;
+  source: "config.maps" | "config.env";
+}
+
+export type BrandKitLogoKind = "primary" | "logo" | "lockup" | "mark" | "icon" | "symbol" | "wordmark";
+export type BrandKitMediaKind = "photos" | "icons" | "graphics" | "backgrounds" | "templates";
+
 /** What `useBrandKit()` returns. */
 export interface BrandKitRuntime {
-  /** The raw kit: logos and collections are read from it. */
+  /** The kit being rendered: the fetched one, else the `brandKit` prop. */
   brandKit: BrandKitJson | null;
-  /** `--color-kit-*`, `--font-*` and `--font-kit-*`, as the provider's scope element carries them. */
+  /** `--<role>`, `--color-<role>`, `--color-kit-*`, `--font-*` and `--font-kit-*`, 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). */
+  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;
+  mapStyle(mode: "micro" | "macro"): BrandKitMapStyle | null;
+  /** A `config.env` value; keys compare case- and punctuation-insensitively, first present wins. */
+  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. */
   brandKit?: BrandKitJson | null;
+  /** A brandkit.json URL to fetch, usually `brandKitSourceUrl(payload)`. */
+  src?: string | null;
   /** Custom properties for whatever the kit leaves out; the kit wins. Pass a stable object. */
   defaults?: Record<string, string>;
-  /** Where a fetched kit came from; its directory resolves relative font URLs when the kit has no `baseUrl`. */
+  /** Where a `brandKit` passed in came from; its directory resolves relative URLs when the kit has no `baseUrl`. */
   sourceUrl?: string;
+  onLoad?: (brandKit: BrandKitJson) => void;
+  /** Default: `console.error`. */
+  onError?: (error: unknown) => void;
   /** For the scope element. `style` is applied last, so `{ display: "block" }` gives it a box. */
   className?: string;
   style?: CSSProperties;
@@ -354,18 +426,78 @@ export interface BrandKitProviderProps {
 
 /**
  * Scopes a kit's CSS variables around the pages and their overlay chrome, on a `display: contents`
- * element, and loads the fonts the kit declares. Colours are hex, `rgb()`/`rgba()` or keywords:
- * HSL is converted, anything else is skipped as if absent.
+ * 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.
  */
 export const BrandKitProvider: ComponentType<BrandKitProviderProps>;
 
 /** The nearest `BrandKitProvider`'s runtime, or `null` outside one. */
 export function useBrandKit(): BrandKitRuntime | null;
 
+/** Brand Kit's production location for published kits. */
+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`.
+ */
+export function brandKitSourceUrl(
+  payload: Record<string, unknown> | null | undefined,
+  options?: { publicBaseUrl?: string; teamId?: string | number },
+): string | null;
+
+/** 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 },
+): BrandKitLogo | null;
+
+export function brandKitCollection(
+  brandKit: BrandKitJson | null | undefined,
+  kind: BrandKitMediaKind | string,
+  options?: { sourceUrl?: string; versionId?: string },
+): BrandKitCollection | null;
+
+export function brandKitMapStyle(brandKit: BrandKitJson | null | undefined, mode: "micro" | "macro"): BrandKitMapStyle | null;
+
+export function brandKitEnv(brandKit: BrandKitJson | null | undefined, keys: string | string[]): string | undefined;
+
 export interface InteractiveModeContextValue {
   interactive: boolean;
   setInteractive: (interactive: boolean) => void;
   enableDevTools?: boolean;
+  /** The shell's resolved interface language (`de`, `fr`, `it`, `en`, or what the template passed). */
+  locale: string;
+}
+
+/**
+ * A label as one string, or one string per language: `{ en: 'Cover', de: 'Titelseite' }`.
+ * Accepted wherever `templateConfig` and `pageOptions` take a `label` (pages, groups, options,
+ * select and colour values) and by `reorderTitle` / `reorderDescription`. Resolved in the shell's
+ * language, then English, then the first entry.
+ */
+export type LocalizedText = string | Record<string, string>;
+
+/** Editor shell words, nested as in the English catalog (docs/editor-shell-translations.md). */
+export type EditorShellTranslations = { [key: string]: string | EditorShellTranslations };
+
+export interface InteractiveModeProviderProps {
+  children: ReactNode;
+  defaultInteractive?: boolean;
+  enableDevTools?: boolean;
+  /**
+   * The shell's interface language. Default: the host's (uhuu-app's locale from the SDK
+   * handshake), then `?lang=`, `<html lang>`, the browser's languages, then `en`.
+   */
+  locale?: string;
+  /**
+   * Per-language overrides of the shell's words, or a whole catalog for a language the package
+   * does not ship: `{ de: { toolbar: { add: 'Neu' } }, rm: romanshCatalog }`. Pass a stable object.
+   */
+  translations?: Record<string, EditorShellTranslations>;
 }
 
 export interface BrandKitOption {
@@ -432,8 +564,8 @@ export interface PageEditorProps {
     pageId?: string;
     parent?: unknown;
   }) => ReactNode;
-  reorderTitle?: string;
-  reorderDescription?: string;
+  reorderTitle?: LocalizedText;
+  reorderDescription?: LocalizedText;
   stateKey?: string;
   brandKits?: BrandKitOption[];
   activeBrandKitId?: string;
@@ -467,11 +599,7 @@ export interface IntegrationAdapter {
 export const EditorShell: {
   TemplateDataProvider: ComponentType<TemplateDataProviderProps>;
   PageEditor: ComponentType<PageEditorProps>;
-  InteractiveModeProvider: ComponentType<{
-    children: ReactNode;
-    defaultInteractive?: boolean;
-    enableDevTools?: boolean;
-  }>;
+  InteractiveModeProvider: ComponentType<InteractiveModeProviderProps>;
   useInteractive: () => InteractiveModeContextValue;
   useIntegrationAdapter: (config: IntegrationAdapterConfig) => IntegrationAdapter;
 };

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.98",
+  "version": "0.3.1",
   "name": "uhuu-components",
   "main": "uhuu-components.umd.cjs",
   "module": "uhuu-components.es.js",
@@ -15,6 +15,15 @@
     }
   },
   "license": "https://uhuu.io/license",
+  "files": [
+    "uhuu-components.es.js",
+    "uhuu-components.es.js.map",
+    "uhuu-components.umd.cjs",
+    "uhuu-components.umd.cjs.map",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"