@byamoah/studio-state 0.0.0-stage → 0.1.0-beta.0

package/react.d.ts

@@ -0,0 +1,152 @@
+import type { StudioContract } from "./index.js";
+import type { ReactNode, ComponentType } from "react";
+/** Augmented by the project's generated declaration file. */
+export interface StudioState {}
+export interface StudioBlockTypes {}
+export function StudioProvider<T extends object>(props: {
+  value: T | null;
+  status?: StudioStatus;
+  contract?: StudioContract;
+  children?: ReactNode;
+}): ReactNode;
+export function useStudioContext(): Readonly<StudioState>;
+
+type CollectionPaths<T, P extends string = ""> = {
+  [K in keyof T & string]: T[K] extends readonly { id: string }[]
+    ? `${P}${K}`
+    : T[K] extends object
+      ? CollectionPaths<T[K], `${P}${K}.`>
+      : never;
+}[keyof T & string];
+type PathValue<T, P extends string> = P extends `${infer K}.${infer R}`
+  ? K extends keyof T
+    ? PathValue<T[K], R>
+    : never
+  : P extends keyof T
+    ? T[P]
+    : never;
+export function useStudioListItem<P extends CollectionPaths<StudioState>>(
+  path: P,
+  id: string,
+  options?: { reveal?: () => void },
+): PathValue<StudioState, P> extends readonly (infer Item)[]
+  ? Readonly<Item>
+  : never;
+
+export function useStudioCollection<P extends CollectionPaths<StudioState>>(
+  path: P,
+  options?: { reveal?: (id: string) => void },
+): Readonly<PathValue<StudioState, P>>;
+
+export interface RepeatItemProps {
+  id: string;
+  index: number;
+  instanceId: string;
+}
+/** Headless: place inside your row, column, grid or native list container. */
+export function Repeat<
+  P extends CollectionPaths<StudioState>,
+  Extra extends object = Record<never, never>,
+>(props: {
+  path: P;
+  template: ComponentType<RepeatItemProps & Extra>;
+  direction?: "vertical" | "horizontal" | "grid";
+  itemProps?: Extra;
+  reveal?: (id: string) => void;
+}): ReactNode;
+export function useStudioRepeat<
+  P extends CollectionPaths<StudioState>,
+  Extra extends object = Record<never, never>,
+>(props: {
+  path: P;
+  template: ComponentType<RepeatItemProps & Extra>;
+  direction?: "vertical" | "horizontal" | "grid";
+  itemProps?: Extra;
+  reveal?: (id: string) => void;
+}): ReactNode[];
+export function useStudioInstanceId(suffix?: string): string;
+
+export interface StudioStatus {
+  phase?: "hydrating" | "fetching" | "preparing" | "idle";
+  channel?: "draft" | "published" | "unknown";
+  checkedAt?: number | null;
+  contractId?: string;
+  ready: boolean;
+  refreshing: boolean;
+  hydrated: boolean;
+  source: "none" | "bundled" | "cache" | "remote" | "development" | "published";
+  revision: string | null;
+  error: string | null;
+  refresh(): Promise<void>;
+}
+export function useStudioStatus(): Readonly<StudioStatus>;
+export function StudioDeliveryProvider<D extends object>(props: {
+  client: import("./delivery.js").ContentClient<D>;
+  contract?: StudioContract;
+  children?: ReactNode;
+}): ReactNode;
+
+/** Compiler-supplied inspection metadata; absent outside an instrumented Repeat. */
+export interface StudioRepeatMetadata {
+  collectionPath?: string;
+  candidates?: StudioRepeatMetadata[];
+  id: string;
+  identity: "registered" | "ambiguous";
+  kind: "text" | "image" | "input" | "surface" | "container" | "component" | "unknown";
+  tag: string;
+  source: { file: string; line: number; column?: number; component: string };
+  fields: Array<{
+    property: string;
+    kind: "text" | "image" | "color" | "number" | "boolean" | "enum" | "array" | "unknown";
+    status: "bound" | "inspect-only";
+    provenance: "editorial" | "literal" | "expression";
+    reason: string;
+    binding?: string;
+    bindingSource?: string;
+    reference?: { path: string; pattern?: string; source: string; dynamic: boolean; unsafe?: boolean; conditions?: Array<Record<string,string>>; collection?: { path: string; key: string; contextual?: boolean } };
+  }>;
+}
+export function useStudioRepeatMetadata(): StudioRepeatMetadata | undefined;
+
+export function defineBlocks<T extends Record<string, import("react").ComponentType<never>>>(blocks: T): Readonly<T>;
+export function Layout<P extends CollectionPaths<StudioState>, Extra extends object = Record<never, never>>(props: {
+  path: P;
+  blocks: Record<string, ComponentType<RepeatItemProps & Extra>>;
+  itemProps?: Extra;
+  direction?: "vertical" | "horizontal" | "grid";
+  reveal?: (id: string) => void;
+}): ReactNode;
+
+/** Pass the actual std collection; no separately declared path is required. */
+export function useStudioListItem<T extends { id: string }>(items: readonly T[], id: string, options?: { reveal?: () => void }): Readonly<T>;
+export function useStudioCollection<T extends { id: string }>(items: readonly T[], options?: { reveal?: (id: string) => void }): readonly T[];
+export function Repeat<Extra extends object = Record<never, never>>(props: {
+  items: readonly { id: string }[];
+  template: ComponentType<RepeatItemProps & Extra>;
+  direction?: "vertical" | "horizontal" | "grid";
+  itemProps?: Extra;
+  reveal?: (id: string) => void;
+}): ReactNode;
+export function useStudioRepeat<Extra extends object = Record<never, never>>(props: {
+  items: readonly { id: string }[];
+  template: ComponentType<RepeatItemProps & Extra>;
+  direction?: "vertical" | "horizontal" | "grid";
+  itemProps?: Extra;
+  reveal?: (id: string) => void;
+}): ReactNode[];
+export function Layout<Extra extends object = Record<never, never>>(props: {
+  items: readonly { id: string; type: string }[];
+  blocks: Record<string, ComponentType<RepeatItemProps & Extra>>;
+  itemProps?: Extra;
+  direction?: "vertical" | "horizontal" | "grid";
+  reveal?: (id: string) => void;
+}): ReactNode;
+
+export function useStudioBlock<K extends keyof StudioBlockTypes>(type: K): Readonly<StudioBlockTypes[K]>;
+export function useStudioBoundMetadata<T extends StudioRepeatMetadata | undefined>(metadata: T): T;
+export function Slot<Extra extends object = Record<never, never>>(props: {
+  name: string;
+  blocks: Record<string, ComponentType<RepeatItemProps & Extra>>;
+  itemProps?: Extra;
+  direction?: "vertical" | "horizontal" | "grid";
+}): ReactNode;

package/react.js

@@ -0,0 +1,258 @@
+import {
+  getStudioValue,
+  studioItemSegment,
+  validateStudioState,
+  subscribeStudioReveal,
+  matchesStudioConditions,
+} from "./index.js";
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useRef,
+  useMemo,
+  useId,
+  useSyncExternalStore,
+} from "react";
+const Context = createContext(undefined);
+const StatusContext = createContext(undefined);
+const noopRefresh = async () => {};
+export function StudioProvider({ value, children, contract, status }) {
+  if (contract && value != null) {
+    const errors = validateStudioState(value, contract);
+    if (errors.length) throw new Error(errors.slice(0, 3).join(" "));
+  }
+  const current = {
+    ready: value != null,
+    refreshing: false,
+    hydrated: true,
+    source: "bundled",
+    revision: null,
+    error: null,
+    refresh: noopRefresh,
+    contractId: contract?.contractId,
+    ...status,
+  };
+  current.ready = current.ready && value != null;
+  return createElement(
+    StatusContext.Provider,
+    { value: current },
+    createElement(Context.Provider, { value }, children),
+  );
+}
+export function useStudioContext() {
+  const value = useContext(Context);
+  if (value == null)
+    throw new Error("useStudioContext must be used inside StudioProvider.");
+  return value;
+}
+
+export function useStudioStatus() {
+  const status = useContext(StatusContext);
+  if (!status)
+    throw new Error("useStudioStatus must be used inside StudioProvider.");
+  return status;
+}
+export function StudioDeliveryProvider({ client, contract, children }) {
+  const state = useSyncExternalStore(
+    client.subscribe,
+    client.getSnapshot,
+    client.getSnapshot,
+  );
+  useEffect(() => {
+    void client.start();
+    return () => client.stop();
+  }, [client]);
+  return createElement(
+    StudioProvider,
+    {
+      value: state.document,
+      contract,
+      status: { ...state, refresh: client.refresh },
+    },
+    children,
+  );
+}
+
+/** Explicit collection binding. Call in an item component, never inside a map callback. */
+export function useStudioListItem(path, id, options) {
+  const instance = useContext(InstanceContext);
+  const revealPath = Array.isArray(path) ? (instance?.items === path ? instance.path : undefined) : path;
+  const state = useStudioContext();
+  const callback = useRef(options?.reveal);
+  callback.current = options?.reveal;
+  useEffect(() => {
+    const reveal = (event) => {
+      if (event.detail?.path === revealPath && event.detail?.id === id)
+        callback.current?.();
+    };
+    const unsubscribe = subscribeStudioReveal((detail) => reveal({ detail }));
+    const browser =
+      typeof window !== "undefined" &&
+      typeof window.addEventListener === "function";
+    if (browser) window.addEventListener("studio:reveal-item", reveal);
+    return () => {
+      unsubscribe();
+      if (browser) window.removeEventListener("studio:reveal-item", reveal);
+    };
+  }, [revealPath, id]);
+  const items = Array.isArray(path) ? path : getStudioValue(state, path);
+  studioItemSegment(id);
+  const matches = Array.isArray(items)
+    ? items.filter((item) => item?.id === id)
+    : [];
+  if (matches.length !== 1)
+    throw new Error(`Studio item ${path}/${id} must exist exactly once.`);
+  return matches[0];
+}
+
+/** Parent-level reveal support also works before a virtualized item is mounted. */
+export function useStudioCollection(path, options) {
+  const state = useStudioContext();
+  const callback = useRef(options?.reveal);
+  callback.current = options?.reveal;
+  useEffect(() => {
+    const reveal = (event) => {
+      if (event.detail?.path === (options?.path ?? path) && typeof event.detail?.id === "string")
+        callback.current?.(event.detail.id);
+    };
+    const unsubscribe = subscribeStudioReveal((detail) => reveal({ detail }));
+    const browser =
+      typeof window !== "undefined" &&
+      typeof window.addEventListener === "function";
+    if (browser) window.addEventListener("studio:reveal-item", reveal);
+    return () => {
+      unsubscribe();
+      if (browser) window.removeEventListener("studio:reveal-item", reveal);
+    };
+  }, [path, options?.path]);
+  const items = Array.isArray(path) ? path : getStudioValue(state, path);
+  if (!Array.isArray(items))
+    throw new Error(`Studio collection ${path} must be an array.`);
+  return items;
+}
+
+const InstanceContext = createContext(undefined);
+/** Headless region: the parent owns native/web layout; direction declares insertion semantics. */
+export function useStudioRepeat({
+  path: explicitPath,
+  items: providedItems,
+  __studioPath,
+  template,
+  direction = "vertical",
+  itemProps,
+  reveal,
+  __studioRepeat,
+}) {
+  const parent = useContext(InstanceContext);
+  const document = useContext(Context);
+  const path = explicitPath ?? __studioPath ?? __studioRepeat?.collectionPath;
+  const items = useStudioCollection(providedItems ?? path, { reveal, path });
+  const regionId = useId();
+  const metadataCache = useRef({ source: __studioRepeat, items: new Map() });
+  if (metadataCache.current.source !== __studioRepeat)
+    metadataCache.current = { source: __studioRepeat, items: new Map() };
+  const live = new Set(items.map(item => studioItemSegment(item.id)));
+  for (const key of metadataCache.current.items.keys()) if (!live.has(key)) metadataCache.current.items.delete(key);
+  if (!["vertical", "horizontal", "grid"].includes(direction))
+    throw new Error("Invalid Studio Repeat direction.");
+  const seen = new Set();
+  return items.map((item, index) => {
+    const segment = studioItemSegment(item.id);
+    if (seen.has(item.id))
+      throw new Error(`Duplicate Studio item id in ${path}.`);
+    seen.add(item.id);
+    const instanceId = `studio:${path}:${segment}:${regionId}`;
+    const signature = JSON.stringify([...(parent?.chain ?? []), [path, item.id, item.type]]);
+    const scope = { path, id: item.id, item, items, signature, chain: [...(parent?.chain ?? []), [path, item.id, item.type]] };
+    const cached = metadataCache.current.items.get(segment);
+    let metadata = cached?.signature === signature ? cached.metadata : undefined;
+    if (__studioRepeat && !metadata) {
+      metadata = bindMetadata(__studioRepeat, scope, document);
+      metadataCache.current.items.set(segment, { signature, metadata });
+    }
+    return createElement(
+      InstanceContext.Provider,
+      { key: segment, value: { ...scope, instanceId, metadata } },
+      createElement(template, { ...itemProps, id: item.id, index, instanceId }),
+    );
+  });
+}
+export function useStudioInstanceId(suffix = "root") {
+  const instance = useContext(InstanceContext);
+  if (!instance)
+    throw new Error("useStudioInstanceId requires a Studio Repeat item.");
+  return `${instance.instanceId}:${studioItemSegment(suffix)}`;
+}
+
+/** Component form for containers that do not inspect their direct React children. */
+export function Repeat(props) {
+  return useStudioRepeat(props);
+}
+
+/** Host adapters consume this to register the current Repeat item's bounds. */
+export function useStudioRepeatMetadata() {
+  return useContext(InstanceContext)?.metadata;
+}
+
+/** Registration stays in application code; content can choose only these types. */
+export function defineBlocks(blocks) {
+  if (!blocks || typeof blocks !== "object" || !Object.keys(blocks).length)
+    throw new Error("Register at least one layout block.");
+  return Object.freeze({ ...blocks });
+}
+function LayoutItem({ __layout, ...props }) {
+  const item = useStudioListItem(__layout.items ?? __layout.path, props.id);
+  const Template = Object.hasOwn(__layout.blocks, item.type) && __layout.blocks[item.type];
+  if (!Template) throw new Error(`Unsupported Studio block type: ${item.type}`);
+  return createElement(Template, props);
+}
+/** Ordered heterogeneous blocks with Repeat's identity and inspection semantics. */
+export function Layout({ blocks, itemProps, ...props }) {
+  return useStudioRepeat({ ...props, template: LayoutItem,
+    itemProps: { ...itemProps, __layout: { path: props.path, items: props.items, blocks } },
+  });
+}
+
+/** A type-scoped item reader; the compiler supplies its collection and schema. */
+export function useStudioBlock(type) {
+  const scope = useContext(InstanceContext);
+  if (!scope || scope.item?.type !== type) throw new Error(`Studio block ${type} requires its matching Layout item.`);
+  return scope.item;
+}
+function bindMetadata(metadata, scope, document) {
+  if (!metadata || !scope?.path) return metadata;
+  if (metadata.candidates) {
+    for (const candidate of metadata.candidates) {
+      const bound = bindMetadata(candidate, scope, document);
+      if (bound.fields.some(field => field.reference?.collection && field.status === "bound")) return bound;
+    }
+  }
+  return { ...metadata, fields: metadata.fields.flatMap(field => {
+    const pattern = scope.path.split(".").map(part => part.startsWith("@") ? "*" : part).join(".");
+    const collection = field.reference?.collection ?? (field.reference?.path.startsWith(pattern + ".*.") ? {path:pattern} : undefined);
+    if (!collection) return [field];
+    const schemaPath = field.reference.pattern ?? field.reference.path;
+    const prefix = schemaPath.startsWith(collection.path + ".") ? collection.path : scope.path;
+    const suffix = schemaPath.slice(prefix.length + 1).split(".").slice(1).join(".");
+    const binding = `${scope.path}.${studioItemSegment(scope.id)}.${suffix}`;
+    // Only resources belonging to this rendered instance can bind here.
+    if (pattern !== collection.path || !matchesStudioConditions(document, binding, field.reference.conditions)) return [];
+    return [{ ...field, binding, reference: { ...field.reference, path: binding, pattern: schemaPath } }];
+  }) };
+}
+/** Shared host adapters use this for nested/contextual compiler metadata. */
+export function useStudioBoundMetadata(metadata) {
+  const scope = useContext(InstanceContext);
+  const document = useContext(Context);
+  return useMemo(() => bindMetadata(metadata, scope, document), [metadata, scope?.signature]);
+}
+/** A named, typed region owned by the current layout item. */
+export function Slot({ name, blocks, itemProps, ...props }) {
+  const owner = useContext(InstanceContext);
+  if (!owner || !/^[A-Za-z_$][\w$]*$/.test(name) || ["__proto__", "constructor", "prototype"].includes(name))
+    throw new Error("Studio Slot requires a Layout item and a safe name.");
+  const path = `${owner.path ?? "items"}.${studioItemSegment(owner.id)}.slots.${name}`;
+  return createElement(Layout, { ...props, path, items: owner.item.slots?.[name] ?? [], blocks, itemProps });
+}