@foir/sdk 0.1.0

package/dist/codegen/index.d.ts

@@ -0,0 +1,65 @@
+import { CodegenConfig } from '@graphql-codegen/cli';
+export { B as BlockPluginConfig } from '../shared-DkWlEd2Z.js';
+
+/**
+ * `@foir/sdk/codegen` — the Foir graphql-codegen preset.
+ *
+ * `foirCodegen()` returns a complete `@graphql-codegen/client-preset` config so
+ * a consumer's `codegen.ts` is ~3 lines instead of the ~109 every storefront
+ * hand-copies. It standardizes the Foir conventions (custom scalars,
+ * `enumValues: 'keep'`, the `X-Foir-Schema-Channel: draft` introspection header)
+ * AND wires the block-registry plugin so the exhaustive `BlockRegistry` type is
+ * regenerated alongside the typed documents.
+ *
+ * `foirScaffold()` is the separate one-shot that writes the ContentRenderer
+ * shell (run once; the dev owns the output).
+ */
+
+interface FoirCodegenOptions {
+    /** Foir public API GraphQL endpoint. */
+    apiUrl: string;
+    /**
+     * Public (`pk_`) API key. Reads the published schema. Used as the fallback
+     * when no preview key is set.
+     */
+    apiKey?: string;
+    /**
+     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
+     * freshly pushed (un-promoted) model changes are visible to codegen.
+     * Strongly preferred — a `pk_` key only sees the published schema.
+     */
+    previewKey?: string;
+    /** Output directory for the generated client types. Default `./app/gql/foir/`. */
+    outputDir?: string;
+    /** Operation document glob(s). Default `app/graphql/foir/**\/*.graphql`. */
+    documents?: string | string[];
+    /** Block union name(s) for the registry. Default `['Block']`. */
+    blockUnions?: string[];
+    /** Generated registry file path. Default `<outputDir>block-registry.ts`. */
+    registryFile?: string;
+    /** Extra/override custom scalars merged onto the Foir defaults. */
+    scalars?: Record<string, unknown>;
+}
+/**
+ * Build the continuous Foir codegen config: typed documents + the exhaustive
+ * block registry. Drop it into `codegen.ts` and run `graphql-codegen`.
+ */
+declare function foirCodegen(options: FoirCodegenOptions): CodegenConfig;
+interface FoirScaffoldOptions extends FoirCodegenOptions {
+    /** Output path for the scaffold. Default `<outputDir>ContentRenderer.tsx`. */
+    scaffoldFile?: string;
+    /** Render-context type threaded to every block component. Default `unknown`. */
+    ctxType?: string;
+    /** Optional ctx-type import line, e.g. `import type { Ctx } from '~/ctx'`. */
+    ctxImport?: string;
+    /** Import path for the generated registry type. Default `./block-registry`. */
+    registryImport?: string;
+}
+/**
+ * Build the one-shot scaffold config — writes a ContentRenderer shell with a
+ * typed stub per block type. Run once (`graphql-codegen --config scaffold.ts`),
+ * then own and implement the output.
+ */
+declare function foirScaffold(options: FoirScaffoldOptions): CodegenConfig;
+
+export { type FoirCodegenOptions, type FoirScaffoldOptions, foirCodegen, foirScaffold };

package/dist/codegen/index.js

@@ -0,0 +1,80 @@
+import {
+  DEFAULT_UNIONS
+} from "../chunk-ADO5FJNM.js";
+
+// src/codegen/preset.ts
+var DEFAULT_OUTPUT_DIR = "./app/gql/foir/";
+var DEFAULT_DOCUMENTS = "app/graphql/foir/**/*.graphql";
+var FOIR_SCALARS = {
+  JSON: { input: "unknown", output: "{ [key: string]: unknown }" },
+  DateTime: "string"
+};
+function normalizeDir(dir) {
+  return dir.endsWith("/") ? dir : `${dir}/`;
+}
+function schemaEntry(apiUrl, key) {
+  return [
+    {
+      [apiUrl]: {
+        headers: {
+          "x-api-key": key ?? "",
+          // Read the draft channel so freshly pushed changes are visible
+          // (silently ignored by public keys, which can't see drafts).
+          "X-Foir-Schema-Channel": "draft"
+        }
+      }
+    }
+  ];
+}
+function foirCodegen(options) {
+  const previewKey = options.previewKey ?? options.apiKey;
+  const outputDir = normalizeDir(options.outputDir ?? DEFAULT_OUTPUT_DIR);
+  const documents = options.documents ?? DEFAULT_DOCUMENTS;
+  const blockUnions = options.blockUnions ?? DEFAULT_UNIONS;
+  const registryFile = options.registryFile ?? `${outputDir}block-registry.ts`;
+  return {
+    schema: schemaEntry(options.apiUrl, previewKey),
+    documents,
+    ignoreNoDocuments: true,
+    generates: {
+      [outputDir]: {
+        preset: "client",
+        presetConfig: { fragmentMasking: false },
+        config: {
+          useTypeImports: true,
+          namingConvention: { enumValues: "keep" },
+          scalars: { ...FOIR_SCALARS, ...options.scalars ?? {} }
+        }
+      },
+      [registryFile]: {
+        plugins: ["@foir/sdk/codegen/block-registry"],
+        config: { unions: blockUnions }
+      }
+    }
+  };
+}
+function foirScaffold(options) {
+  const previewKey = options.previewKey ?? options.apiKey;
+  const outputDir = normalizeDir(options.outputDir ?? DEFAULT_OUTPUT_DIR);
+  const scaffoldFile = options.scaffoldFile ?? `${outputDir}ContentRenderer.tsx`;
+  const blockUnions = options.blockUnions ?? DEFAULT_UNIONS;
+  return {
+    schema: schemaEntry(options.apiUrl, previewKey),
+    ignoreNoDocuments: true,
+    generates: {
+      [scaffoldFile]: {
+        plugins: ["@foir/sdk/codegen/block-scaffold"],
+        config: {
+          unions: blockUnions,
+          ctxType: options.ctxType,
+          ctxImport: options.ctxImport,
+          registryImport: options.registryImport
+        }
+      }
+    }
+  };
+}
+export {
+  foirCodegen,
+  foirScaffold
+};

package/dist/content.d.ts

@@ -0,0 +1,96 @@
+import { ReactNode, JSX } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * createContentRenderer — the generic content-dispatch primitive.
+ *
+ * It does NOT know any concrete block types. Given a registry that maps each
+ * block `__typename` to a component, it renders a `flexible` field's block
+ * array: looks each block up by `__typename`, renders unknown types as null,
+ * keys by the block `_id`, assigns LCP `priority` to the first block that
+ * actually renders, and threads a consumer-defined `Ctx` to every component.
+ *
+ * The "switch" is a typed object lookup. Exhaustiveness is enforced where the
+ * registry is BUILT — against the exhaustive `BlockRegistry` type the codegen
+ * plugin (EID-92) generates per project, so omitting a block type is a compile
+ * error there, not a runtime surprise here. The consumer can supply different
+ * registries per surface (e.g. web vs email).
+ */
+
+/** Minimal shape every block in a `flexible` field carries. */
+interface BlockLike {
+    __typename: string;
+    _id?: string | null;
+}
+/** Props a block component receives from the content renderer. */
+interface BlockComponentProps<TBlock, TCtx = unknown> {
+    block: TBlock;
+    /** Consumer-defined render context (host product, locale, etc.). */
+    ctx: TCtx;
+    /** True only for the first block that renders — the LCP candidate. */
+    priority: boolean;
+}
+/** A component that renders one block type. */
+type BlockComponent<TBlock, TCtx = unknown> = (props: BlockComponentProps<TBlock, TCtx>) => ReactNode;
+/**
+ * A registry mapping `__typename` → block component. In practice this is the
+ * exhaustive `BlockRegistry` type the codegen plugin emits for the project;
+ * here it's the structural lower bound the renderer needs.
+ */
+type BlockRegistry<TCtx = unknown> = Record<string, BlockComponent<any, TCtx>>;
+interface ContentRendererProps<TCtx> {
+    blocks: readonly BlockLike[] | null | undefined;
+    /** Consumer-defined context passed to every block component. */
+    ctx: TCtx;
+}
+/**
+ * Build a `<ContentRenderer>` bound to a block registry. Returns a component
+ * that takes the `flexible` field's `blocks` array plus a `ctx`.
+ */
+declare function createContentRenderer<TCtx = unknown>(registry: BlockRegistry<TCtx>): (props: ContentRendererProps<TCtx>) => ReactNode;
+
+/** A resolved typography token from the project's design tokens. */
+interface TypographyToken {
+    /** Token key referenced by a Lexical node's `style`. */
+    name: string;
+    /** Rendered HTML element (paragraph / h1–h6 / blockquote). */
+    tag?: string;
+    value: {
+        fontFamily: string[];
+        fontSize: string | number;
+        fontWeight: string | number;
+        lineHeight: string | number;
+        letterSpacing: string | number;
+        textTransform?: string;
+    };
+}
+/**
+ * Provide the project's resolved typography tokens to every nested
+ * `<RichTextRenderer>` so callers don't thread them through each usage. A
+ * `tokens` prop on the renderer still takes precedence.
+ */
+declare function RichTextTypographyProvider({ tokens, children, }: {
+    tokens: TypographyToken[];
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** Read the injected typography tokens (null when no provider is mounted). */
+declare function useRichTextTypography(): TypographyToken[] | null;
+interface RichtextValueLike {
+    html?: string | null;
+    json?: unknown;
+}
+interface RichTextRendererProps {
+    value: RichtextValueLike | null | undefined;
+    className?: string;
+    /**
+     * Resolved typography tokens. Overrides any provided via
+     * `<RichTextTypographyProvider>`. When neither is set, paragraphs render
+     * with `fallbackTag` and no inline typography.
+     */
+    tokens?: TypographyToken[];
+    /** Tag used for any paragraph with no token style and no Lexical tag. */
+    fallbackTag?: keyof JSX.IntrinsicElements;
+}
+declare function RichTextRenderer({ value, className, tokens, fallbackTag, }: RichTextRendererProps): react_jsx_runtime.JSX.Element | null;
+
+export { type BlockComponent, type BlockComponentProps, type BlockLike, type BlockRegistry, type ContentRendererProps, RichTextRenderer, type RichTextRendererProps, RichTextTypographyProvider, type TypographyToken, createContentRenderer, useRichTextTypography };

package/dist/content.js

@@ -0,0 +1,161 @@
+// src/content/content-renderer.tsx
+import { Fragment } from "react";
+import { Fragment as Fragment2, jsx } from "react/jsx-runtime";
+function createContentRenderer(registry) {
+  return function ContentRenderer({ blocks, ctx }) {
+    if (!blocks?.length) return null;
+    let priorityAssigned = false;
+    return /* @__PURE__ */ jsx(Fragment2, { children: blocks.map((block, i) => {
+      const Component = registry[block.__typename];
+      if (!Component) return null;
+      const priority = !priorityAssigned;
+      priorityAssigned = true;
+      return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(Component, { block, ctx, priority }) }, block._id ?? i);
+    }) });
+  };
+}
+
+// src/content/richtext.tsx
+import {
+  createContext,
+  createElement,
+  useContext
+} from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function safeHref(url) {
+  if (!url) return "#";
+  const trimmed = url.trim();
+  if (trimmed.startsWith("/") || trimmed.startsWith("#") || trimmed.startsWith("?") || trimmed.startsWith("./") || trimmed.startsWith("../")) {
+    return trimmed;
+  }
+  const normalized = Array.from(trimmed).filter((ch) => ch.charCodeAt(0) > 32).join("").toLowerCase();
+  const schemeMatch = normalized.match(/^([a-z][a-z0-9+.-]*):/);
+  if (!schemeMatch) return trimmed;
+  const allowed = ["http", "https", "mailto", "tel"];
+  return allowed.includes(schemeMatch[1]) ? trimmed : "#";
+}
+var TypographyContext = createContext(null);
+function RichTextTypographyProvider({
+  tokens,
+  children
+}) {
+  return /* @__PURE__ */ jsx2(TypographyContext.Provider, { value: tokens, children });
+}
+function useRichTextTypography() {
+  return useContext(TypographyContext);
+}
+var TEXT_FORMAT_BOLD = 1;
+var TEXT_FORMAT_ITALIC = 2;
+var TEXT_FORMAT_STRIKETHROUGH = 4;
+var TEXT_FORMAT_UNDERLINE = 8;
+var TEXT_FORMAT_CODE = 16;
+function RichTextRenderer({
+  value,
+  className,
+  tokens,
+  fallbackTag = "p"
+}) {
+  const contextTokens = useRichTextTypography();
+  const typography = tokens ?? contextTokens ?? [];
+  if (!value) return null;
+  if (!value.json) {
+    if (value.html) {
+      return /* @__PURE__ */ jsx2(
+        "div",
+        {
+          className,
+          dangerouslySetInnerHTML: { __html: value.html }
+        }
+      );
+    }
+    return null;
+  }
+  const root = value.json && typeof value.json === "object" ? value.json.root ?? null : null;
+  if (!root || !Array.isArray(root.children) || root.children.length === 0) {
+    return null;
+  }
+  const tokenMap = /* @__PURE__ */ new Map();
+  for (const t of typography) {
+    tokenMap.set(t.name, t);
+  }
+  return /* @__PURE__ */ jsx2("div", { className, children: root.children.map(
+    (node, i) => renderBlockNode(node, i, tokenMap, fallbackTag)
+  ) });
+}
+function renderBlockNode(node, key, tokens, fallbackTag) {
+  const type = node.type;
+  if (type === "paragraph" || type === "heading" || type === "quote") {
+    const styleKey = typeof node.style === "string" && node.style.length > 0 ? node.style : null;
+    const token = styleKey ? tokens.get(styleKey) ?? null : null;
+    const tag = pickTag(node, token, fallbackTag);
+    const styleProps = tokenToCss(token, node.format);
+    const children = (node.children ?? []).map(
+      (child, i) => renderInlineNode(child, i)
+    );
+    return createElement(tag, { key, style: styleProps }, ...children);
+  }
+  if (type === "list") {
+    const ordered = node.listType === "number";
+    const ListTag = ordered ? "ol" : "ul";
+    return /* @__PURE__ */ jsx2(ListTag, { children: (node.children ?? []).map((child, i) => /* @__PURE__ */ jsx2("li", { children: (child.children ?? []).map((c, j) => renderInlineNode(c, j)) }, i)) }, key);
+  }
+  if (Array.isArray(node.children)) {
+    return /* @__PURE__ */ jsx2("div", { children: node.children.map((child, i) => renderInlineNode(child, i)) }, key);
+  }
+  return null;
+}
+function renderInlineNode(node, key) {
+  if (node.type === "text") {
+    const formatBits = typeof node.format === "number" ? node.format : 0;
+    let el = node.text ?? "";
+    if (formatBits & TEXT_FORMAT_CODE) el = /* @__PURE__ */ jsx2("code", { children: el });
+    if (formatBits & TEXT_FORMAT_BOLD) el = /* @__PURE__ */ jsx2("strong", { children: el });
+    if (formatBits & TEXT_FORMAT_ITALIC) el = /* @__PURE__ */ jsx2("em", { children: el });
+    if (formatBits & TEXT_FORMAT_UNDERLINE) el = /* @__PURE__ */ jsx2("u", { children: el });
+    if (formatBits & TEXT_FORMAT_STRIKETHROUGH) el = /* @__PURE__ */ jsx2("s", { children: el });
+    return /* @__PURE__ */ jsx2("span", { children: el }, key);
+  }
+  if (node.type === "linebreak") return /* @__PURE__ */ jsx2("br", {}, key);
+  if (node.type === "link") {
+    const href = safeHref(node.url);
+    const target = node.target;
+    const rel = target && target !== "_self" ? "noopener noreferrer" : void 0;
+    return /* @__PURE__ */ jsx2("a", { href, target, rel, children: (node.children ?? []).map((c, i) => renderInlineNode(c, i)) }, key);
+  }
+  if (Array.isArray(node.children)) {
+    return /* @__PURE__ */ jsx2("span", { children: node.children.map((c, i) => renderInlineNode(c, i)) }, key);
+  }
+  return null;
+}
+function pickTag(node, token, fallback) {
+  if (token?.tag) return token.tag;
+  if (node.type === "heading" && typeof node.tag === "string") {
+    return node.tag;
+  }
+  if (node.type === "quote") return "blockquote";
+  return fallback;
+}
+function tokenToCss(token, paragraphFormat) {
+  const style = {};
+  if (token) {
+    const v = token.value;
+    style.fontFamily = v.fontFamily.join(", ");
+    style.fontSize = v.fontSize;
+    style.fontWeight = v.fontWeight;
+    style.lineHeight = v.lineHeight;
+    style.letterSpacing = v.letterSpacing;
+    if (v.textTransform) {
+      style.textTransform = v.textTransform;
+    }
+  }
+  if (typeof paragraphFormat === "string" && paragraphFormat !== "") {
+    style.textAlign = paragraphFormat;
+  }
+  return Object.keys(style).length > 0 ? style : void 0;
+}
+export {
+  RichTextRenderer,
+  RichTextTypographyProvider,
+  createContentRenderer,
+  useRichTextTypography
+};