@foir/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,476 @@
+// src/components/EditorProvider.tsx
+import {
+  createContext,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+
+// src/protocol/constants.ts
+var PROTOCOL_VERSION = "1.0";
+var MAX_RESIZE_HEIGHT = 1e5;
+var DANGEROUS_PATH_SEGMENTS = [
+  "__proto__",
+  "constructor",
+  "prototype"
+];
+
+// src/protocol/validation.ts
+var VALID_EDITOR_TYPES = /* @__PURE__ */ new Set([
+  "ready",
+  "update-values",
+  "update-field",
+  "request-save",
+  "request-publish",
+  "resize",
+  "dirty",
+  "request-navigate",
+  "request-operation"
+]);
+var VALID_HOST_TYPES = /* @__PURE__ */ new Set([
+  "init",
+  "values-changed",
+  "variant-changed",
+  "save-result",
+  "publish-result",
+  "theme-changed",
+  "selection-changed",
+  "locale-changed",
+  "operation-result"
+]);
+function isSafeFieldPath(path) {
+  const segments = path.split(".");
+  return !segments.some((s) => DANGEROUS_PATH_SEGMENTS.includes(s));
+}
+function isValidEditorMessage(data) {
+  if (!data || typeof data !== "object") return false;
+  const msg = data;
+  if (typeof msg.type !== "string") return false;
+  if (!VALID_EDITOR_TYPES.has(msg.type)) return false;
+  if (!msg.payload || typeof msg.payload !== "object") return false;
+  switch (msg.type) {
+    case "update-field": {
+      const payload = msg.payload;
+      if (typeof payload.path !== "string") return false;
+      if (!isSafeFieldPath(payload.path)) return false;
+      break;
+    }
+    case "resize": {
+      const payload = msg.payload;
+      if (typeof payload.height !== "number") return false;
+      if (payload.height < 0 || payload.height > MAX_RESIZE_HEIGHT)
+        return false;
+      if (!Number.isFinite(payload.height)) return false;
+      break;
+    }
+    case "update-values": {
+      const payload = msg.payload;
+      if (!payload.values || typeof payload.values !== "object") return false;
+      break;
+    }
+    case "dirty": {
+      const payload = msg.payload;
+      if (typeof payload.isDirty !== "boolean") return false;
+      break;
+    }
+    case "request-navigate": {
+      const payload = msg.payload;
+      if (typeof payload.path !== "string") return false;
+      if (!payload.path.startsWith("/")) return false;
+      if (payload.path.length > 500) return false;
+      break;
+    }
+  }
+  return true;
+}
+function isValidHostMessage(data) {
+  if (!data || typeof data !== "object") return false;
+  const msg = data;
+  if (typeof msg.type !== "string") return false;
+  if (!VALID_HOST_TYPES.has(msg.type)) return false;
+  if (!msg.payload || typeof msg.payload !== "object") return false;
+  return true;
+}
+
+// src/client/platform-client.ts
+var PlatformClientError = class extends Error {
+  constructor(message, status, response) {
+    super(message);
+    this.status = status;
+    this.response = response;
+    this.name = "PlatformClientError";
+  }
+  status;
+  response;
+};
+function createPlatformClient(options) {
+  const { apiUrl, apiKey } = options;
+  return {
+    async query(query, variables) {
+      const res = await fetch(apiUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": apiKey
+        },
+        body: JSON.stringify({ query, variables })
+      });
+      if (!res.ok) {
+        throw new PlatformClientError(
+          `GraphQL request failed: ${res.status} ${res.statusText}`,
+          res.status
+        );
+      }
+      const json = await res.json();
+      if (json.errors?.length) {
+        throw new PlatformClientError(json.errors[0].message, void 0, json);
+      }
+      return json;
+    }
+  };
+}
+
+// src/components/EditorProvider.tsx
+import { jsx } from "react/jsx-runtime";
+var EditorContext = createContext(null);
+function getEnv(viteKey, nextKey) {
+  try {
+    const meta = import.meta?.env;
+    if (meta?.[viteKey]) return meta[viteKey];
+  } catch {
+  }
+  const proc = globalThis.process;
+  if (proc?.env?.[nextKey]) return proc.env[nextKey];
+  return void 0;
+}
+function EditorProvider({
+  children,
+  parentOrigin: parentOriginProp,
+  apiUrl: apiUrlProp,
+  onInit,
+  onValuesChanged,
+  onVariantChanged,
+  onSaveResult,
+  onPublishResult,
+  onThemeChanged,
+  onSelectionChanged,
+  onLocaleChanged
+}) {
+  const parentOrigin = parentOriginProp ?? getEnv("VITE_PARENT_ORIGIN", "NEXT_PUBLIC_PARENT_ORIGIN") ?? "*";
+  const apiUrl = apiUrlProp ?? getEnv("VITE_API_URL", "NEXT_PUBLIC_API_URL") ?? "http://localhost:4001/graphql";
+  if (parentOrigin === "*") {
+    console.error(
+      "[EditorSDK] No parentOrigin configured \u2014 the host<->editor channel is DISABLED for safety. Pass the `parentOrigin` prop or set VITE_PARENT_ORIGIN / NEXT_PUBLIC_PARENT_ORIGIN to the embedding origin."
+    );
+  }
+  const [isReady, setIsReady] = useState(false);
+  const [init, setInit] = useState(null);
+  const [theme, setTheme] = useState("light");
+  const [client, setClient] = useState(null);
+  const [configMode, setConfigMode] = useState("editor");
+  const [selectedFieldKeys, setSelectedFieldKeys] = useState([]);
+  const [selectableFields, setSelectableFields] = useState([]);
+  const [localeContext, setLocaleContext] = useState(
+    null
+  );
+  const onInitRef = useRef(onInit);
+  const onValuesChangedRef = useRef(onValuesChanged);
+  const onVariantChangedRef = useRef(onVariantChanged);
+  const onSaveResultRef = useRef(onSaveResult);
+  const onPublishResultRef = useRef(onPublishResult);
+  const onThemeChangedRef = useRef(onThemeChanged);
+  const onSelectionChangedRef = useRef(onSelectionChanged);
+  const onLocaleChangedRef = useRef(onLocaleChanged);
+  useEffect(() => {
+    onInitRef.current = onInit;
+    onValuesChangedRef.current = onValuesChanged;
+    onVariantChangedRef.current = onVariantChanged;
+    onSaveResultRef.current = onSaveResult;
+    onPublishResultRef.current = onPublishResult;
+    onThemeChangedRef.current = onThemeChanged;
+    onSelectionChangedRef.current = onSelectionChanged;
+    onLocaleChangedRef.current = onLocaleChanged;
+  }, [
+    onInit,
+    onValuesChanged,
+    onVariantChanged,
+    onSaveResult,
+    onPublishResult,
+    onThemeChanged,
+    onSelectionChanged,
+    onLocaleChanged
+  ]);
+  const postMessage = useCallback(
+    (message) => {
+      if (typeof window === "undefined" || !window.parent) return;
+      if (parentOrigin === "*") return;
+      window.parent.postMessage(message, parentOrigin);
+    },
+    [parentOrigin]
+  );
+  const updateValues = useCallback(
+    (values) => {
+      postMessage({ type: "update-values", payload: { values } });
+    },
+    [postMessage]
+  );
+  const updateField = useCallback(
+    (path, value2) => {
+      postMessage({ type: "update-field", payload: { path, value: value2 } });
+    },
+    [postMessage]
+  );
+  const requestSave = useCallback(() => {
+    postMessage({ type: "request-save", payload: {} });
+  }, [postMessage]);
+  const requestPublish = useCallback(() => {
+    postMessage({ type: "request-publish", payload: {} });
+  }, [postMessage]);
+  const resize = useCallback(
+    (height) => {
+      postMessage({ type: "resize", payload: { height } });
+    },
+    [postMessage]
+  );
+  const setDirty = useCallback(
+    (isDirty) => {
+      postMessage({ type: "dirty", payload: { isDirty } });
+    },
+    [postMessage]
+  );
+  const requestNavigate = useCallback(
+    (path) => {
+      postMessage({ type: "request-navigate", payload: { path } });
+    },
+    [postMessage]
+  );
+  const pendingOperationsRef = useRef(/* @__PURE__ */ new Map());
+  const requestOperation = useCallback(
+    (operationKey, input, options) => {
+      const requestId = crypto.randomUUID();
+      return new Promise((resolve) => {
+        pendingOperationsRef.current.set(requestId, { resolve });
+        postMessage({
+          type: "request-operation",
+          payload: { operationKey, input, requestId, mode: options?.mode ?? "sync" }
+        });
+        setTimeout(() => {
+          if (pendingOperationsRef.current.has(requestId)) {
+            pendingOperationsRef.current.delete(requestId);
+            resolve({
+              success: false,
+              error: { code: "TIMEOUT", message: "Operation timed out" }
+            });
+          }
+        }, 6e4);
+      });
+    },
+    [postMessage]
+  );
+  useEffect(() => {
+    postMessage({ type: "ready", payload: {} });
+  }, [postMessage]);
+  useEffect(() => {
+    const handleMessage = (event) => {
+      if (parentOrigin === "*" || event.origin !== parentOrigin) return;
+      if (!isValidHostMessage(event.data)) return;
+      const message = event.data;
+      switch (message.type) {
+        case "init": {
+          const initData = message.payload;
+          const effectiveApiUrl = initData.apiUrl || apiUrl;
+          setIsReady(true);
+          setInit(initData);
+          setTheme(initData.theme);
+          setClient(
+            createPlatformClient({
+              apiUrl: effectiveApiUrl,
+              apiKey: initData.apiKey
+            })
+          );
+          if (initData.configMode) setConfigMode(initData.configMode);
+          if (initData.selectedFieldKeys)
+            setSelectedFieldKeys(initData.selectedFieldKeys);
+          if (initData.selectableFields)
+            setSelectableFields(initData.selectableFields);
+          if (initData.localeContext !== void 0)
+            setLocaleContext(initData.localeContext ?? null);
+          onInitRef.current?.(initData);
+          break;
+        }
+        case "values-changed":
+          onValuesChangedRef.current?.(message.payload.values);
+          break;
+        case "variant-changed":
+          onVariantChangedRef.current?.(
+            message.payload.variantKey,
+            message.payload.values
+          );
+          break;
+        case "save-result":
+          onSaveResultRef.current?.(
+            message.payload.success,
+            message.payload.error,
+            message.payload.versionId
+          );
+          break;
+        case "publish-result":
+          onPublishResultRef.current?.(
+            message.payload.success,
+            message.payload.error
+          );
+          break;
+        case "theme-changed":
+          setTheme(message.payload.theme);
+          onThemeChangedRef.current?.(message.payload.theme);
+          break;
+        case "selection-changed":
+          setSelectedFieldKeys(message.payload.selectedFieldKeys);
+          setSelectableFields(message.payload.fields);
+          onSelectionChangedRef.current?.(
+            message.payload.selectedFieldKeys,
+            message.payload.fields
+          );
+          break;
+        case "locale-changed":
+          setLocaleContext(message.payload);
+          onLocaleChangedRef.current?.(message.payload);
+          break;
+        case "operation-result": {
+          const { requestId, ...result } = message.payload;
+          const pending = pendingOperationsRef.current.get(requestId);
+          if (pending) {
+            pendingOperationsRef.current.delete(requestId);
+            pending.resolve(result);
+          }
+          break;
+        }
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  }, [parentOrigin, apiUrl]);
+  const noopClient = useMemo(
+    () => ({
+      async query() {
+        throw new Error(
+          "[EditorSDK] Client not ready \u2014 waiting for init from host."
+        );
+      }
+    }),
+    []
+  );
+  const value = useMemo(
+    () => ({
+      isReady,
+      init,
+      theme,
+      client: client ?? noopClient,
+      updateValues,
+      updateField,
+      requestSave,
+      requestPublish,
+      resize,
+      setDirty,
+      requestNavigate,
+      requestOperation,
+      configMode,
+      selectedFieldKeys,
+      selectableFields,
+      localeContext
+    }),
+    [
+      isReady,
+      init,
+      theme,
+      client,
+      noopClient,
+      updateValues,
+      updateField,
+      requestSave,
+      requestPublish,
+      resize,
+      setDirty,
+      requestNavigate,
+      requestOperation,
+      configMode,
+      selectedFieldKeys,
+      selectableFields,
+      localeContext
+    ]
+  );
+  return /* @__PURE__ */ jsx(EditorContext.Provider, { value, children });
+}
+
+// src/hooks/useEditor.ts
+import { useContext } from "react";
+function useEditor() {
+  const ctx = useContext(EditorContext);
+  if (!ctx) {
+    throw new Error(
+      "[EditorSDK] useEditor must be used inside <EditorProvider>."
+    );
+  }
+  return ctx;
+}
+
+// src/hooks/useAutoResize.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2 } from "react";
+function useAutoResize(options = {}) {
+  const { minHeight = 400, debounce = 100, enabled = true } = options;
+  const { isReady, resize } = useEditor();
+  const observerRef = useRef2(null);
+  const timeoutRef = useRef2(
+    void 0
+  );
+  const elementRef = useRef2(null);
+  const cleanup = useCallback2(() => {
+    if (observerRef.current) {
+      observerRef.current.disconnect();
+      observerRef.current = null;
+    }
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = void 0;
+    }
+  }, []);
+  const callbackRef = useCallback2(
+    (node) => {
+      cleanup();
+      elementRef.current = node;
+      if (!node || !enabled || !isReady) return;
+      const reportHeight = () => {
+        if (!elementRef.current) return;
+        const height = Math.max(elementRef.current.scrollHeight, minHeight);
+        resize(height);
+      };
+      reportHeight();
+      const observer = new ResizeObserver(() => {
+        if (timeoutRef.current) clearTimeout(timeoutRef.current);
+        timeoutRef.current = setTimeout(reportHeight, debounce);
+      });
+      observer.observe(node);
+      observerRef.current = observer;
+    },
+    [isReady, enabled, minHeight, debounce, resize, cleanup]
+  );
+  useEffect2(() => {
+    if (elementRef.current) {
+      callbackRef(elementRef.current);
+    }
+  }, [callbackRef]);
+  useEffect2(() => cleanup, [cleanup]);
+  return callbackRef;
+}
+export {
+  EditorProvider,
+  PROTOCOL_VERSION,
+  PlatformClientError,
+  createPlatformClient,
+  isValidEditorMessage,
+  isValidHostMessage,
+  useAutoResize,
+  useEditor
+};

package/dist/media.d.ts

@@ -0,0 +1,234 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Foir media types + adapters.
+ *
+ * Framework-agnostic plumbing for rendering Foir image/video fields with
+ * `<ProgressiveMedia>`: the canonical source shapes, GraphQL-value → source
+ * adapters (crop normalization, per-format variant sets, HLS URL
+ * absolutising), and crop-aware dimension maths for CLS-free layout.
+ *
+ * HLS manifest URLs are absolutised via the shared `absolutiseFoirMediaUrl`
+ * from the client transport — not re-implemented here.
+ */
+/** One rendered tier: a URL + its TRUE (crop-aware) dims (for srcset `w` + CLS). */
+interface VariantTier {
+    url: string;
+    width?: number | null;
+    height?: number | null;
+}
+/** Curated tier set in one format (Foir `ImageVariantSet`). */
+interface VariantSet {
+    thumbnail?: VariantTier | null;
+    small?: VariantTier | null;
+    medium?: VariantTier | null;
+    large?: VariantTier | null;
+    xlarge?: VariantTier | null;
+    _2xl?: VariantTier | null;
+    _3xl?: VariantTier | null;
+    _4xl?: VariantTier | null;
+}
+/** A `VariantSet` tier name. */
+type VariantTierKey = keyof VariantSet;
+/**
+ * Default tier order, smallest→largest, for walking a `VariantSet`
+ * deterministically when building a `srcset`. Override per `<ProgressiveMedia>`
+ * via the `variantTiers` prop when a project curates a different tier set.
+ */
+declare const DEFAULT_VARIANT_TIERS: readonly VariantTierKey[];
+/** Image source with progressive loading data. */
+interface ProgressiveImageSource {
+    url: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    blurhash?: string;
+    dominantColor?: string;
+    thumbnailUrl?: string;
+    /** Per-format tier sets (WebP universal; AVIF preferred via `<picture>`). */
+    webp?: VariantSet | null;
+    avif?: VariantSet | null;
+    /**
+     * Optional crop rectangle expressed as percentages of the source image
+     * (`{x, y, width, height}` in 0–100). Foir's image pipeline serves the
+     * cropped file at the cropped dimensions, so consumers need this to compute
+     * correct `width`/`height` attrs for CLS-free rendering.
+     */
+    crop?: {
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+    };
+}
+/** Video source with progressive loading data + optional HLS. */
+interface ProgressiveVideoSource {
+    url: string;
+    width?: number;
+    height?: number;
+    blurhash?: string;
+    dominantColor?: string;
+    thumbnailUrl?: string;
+    previewUrl?: string;
+    hlsUrl?: string;
+    duration?: number;
+}
+/**
+ * Foir GraphQL `ImageValue`-like input — the shape a consumer's codegen
+ * produces for an image field (intrinsic dims + per-format variant sets +
+ * crop as opaque JSON). Structurally compatible with the generated type.
+ */
+interface FoirImageInput {
+    url?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+    blurhash?: string | null;
+    dominantColor?: string | null;
+    webp?: VariantSet | null;
+    avif?: VariantSet | null;
+    crop?: {
+        [key: string]: unknown;
+    } | null;
+}
+/** Foir GraphQL `VideoValue`-like input. */
+interface FoirVideoInput {
+    url?: string | null;
+    width?: number | null;
+    height?: number | null;
+    hlsManifestUrl?: string | null;
+    thumbnailUrl?: string | null;
+    previewUrl?: string | null;
+    blurhash?: string | null;
+    dominantColor?: string | null;
+}
+/**
+ * Adapt a Foir image field to the `ProgressiveImageSource` consumed by
+ * `<ProgressiveMedia>`. Returns `undefined` when the field is empty (the
+ * caller falls back to a placeholder). Narrows the JSON-typed `crop` to the
+ * numeric keys; out-of-range values are filtered in `effectiveImageDimensions`.
+ */
+declare function toProgressiveImage(img: FoirImageInput | null | undefined): ProgressiveImageSource | undefined;
+/**
+ * Adapt a Foir video field to the `ProgressiveVideoSource` consumed by
+ * `<ProgressiveMedia>`. Absolutises the HLS manifest URL (Foir returns it
+ * relative to its media proxy). Returns `undefined` when the field is empty.
+ */
+declare function toProgressiveVideo(v: FoirVideoInput | null | undefined): ProgressiveVideoSource | undefined;
+/**
+ * Resolve the dimensions of the file Foir's pipeline will actually serve,
+ * applying any crop percentages to the source's intrinsic size. Returns null
+ * when the source has no width/height. Drives both the wrapper aspect-ratio
+ * and the `<img>` `width`/`height` attrs.
+ */
+declare function effectiveImageDimensions(image: {
+    width?: number | null;
+    height?: number | null;
+    crop?: unknown;
+} | null | undefined): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * Compute a CSS `aspect-ratio` string from a Foir image's natural dimensions
+ * and optional crop. When a usable crop is set the cropped rectangle's aspect
+ * wins; otherwise the intrinsic width/height; otherwise `null`.
+ */
+declare function cropAspectRatio(image: {
+    width?: number | null;
+    height?: number | null;
+    crop?: unknown;
+} | null | undefined): string | null;
+
+interface ProgressiveMediaProps {
+    image?: ProgressiveImageSource;
+    video?: ProgressiveVideoSource;
+    alt?: string;
+    className?: string;
+    /** Fill the parent container instead of using intrinsic aspect ratio. */
+    fill?: boolean;
+    /**
+     * Object-fit for fill mode. Defaults to 'cover'. Has no effect when `fill`
+     * is false (the image renders at its intrinsic aspect ratio).
+     */
+    fit?: 'cover' | 'contain';
+    /**
+     * Solid-colour placeholder mode. When neither image nor video is provided,
+     * render a flat coloured div. `aspectRatio` defaults to 16/10.
+     */
+    placeholder?: {
+        color: string;
+        aspectRatio?: number;
+    };
+    /** Video playback — autoplay on mount. Default true. */
+    autoplay?: boolean;
+    /** Video playback — muted. Default true (required for autoplay). */
+    muted?: boolean;
+    /** Video playback — loop on end. Default true. */
+    loop?: boolean;
+    /**
+     * When false, skip loading the full media layer (no `<video>`/full `<img>`
+     * mount, no HLS attach, no full-image preload). The lower layers — colour,
+     * blurhash, thumbnail — still render. Used by responsive dual-render so the
+     * CSS-hidden branch doesn't download its full asset. Default true.
+     */
+    active?: boolean;
+    /**
+     * `sizes` attribute applied to the full `<img>` — tells the browser how
+     * wide the image renders so it can pick the right `srcset` entry. Default
+     * `"100vw"`. Has no effect on video sources.
+     */
+    sizes?: string;
+    /**
+     * When true, treat this media as the page's LCP candidate: thumbnail and
+     * full `<img>` get `fetchpriority="high"` + `loading="eager"`, and any
+     * `<video>` mounts immediately. When false (default) below-fold behaviour:
+     * `loading="lazy"` on `<img>`, and `<video>` is gated by an
+     * IntersectionObserver so its `src`/HLS only attaches near the viewport.
+     */
+    priority?: boolean;
+    /**
+     * Tier order, smallest→largest, used to build the `srcset` from a
+     * `VariantSet`. Defaults to {@link DEFAULT_VARIANT_TIERS}; override when a
+     * project curates a different tier set.
+     */
+    variantTiers?: readonly VariantTierKey[];
+}
+declare function ProgressiveMedia({ image, video, alt, className, fill, fit, placeholder, autoplay, muted, loop, active, sizes, priority, variantTiers, }: ProgressiveMediaProps): react_jsx_runtime.JSX.Element | null;
+
+interface BlurhashCanvasProps {
+    hash: string;
+    className?: string;
+}
+/**
+ * Decodes a BlurHash string to a 32×32 canvas. `blurhash` is an optional peer
+ * dependency loaded via dynamic import — if it isn't installed the canvas
+ * stays blank rather than throwing.
+ */
+declare function BlurhashCanvas({ hash, className }: BlurhashCanvasProps): react_jsx_runtime.JSX.Element;
+
+type LoadStage = 'color' | 'blurhash' | 'thumbnail' | 'full';
+interface UseProgressiveLoadOptions {
+    blurhash?: string;
+    thumbnailUrl?: string;
+    fullUrl?: string;
+    /**
+     * Optional srcset + sizes — when provided to image sources, the preloader
+     * matches the variant the visible `<img>` will pick, so the browser dedupes
+     * the fetch instead of downloading two sizes.
+     */
+    fullSrcSet?: string;
+    fullSizes?: string;
+    isVideo?: boolean;
+}
+/**
+ * State machine for progressive media loading.
+ * Stages advance forward only: color → blurhash → thumbnail → full.
+ * Skips stages when data is missing. Never regresses.
+ */
+declare function useProgressiveLoad({ blurhash, thumbnailUrl, fullUrl, fullSrcSet, fullSizes, isVideo, }: UseProgressiveLoadOptions): {
+    stage: LoadStage;
+    onFullReady: () => void;
+};
+
+export { BlurhashCanvas, type BlurhashCanvasProps, DEFAULT_VARIANT_TIERS, type FoirImageInput, type FoirVideoInput, type LoadStage, type ProgressiveImageSource, ProgressiveMedia, type ProgressiveMediaProps, type ProgressiveVideoSource, type UseProgressiveLoadOptions, type VariantSet, type VariantTier, type VariantTierKey, cropAspectRatio, effectiveImageDimensions, toProgressiveImage, toProgressiveVideo, useProgressiveLoad };