uhuu-components 0.2.97 → 0.3.0

package/index.d.ts

@@ -4,6 +4,7 @@ import type {
   CSSProperties,
   ImgHTMLAttributes,
   Key,
+  MouseEventHandler,
   ReactElement,
   ReactEventHandler,
   ReactNode,
@@ -222,8 +223,248 @@ export interface EditableProps {
   children?: ReactNode;
 }
 
+/**
+ * Wraps its children in a `div` bound to `dialog`. The element is rendered even when the
+ * children are empty (null, false, whitespace): it is the click target. A bound, empty
+ * Editable carries `uhuu-text-empty`, which gets a one-line box in the editor.
+ * Template CSS controls print layout. Only text/textarea/markdown dialogs get the marker.
+ * Pass `null`, not a renderer element around an empty string.
+ */
 export const Editable: ComponentType<EditableProps>;
 
+/** What `getDialogProps` returns. Spread it onto the element that renders the field. */
+export interface DialogBindingProps {
+  /** Marks the element for the editor: `""`, or the serialised dialog under legacy dynamic pagination. */
+  "data-uhuu"?: string;
+  /** `dialog.type`, so CSS can tell an empty text binding from an empty image. */
+  "data-uhuu-type"?: string;
+  /** Opens the dialog in the interactive editor. Never set in renderer mode (`window.$uhuu_renderer`). */
+  onClick?: MouseEventHandler<HTMLElement>;
+}
+
+/**
+ * The props `Editable` and `ImageBlock` attach, for a template that binds its own element:
+ * `<p {...getDialogProps({ dialog: { path, type: "textarea", value } })}>`. Renderer mode gets
+ * the markers without a click handler. No dialog returns `{}`. Never returns `className`.
+ */
+export function getDialogProps(props: { dialog?: object | null } | null | undefined): DialogBindingProps;
+
+// --- Image URLs (src/uhuu/image/image-url.js). See docs/image-url.md. ---
+
+/** An image as payloads store it: an ImageObject, the dialogs' legacy `{ url }`, a URL, or nothing. */
+export type ImageSource =
+  | string
+  | {
+      contentUrl?: string;
+      url?: string;
+      src?: string;
+      encodingFormat?: string;
+      mimeType?: string;
+      [key: string]: unknown;
+    }
+  | null
+  | undefined;
+
+export interface ImageUrlOptions {
+  /** Print-product sizing. Default: the host's `$uhuu.is.printProduct()` (false without a host). */
+  print?: boolean;
+  /** Screen size as `WxH`. Default `2000x2000`. */
+  size?: string;
+  /** Print size as `WxH`. Default `4000x4000`. */
+  printSize?: string;
+  /** Thumbnail output format, e.g. `image/jpeg`. Default: the source's own (keeps transparency). */
+  format?: string;
+}
+
+/**
+ * The thumbnailer URL to render an image at: print-aware size, encoded source URL, SVG/`data:`/
+ * relative sources passed through, already-thumbnailed URLs rebuilt rather than nested.
+ * No image returns `undefined`, which renders no `src` attribute.
+ */
+export function imageUrl(src: ImageSource, options?: ImageUrlOptions): string | undefined;
+
+// --- Brand-kit runtime (src/uhuu/brand-kit/). See docs/brand-kit-runtime.md. ---
+
+export interface BrandKitFontFile {
+  src: string;
+  weight?: number | string;
+  style?: "normal" | "italic";
+  format?: string;
+}
+
+export interface BrandKitFont {
+  id?: string;
+  family?: string;
+  /** Role-keyed fonts (`fonts.body`, `fonts.heading`): the stack after `family`. */
+  fallback?: string;
+  source?: string;
+  provider?: string;
+  cssUrl?: string;
+  weights?: number[];
+  styles?: Array<"normal" | "italic">;
+  files?: BrandKitFontFile[];
+  faces?: Array<{
+    weight?: number;
+    style?: "normal" | "italic";
+    cssUrl?: string;
+    files?: BrandKitFontFile[] | Record<string, string>;
+    [key: string]: unknown;
+  }>;
+  [key: string]: unknown;
+}
+
+/** A brandkit.json document. Only the parts the runtime reads are typed. */
+export interface BrandKitJson {
+  version?: string | number;
+  id?: string;
+  name?: string;
+  baseUrl?: string;
+  assignments?: Record<string, string>;
+  fonts?: Record<string, BrandKitFont> | BrandKitFont[];
+  tokens?: {
+    light?: {
+      semantic?: Record<string, string | undefined>;
+      aliases?: Record<string, string | Record<string, string | undefined> | undefined>;
+    };
+    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 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. */
+  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 `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;
+  children?: ReactNode;
+}
+
+/**
+ * Scopes a kit's CSS variables around the pages and their overlay chrome, on a `display: contents`
+ * 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;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.97",
+  "version": "0.3.0",
   "name": "uhuu-components",
   "main": "uhuu-components.umd.cjs",
   "module": "uhuu-components.es.js",