@bettercms-ai/kit 0.1.1 → 2.0.0

package/dist/adapters/values.d.ts

@@ -0,0 +1,221 @@
+/**
+ * VALUE ADAPTERS — a V2 stored value ↔ the value production stores for the same field (Lane C map,
+ * docs/design-system/v2-map/C-controls.md §2, updated for F1). Storage stays prod's: `*ToProd` returns what the
+ * backend accepts, `*FromProd` the V2 shape the kit controls edit.
+ *
+ * Every `*ToProd` returns `{ value, lost }`. `lost` names the V2 keys prod cannot keep (relative to the value), so
+ * `*FromProd(*ToProd(v).value)` equals `v` minus exactly those keys. Nothing is dropped without being named.
+ */
+import type { ScaleSchema, ScaleValue } from "../schema/types";
+import type { TableValue } from "../schema/table";
+import { type DockIconName, type ProdButtonValue, type ProdFormRef, type ProdImageCrop, type ProdImageValue, type ProdLinkValue, type ProdPolymorphicRef, type ProdTargetRef, type ProdVideoValue } from "./prod-types";
+export interface ValueResult<T> {
+    value: T;
+    /** V2 keys (dotted, relative to the value) production cannot keep. */
+    lost: string[];
+}
+export type V2LinkType = "page" | "entry" | "url" | "section" | "email" | "phone" | "file";
+export type V2ButtonStyle = "primary" | "secondary" | "outline" | "link";
+export interface V2LinkValue {
+    type?: V2LinkType;
+    href: string;
+    label?: string;
+    title?: string;
+    pageId?: string;
+    entryId?: string;
+    anchor?: string;
+    assetId?: string;
+    email?: string;
+    subject?: string;
+    phone?: string;
+    target?: "_self" | "_blank";
+    newTab?: boolean;
+    rel?: "follow" | "nofollow" | "ugc" | "sponsored";
+}
+export interface V2ButtonValue extends V2LinkValue {
+    style?: V2ButtonStyle;
+    variant?: V2ButtonStyle;
+    size?: "sm" | "md" | "lg";
+    arrow?: boolean;
+    icon?: string;
+    fullWidth?: boolean;
+}
+export type V2ImageCrop = "original" | "16:9" | "4:3" | "1:1" | "4:5";
+export interface V2ImageValue {
+    url: string;
+    alt?: string;
+    /** percent */
+    focal?: {
+        x: number;
+        y: number;
+    };
+    /** A preset to cut (written as its rect, so it needs the size), or the stored rect itself, carried as it was read. */
+    crop?: V2ImageCrop | ProdImageCrop;
+    caption?: string;
+    name?: string;
+    width?: number;
+    height?: number;
+    size?: number;
+    id?: string;
+}
+/**
+ * F1 stores the V2 link object as sent (link-value.ts: the kit's pageId, entryId, anchor, email, phone, label… are
+ * kept), plus `ref` for a page / entry link so delivery resolves it. A bare href string stays a string.
+ */
+export declare function linkToProd(v: V2LinkValue | string | null | undefined): ValueResult<ProdLinkValue | string | null>;
+export declare function linkFromProd(v: unknown): V2LinkValue | string | null;
+/**
+ * A V2 button is a link with a label and a look, flattened. Prod's ButtonValue reads `label`, `href` (string or link
+ * object), `variant`, `size`, `arrow`, `icon` (a dock icon name), `newTab`, `rel`; other keys are kept and ignored,
+ * so the link half (type, pageId, anchor…) rides along as sent. The look is written as `variant` (what renderers read).
+ */
+export declare function buttonToProd(v: V2ButtonValue | null | undefined): ValueResult<ProdButtonValue | null>;
+export declare function buttonFromProd(v: unknown): V2ButtonValue | null;
+/** A date is the same "YYYY-MM-DD" string on both sides. */
+export declare const dateToProd: (v: string | null | undefined) => ValueResult<string | null>;
+export declare const dateFromProd: (v: unknown) => string | null;
+/**
+ * V2 stores RFC 9557 (`2026-10-14T09:00:00+05:30[Asia/Kolkata]`). Prod keeps the ISO instant with seconds and its
+ * offset; a `[Zone]` suffix is checked and dropped on write. So the zone survives only as the field's own
+ * `config.timezone` when that names it (pass it as `zone`); otherwise it is lost.
+ */
+export declare function datetimeToProd(v: string | null | undefined, opts?: {
+    zone?: string;
+}): ValueResult<string | null>;
+export declare function datetimeFromProd(v: unknown, opts?: {
+    zone?: string;
+}): string | null;
+/** A crop preset → the centred-on-focal rect prod stores. Needs the image's pixel size. */
+export declare function cropRect(crop: V2ImageCrop, width: number, height: number, focal?: {
+    x: number;
+    y: number;
+}): ProdImageCrop | undefined;
+/** A stored rect → the preset whose aspect it cuts (within 1%), when the image's pixel size is known. */
+export declare function cropPreset(rect: ProdImageCrop, width: number, height: number): V2ImageCrop | undefined;
+/** The asset facts an image value refers to but prod does not store in the value (width, height, size). */
+export interface ImageAsset {
+    width?: number;
+    height?: number;
+    size?: number;
+}
+/**
+ * The contract holds against `imageFromProd(value)` with no asset (how stored defaults are read): a crop rect needs the
+ * image's pixel size to read back as its preset, and width / height / size live on the asset, so all four are named in
+ * `lost`. Passing the asset to imageFromProd restores them.
+ */
+export declare function imageToProd(v: V2ImageValue | string | null | undefined): ValueResult<ProdImageValue | string | null>;
+/** A crop window as prod stores it: four 0–1 edges that leave something on both axes. */
+export declare function isCropRect(v: unknown): v is ProdImageCrop;
+/**
+ * Pass the asset's pixel size to read a stored crop rect back as its preset and to restore width / height / size.
+ * An older value written as `{ src, alt }` (the block's own image props) reads as the same picture and alt text.
+ */
+export declare function imageFromProd(v: unknown, asset?: ImageAsset): V2ImageValue | string | null;
+export declare const targetTag: (kind: ProdTargetRef["kind"], id: string) => string;
+export declare function parseTargetTag(v: string): ProdTargetRef | null;
+/**
+ * V2 stores the target id (`"en_12"`; a list for many). Prod stores the same id, or `{ entryId, modelSlug }` on a
+ * polymorphic field (pass `modelSlug`), or `{ formId }` on a component `form` prop (`to: "form"`), or `{ kind, id }` for
+ * a tagged page / form / collection pick (`"page:pg_1"`).
+ */
+export declare function referenceToProd(v: string | string[] | null | undefined, opts?: {
+    to?: "form";
+    modelSlug?: string;
+}): ValueResult<string | (string | ProdTargetRef)[] | ProdPolymorphicRef | ProdFormRef | ProdTargetRef | null>;
+export declare function referenceFromProd(v: unknown): string | string[] | null;
+/**
+ * Prod has no table type: the schema adapter stores a V2 table as a `json` field (named in the lossy ledger), and
+ * `json` keeps any JSON value, so the TableValue itself is stored verbatim (typed columns, groups, footer,
+ * footnotes, caption, design, jsonLd).
+ */
+export declare function tableToProd(v: TableValue | null | undefined): ValueResult<TableValue | null>;
+export declare const tableFromProd: (v: unknown) => TableValue | null;
+/**
+ * Prod stores the three V2 scale shapes as they are (CPO D41, reference-validation.ts scaleValueProblem): a bare number,
+ * a token step's string, a custom `{ value, unit }`. Pass the field's scale: a token it does not list, or a custom value
+ * it does not allow (allowCustom off, a unit outside its units, past its bounds), is refused by the backend, so it is
+ * not written (`lost: [""]`). With no scale only a number is known to fit.
+ */
+export declare function scaleToProd(v: ScaleValue | null | undefined, scale?: ScaleSchema): ValueResult<ScaleValue | null>;
+export declare function scaleFromProd(v: unknown): ScaleValue | null;
+export type V2VideoValue = string | {
+    url: string;
+    poster?: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    transcript?: string;
+};
+/**
+ * The V2 video value and prod's are the same shape: a URL string, or `{ url, poster?, autoplay?, loop?, transcript? }`
+ * (the video block's props). The backend refuses any other key, and a url or poster that is not an http(s) URL or a
+ * site path (video_value_invalid): another key is left out and named, a bad url refuses the value whole.
+ */
+export declare function videoToProd(v: V2VideoValue | null | undefined): ValueResult<ProdVideoValue | string | null>;
+export declare function videoFromProd(v: unknown): V2VideoValue | null;
+export type ListItemType = "text" | "number" | "date" | "image" | "link" | "richtext";
+/**
+ * A V2 list of one primitive (`of: [{ type }]`) is a prod `array` with `config.itemType`, each item judged and normalized
+ * as a field of its type: an image item stores prod's image keys (altText, 0–1 focal), a link item its stored link. Scalar
+ * and rich text items pass as they are. `lost` names `<index>/<key>` (or `<index>` for a whole item) per item.
+ */
+export declare function listToProd(v: unknown, itemType: ListItemType): ValueResult<unknown[] | null>;
+export declare function listFromProd(v: unknown, itemType: ListItemType): unknown[];
+/**
+ * The backend judges tags trimmed and case-insensitively (reference-validation.ts tagsValueProblem): a field write
+ * trims and de-dupes, a prop value is refused (tags_value_invalid). So the value is written clean for both: trimmed,
+ * first spelling of a case-repeat kept, and an empty, over-long, off-list (`allowCustom: false`) or over-`max` tag left
+ * out. `lost` names each changed or dropped tag by its index in `v`.
+ */
+export declare function tagsToProd(v: string[] | null | undefined, opts?: {
+    max?: number;
+    allowCustom?: boolean;
+    options?: (string | {
+        value: string;
+    })[];
+}): ValueResult<string[] | null>;
+export declare const tagsFromProd: (v: unknown) => string[];
+export interface RatingScale {
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * A prod rating runs from config.min (0 unset) to config.max (5 unset) in steps of config.step (1 unset), and 0 is "not
+ * rated" on every scale (validation-parity.ts ratingScale / onRatingScale). V2's empty rating is null: it is written as
+ * null, and any other number off the scale is refused by the backend (rating_value_invalid), so it is not written either.
+ */
+export declare function ratingToProd(v: number | null | undefined, opts?: RatingScale): ValueResult<number | null>;
+/** A stored number back; 0 on a scale that starts above it is prod's "not rated", which V2 holds as null. */
+export declare function ratingFromProd(v: unknown, opts?: RatingScale): number | null;
+export type V2CodeValue = string | {
+    language?: string;
+    code: string;
+};
+/**
+ * Prod stores a code value as a string, or `{ language?, code }` (no other key). A language outside the field's
+ * `config.languages` is refused by the backend (code_value_invalid), so it is left out and named; a value over
+ * CODE_MAX_LENGTH characters is refused whole.
+ */
+export declare function codeToProd(v: V2CodeValue | null | undefined, opts?: {
+    languages?: string[];
+}): ValueResult<V2CodeValue | null>;
+export declare function codeFromProd(v: unknown): V2CodeValue | null;
+/** A V2 list of object items is stored by prod as the repeatable zone of its array: `{ repeatable: [...] }`. */
+export declare const zoneListToProd: (v: unknown[] | null | undefined) => {
+    repeatable: unknown[];
+};
+export declare const zoneListFromProd: (v: unknown) => unknown[];
+/** A row of a polymorphic list: V2's and prod's shape alike, `{ _key?, _type, ...fields }` (BE prop-fields typedRowIssues). */
+export type TypedRow = Record<string, unknown> & {
+    _type: string;
+    _key?: string;
+};
+/**
+ * V2 rows → the stored rows. Prod keeps V2's own row shape, so a row passes as it is after `mapRow` (its fields through
+ * their plans); a row with no `_type` has no item type to be judged by (item_type_required) and is named, by index.
+ */
+export declare function typedRowsToProd(v: unknown, mapRow?: (row: TypedRow, i: number) => Record<string, unknown>): ValueResult<unknown>;
+/** Stored rows → V2 rows: the same shape, each row through `mapRow`; a row that is not typed passes as stored. */
+export declare function typedRowsFromProd(v: unknown, mapRow?: (row: TypedRow, i: number) => Record<string, unknown>): unknown;
+/** A dock icon name passes through; anything else is not a prod icon. */
+export declare const isDockIcon: (v: unknown) => v is DockIconName;