@storystick/react 0.0.0-stage → 0.2.0-rc.1

package/dist/slice-zone.d.ts

@@ -0,0 +1,82 @@
+import { type ContentSource } from '@storystick/client/internal';
+/** Dispatch autonomous SDK slices; context is opaque application data. */
+import React from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import type { SectionAnchorData } from '@storystick/types';
+import { type SliceContractRegistry, type SliceFallback, type SliceRenderFailureHandler } from './slice-render-failure.js';
+export type { SliceContract, SliceContractRegistry, SliceFallback, SliceRenderFailure, SliceRenderFailureHandler, } from './slice-render-failure.js';
+import { type SliceAnchor } from '@storystick/preview/provenance/slice-model';
+import { type SliceProvenance } from './preview-provenance.js';
+/**
+ * Data shape for a single slice.
+ * Every slice must have _type (discriminant) and _key (React key).
+ */
+export interface SliceData {
+    _type: string;
+    _key: string;
+    _variation?: string;
+    /** Authored deep-link target rendered by `Slice.*` as a native `id`. */
+    _anchor?: SectionAnchorData;
+}
+/**
+ * Props received by every slice component.
+ * Uniform contract — no exceptions.
+ */
+export interface SliceComponentProps<T extends SliceData = SliceData, TContext = unknown, TZones extends Record<string, ReactNode> = Record<string, ReactNode>> {
+    /** The slice data (all fields + _type, _key, _variation) */
+    slice: T;
+    /** Optional context passed through from SliceZone (e.g., document data) */
+    context?: TContext;
+    /**
+     * Renderable zones for zone container slices. Populated by SliceZone
+     * from the slice’s local render metadata — absent for non-zone-container slices.
+     * Applications can specialize `TZones` for a container registry; this base
+     * type stays permissive so the runtime contract remains unopinionated.
+     * Prefer rendering with <ZoneSlot zone={zones.main} />.
+     */
+    zones?: TZones;
+    /** Field binding attributes for this slice, grouped as plain serializable data. */
+    bindings?: SliceProvenance;
+}
+/**
+ * Shape of the `_zoneMappings` metadata attached to document responses by
+ * the backend (ADR-051 §9). Consumed here to resolve zone content before
+ * dispatching to slice components.
+ */
+export type ZoneMappings = Record<string, Record<string, string>>;
+export type SliceComponentRegistry<TSliceMap extends object = Record<string, SliceData>, TContext = unknown, TZones extends Record<string, ReactNode> = Record<string, ReactNode>> = {
+    readonly [TType in keyof TSliceMap]: React.ComponentType<SliceComponentProps<Extract<TSliceMap[TType], SliceData>, TContext, TZones>>;
+};
+type SliceFromMap<TSliceMap extends object> = Extract<TSliceMap[keyof TSliceMap], SliceData>;
+export interface SliceZoneProps<TSliceMap extends object = Record<string, SliceData>, TContext = unknown, TZones extends Record<string, ReactNode> = Record<string, ReactNode>> {
+    /** Array of slice data objects from a sliceZone field */
+    slices: readonly SliceFromMap<TSliceMap>[] | undefined | null;
+    /** Registry mapping slice _type to React components */
+    components: SliceComponentRegistry<TSliceMap, TContext, TZones>;
+    /** Optional context passed to every slice component */
+    context?: TContext;
+    /** Customer-owned output for malformed or unregistered slice entries. */
+    fallback?: SliceFallback;
+    /** Runtime variation IDs generated from the same resolved Story schema. */
+    contracts?: SliceContractRegistry;
+    /** Local observability hook for every slice render failure. */
+    onRenderFailure?: SliceRenderFailureHandler;
+    /** Explicit owner for raw content; ordinary SDK values already carry it. */
+    source?: ContentSource;
+    /** Optional owning document field; usually inferred by the public SDK seam */
+    sliceField?: string;
+    /** Internal preview ancestry for recursive zone-container SliceZones. */
+    parentAnchors?: ReadonlyArray<SliceAnchor>;
+    /** Internal numeric visual path of the parent slice. */
+    parentPath?: string;
+}
+export type ZoneSlotKind = 'richtext' | 'sliceZone' | 'empty';
+export interface ZoneSlotDescriptor {
+    readonly kind: ZoneSlotKind;
+    readonly fieldPath: string;
+}
+export interface ZoneSlotProps {
+    readonly zone?: ReactNode;
+}
+export declare function ZoneSlot({ zone, }: ZoneSlotProps): ReactElement | null;
+export declare function SliceZone<TSliceMap extends object = Record<string, SliceData>, TContext = unknown, TZones extends Record<string, ReactNode> = Record<string, ReactNode>>({ slices: inputSlices, components, context, source, fallback, contracts, onRenderFailure, sliceField, parentAnchors, parentPath, }: SliceZoneProps<TSliceMap, TContext, TZones>): React.JSX.Element | null;

package/dist/slice-zone.js

@@ -0,0 +1,273 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { readContentOrigin, prepareContentSource } from '@storystick/client/internal';
+/** Dispatch autonomous SDK slices; context is opaque application data. */
+import React from 'react';
+import { RichText } from './rich-text.js';
+import { hydrateSliceWithDiagnostics } from './hydrate-slice.js';
+import { projectHydratedSlice, renderSliceFallback, reportSliceFailure, validateSliceVariation, } from './slice-render-failure.js';
+import { stampPreviewScope } from './preview-scope.js';
+import { extractSliceFields, getPreviewDocumentId, isPublishedSnapshotContext, makeSliceRenderId, serializeSliceModel, } from '@storystick/preview/provenance/slice-model';
+import { buildSliceProvenance, readPreviewProvenanceRouteFrame, readPreviewProvenanceRouteRender, } from './preview-provenance.js';
+import { isPreviewSliceDirectInvocationCandidate, readPreviewSliceScopeAdapter, } from './preview-slice-scope.js';
+export function ZoneSlot({ zone, }) {
+    if (zone === undefined || zone === null || zone === false)
+        return null;
+    return _jsx(_Fragment, { children: zone });
+}
+function ZoneSlotCarrier({ children, }) {
+    return children === undefined || children === null ? null : _jsx(_Fragment, { children: children });
+}
+export function SliceZone({ slices: inputSlices, components, context, source, fallback, contracts, onRenderFailure, sliceField, parentAnchors = [], parentPath, }) {
+    const slices = prepareContentSource(inputSlices, source);
+    if (!slices)
+        return null;
+    const runtimeComponents = components;
+    // Explicit raw sources use the same resolver without borrowing app context.
+    const zoneMappings = getZoneMappings(source?.document);
+    const documentFields = zoneMappings ? getDocumentFields(source?.document) : null;
+    const routeFrame = readPreviewProvenanceRouteRender(source?.document)?.frame ??
+        readPreviewProvenanceRouteFrame(source?.document) ??
+        null;
+    const scopeAdapter = readPreviewSliceScopeAdapter();
+    const renderIds = new Map();
+    const rendered = slices.map((rawSlice, index) => {
+        if (!isRecord(rawSlice)) {
+            const failure = {
+                reason: 'invalid-slice',
+                value: rawSlice,
+                index,
+            };
+            reportSliceFailure(failure, onRenderFailure);
+            return renderSliceFallback(fallback, failure, `invalid-slice-${index}`, process.env.NODE_ENV !== 'production');
+        }
+        if (typeof rawSlice._type !== 'string' || rawSlice._type.length === 0) {
+            const failure = {
+                reason: 'missing-type',
+                slice: rawSlice,
+                index,
+            };
+            reportSliceFailure(failure, onRenderFailure);
+            return renderSliceFallback(fallback, failure, `missing-type-${index}`, process.env.NODE_ENV !== 'production');
+        }
+        const slice = rawSlice;
+        const content = readContentOrigin(slice);
+        const scopeDocId = content?.documentId ?? getPreviewDocumentId(source?.document);
+        const previewing = content ? content.preview === true : scopeDocId !== null && !isPublishedSnapshotContext(source?.document);
+        const scopeKey = content?.path.replace(/\[\d+\]$/, '');
+        const renderKey = JSON.stringify([scopeDocId, scopeKey]);
+        let renderId = '';
+        if (previewing && scopeDocId) {
+            renderId = renderIds.get(renderKey) ?? makeSliceRenderId({ scopeDocId, slices, scopeKey });
+            renderIds.set(renderKey, renderId);
+        }
+        const sourceIndex = content?.index ?? index;
+        const effectiveParentAnchors = content?.parentAnchors ?? parentAnchors;
+        const variationFailure = validateSliceVariation(slice, contracts, index);
+        if (variationFailure) {
+            reportSliceFailure(variationFailure, onRenderFailure);
+            return renderSliceFallback(fallback, variationFailure, slice._key || `invalid-variation-${index}`, previewing || process.env.NODE_ENV !== 'production');
+        }
+        const Component = runtimeComponents[slice._type];
+        if (!Component) {
+            const failure = {
+                reason: 'unregistered-type',
+                slice,
+                index,
+                registeredTypes: Object.keys(runtimeComponents).sort(),
+            };
+            reportSliceFailure(failure, onRenderFailure);
+            return renderSliceFallback(fallback, failure, slice._key || `unregistered-slice-${index}`, previewing || process.env.NODE_ENV !== 'production');
+        }
+        const zoneMapping = zoneMappings?.[slice._type];
+        const effectiveSliceField = content?.zoneField ?? sliceField ?? source?.path ?? 'sections';
+        const slicePath = content?.path ?? (parentPath
+            ? `${parentPath}.${effectiveSliceField}[${index}]`
+            : `${effectiveSliceField}[${index}]`);
+        const currentAnchorPrefix = parentPath
+            ? `${parentPath}.${effectiveSliceField}`
+            : effectiveSliceField;
+        const currentAnchor = typeof slice._key === 'string' && slice._key.length > 0
+            ? { pathPrefix: currentAnchorPrefix, key: slice._key }
+            : null;
+        const zones = content?.zones
+            ? Object.fromEntries(Object.entries(content.zones).map(([name, zone]) => [name,
+                renderZoneValue(zone.path, zone.value, runtimeComponents, context, fallback, contracts, onRenderFailure, [], '')]))
+            : zoneMapping
+                ? resolveZones(zoneMapping, documentFields, runtimeComponents, context, fallback, contracts, onRenderFailure, currentAnchor === null ? parentAnchors : [...parentAnchors, currentAnchor], slicePath, source?.document)
+                : undefined;
+        // Field bindings (ADR-052): fill bound fields that have no stored
+        // value on the instance. Reference-stable when nothing to hydrate —
+        // memoization and React.memo stay sharp. Safe when the explicit source has
+        // no `_fieldBindings` sidecar (e.g., older backends).
+        const hydration = content ? { slice, failures: content.failures ?? [] } : hydrateSliceWithDiagnostics(slice, source?.document, {
+            sourceRefPath: `${slicePath}._model`,
+        });
+        if (hydration.failures.length > 0) {
+            const failures = hydration.failures.map((failure) => failure.reason === 'missing-model'
+                ? { ...failure, slice, index }
+                : { reason: 'invalid-bindings', slice, index });
+            failures.forEach((failure) => reportSliceFailure(failure, onRenderFailure));
+            return renderSliceFallback(fallback, failures[0], slice._key || `slice-hydration-${index}`, previewing || process.env.NODE_ENV !== 'production');
+        }
+        const hydrated = projectHydratedSlice(hydration.slice, contracts);
+        const hydratedFields = extractSliceFields(hydrated);
+        // ADR-129 D4/D9 — NO injected node. In preview, stamp the slice
+        // with its serialized per-slice model; `<Slice.section slice>` reads
+        // the stamp and emits `data-ss-slice` (the `_key`) + `data-ss-model`
+        // (this model) — both ATTRIBUTES on the slice's own root element.
+        // The model is built from the HYDRATED slice (post-binding values)
+        // so inference + the coverage model see the same field values the
+        // component renders. Only when previewing + the slice has a usable
+        // `_key`. React keying lives on the component element itself.
+        let propSlice = hydrated;
+        if (previewing &&
+            scopeDocId !== null &&
+            typeof slice._key === 'string' &&
+            slice._key.length > 0) {
+            const modelJson = serializeSliceModel({
+                v: 129,
+                renderId,
+                doc: scopeDocId,
+                i: sourceIndex,
+                type: slice._type,
+                fields: hydratedFields,
+                zoneField: effectiveSliceField,
+                zoneFieldSource: content || sliceField !== undefined ? 'explicit' : 'default',
+                parentAnchors: effectiveParentAnchors,
+                ...(content ? { source: { path: content.path, anchors: [...content.parentAnchors, { pathPrefix: content.path.replace(/\[\d+\]$/, ''), key: slice._key }] } } : {}),
+            });
+            // A model that fails to serialize ⇒ the slice is left unstamped:
+            // no `data-ss-slice`/`data-ss-model`, no overlay (honest absence),
+            // every sibling slice unaffected.
+            if (modelJson !== null) {
+                propSlice = stampPreviewScope(hydrated, modelJson);
+            }
+        }
+        const bindings = buildSliceProvenance(content ?? source?.document, slice);
+        const componentProps = {
+            slice: propSlice,
+            context,
+            zones,
+            bindings,
+        };
+        const key = slice._key || `slice-${index}`;
+        if (scopeAdapter !== undefined &&
+            scopeDocId !== null &&
+            isPreviewSliceDirectInvocationCandidate(Component)) {
+            const scoped = scopeAdapter({
+                component: Component,
+                props: componentProps,
+                scope: {
+                    routeFrame: routeFrame?.frameId === 'route' ? routeFrame : null,
+                    documentId: scopeDocId,
+                    sliceField: effectiveSliceField,
+                    slicePath,
+                    sliceKey: slice._key,
+                    sliceType: slice._type,
+                    sliceIndex: index,
+                },
+            });
+            return React.createElement(React.Fragment, { key }, scoped);
+        }
+        return React.createElement(Component, { key, ...componentProps });
+    });
+    // ADR-129 D9 — no `<script>` island node: every slice carries its own
+    // model on its `data-ss-model` attribute. The render is byte-identical
+    // to a SliceZone with no preview seam outside preview, and injects
+    // zero nodes inside it.
+    return _jsx(_Fragment, { children: rendered });
+}
+// ─────────────────────────────────────────────
+// Zone container helpers
+// ─────────────────────────────────────────────
+/**
+ * Read zone mappings from an explicit raw document source. Returns
+ * `null` when that source carries no mappings, which lets
+ * SliceZone fall back to the original (zoneless) dispatch.
+ */
+function getZoneMappings(source) {
+    if (!source || typeof source !== 'object')
+        return null;
+    const c = source;
+    const m = c._zoneMappings;
+    if (!m || typeof m !== 'object')
+        return null;
+    return m;
+}
+/**
+ * Document responses wrap content under `fields`. Zone refs resolve against
+ * that object. Returning `null` when the shape isn't recognised keeps the
+ * caller's null-checks narrow.
+ */
+function getDocumentFields(source) {
+    if (!source || typeof source !== 'object')
+        return null;
+    const c = source;
+    if (c.fields && typeof c.fields === 'object') {
+        return c.fields;
+    }
+    return null;
+}
+/**
+ * Build the `zones` prop for a zone container slice by reading each mapped
+ * field from the document and rendering it with the appropriate component.
+ *
+ * Field-type detection is shape-based: a string is treated as richtext (a
+ * ProseMirror JSON payload), an array as a sliceZone. This mirrors the
+ * resolver's push-time validation (ADR-051 check 9 — zone refs must point
+ * to richtext or sliceZone fields), so we never get here with a field of a
+ * different type. `null`/`undefined` zones become explicit empty zones.
+ */
+function resolveZones(mapping, fields, components, context, fallback, contracts, onRenderFailure, parentAnchors, parentPath, sourceDocument) {
+    const zones = {};
+    for (const [zoneName, fieldPath] of Object.entries(mapping)) {
+        const value = fields?.[fieldPath];
+        zones[zoneName] = renderZoneValue(fieldPath, value, components, context, fallback, contracts, onRenderFailure, parentAnchors, parentPath, sourceDocument);
+    }
+    return zones;
+}
+function renderZoneValue(fieldPath, value, components, context, fallback, contracts, onRenderFailure, parentAnchors, parentPath, sourceDocument) {
+    if (value === null || value === undefined) {
+        return createZoneCarrier({ kind: 'empty', fieldPath }, null);
+    }
+    if (typeof value === 'string' || readContentOrigin(value)?.kind === 'richtext') {
+        // Richtext zone — the stored value is a ProseMirror JSON string. <RichText>
+        // parses and walks it using the same components registry so embeds inside
+        // the zone keep dispatching to the consumer's slice components.
+        return createZoneCarrier({ kind: 'richtext', fieldPath }, React.createElement(RichText, {
+            content: value,
+            components: { embeds: components },
+            context,
+            ...(sourceDocument ? { source: { document: sourceDocument, path: fieldPath } } : {}),
+            sliceFallback: fallback,
+            contracts,
+            onRenderFailure,
+            sliceField: fieldPath,
+            parentAnchors,
+            parentPath,
+        }));
+    }
+    if (Array.isArray(value)) {
+        // SliceZone zone — recurse with the same registry and context so nested
+        // zone containers (should a future version allow them) would also resolve.
+        return createZoneCarrier({ kind: 'sliceZone', fieldPath }, React.createElement((SliceZone), {
+            slices: value,
+            components,
+            context,
+            ...(sourceDocument ? { source: { document: sourceDocument, path: fieldPath } } : {}),
+            fallback,
+            contracts,
+            onRenderFailure,
+            sliceField: fieldPath,
+            parentAnchors,
+            parentPath,
+        }));
+    }
+    return createZoneCarrier({ kind: 'empty', fieldPath }, null);
+}
+function createZoneCarrier(descriptor, children) {
+    return React.createElement(ZoneSlotCarrier, { descriptor }, children);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/slice.d.ts

@@ -0,0 +1,16 @@
+import { type ComponentType } from 'react';
+import type { SliceData } from './slice-zone.js';
+/** The slice received by a SliceZone or rich-text embed component. */
+export interface SliceRootProps {
+    slice: SliceData;
+}
+/** Native elements that declare a slice's visual root, without a wrapper. */
+export type SliceElements = {
+    readonly [Tag in keyof React.JSX.IntrinsicElements]: ComponentType<React.JSX.IntrinsicElements[Tag] & SliceRootProps>;
+};
+/**
+ * Render a slice's own native root: `<Slice.section slice={slice}>`.
+ * SliceZone supplies the serializable Preview identity. Without it, this
+ * renders ordinary HTML. Fields use automatic provenance or `bindings`.
+ */
+export declare const Slice: SliceElements;

package/dist/slice.js

@@ -0,0 +1,46 @@
+import { createElement } from 'react';
+import { isSectionAnchorSlug } from '@storystick/types';
+import { getPreviewModel } from './preview-scope.js';
+function createSliceRoot(tag) {
+    function SliceRoot({ slice, children, ...props }) {
+        const anchor = slice
+            ?._anchor;
+        if (props.id === undefined &&
+            typeof anchor?.slug === 'string' &&
+            isSectionAnchorSlug(anchor.slug)) {
+            props.id = anchor.slug;
+        }
+        const model = getPreviewModel(slice);
+        const key = slice?._key;
+        if (model !== undefined && typeof key === 'string' && key.length > 0) {
+            props['data-ss-slice'] = key;
+            props['data-ss-model'] = model;
+            props.suppressHydrationWarning ??= true;
+        }
+        return createElement(tag, props, children);
+    }
+    SliceRoot.displayName = `Slice.${tag}`;
+    return SliceRoot;
+}
+const inspectionKeys = new Set(['then', 'toJSON', 'constructor', 'toString', 'valueOf', 'inspect']);
+const elements = new Map();
+/**
+ * Render a slice's own native root: `<Slice.section slice={slice}>`.
+ * SliceZone supplies the serializable Preview identity. Without it, this
+ * renders ordinary HTML. Fields use automatic provenance or `bindings`.
+ */
+export const Slice = new Proxy(Object.create(null), {
+    get(_target, tag) {
+        // Ignore Promise assimilation and React/JS inspection probes. SVG tags
+        // can contain capitals (e.g. foreignObject); native tags start lowercase.
+        if (typeof tag !== 'string' || inspectionKeys.has(tag) || !/^[a-z][a-zA-Z0-9]*$/.test(tag)) {
+            return undefined;
+        }
+        let element = elements.get(tag);
+        if (!element) {
+            element = createSliceRoot(tag);
+            elements.set(tag, element);
+        }
+        return element;
+    },
+});

package/dist/storystick-mark.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentPropsWithoutRef } from 'react';
+/** Canonical brand geometry, shared by Studio and the lightweight preview host. */
+export declare function StorystickMark(props: ComponentPropsWithoutRef<'svg'>): import("react").JSX.Element;

package/dist/storystick-mark.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { STORYSTICK_MARK_RECTS, STORYSTICK_MARK_VIEW_BOX } from '@storystick/preview/page-presentation';
+/** Canonical brand geometry, shared by Studio and the lightweight preview host. */
+export function StorystickMark(props) {
+    return (_jsx("svg", { ...props, "data-slot": "storystick-mark", viewBox: STORYSTICK_MARK_VIEW_BOX, fill: "currentColor", focusable: "false", "aria-hidden": "true", children: STORYSTICK_MARK_RECTS.map(rect => _jsx("rect", { ...rect }, rect.x)) }));
+}

package/dist/use-generated-query.d.ts

@@ -0,0 +1,37 @@
+import { StorystickError } from '@storystick/client';
+import type { CompiledQueryV2, QueryPageInfo, QueryResult } from '@storystick/types/query-contract';
+export interface UseQueryOptions {
+    readonly enabled?: boolean;
+}
+interface ExecutableQuery<TData, TPageInfo extends QueryPageInfo | null> {
+    compile(): {
+        readonly canonical: string;
+        readonly query: CompiledQueryV2;
+    };
+    execute(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<QueryResult<TData, TPageInfo>>;
+}
+interface UseQueryCommon<TData, TPageInfo extends QueryPageInfo | null> {
+    readonly data: TData | undefined;
+    readonly pageInfo: TPageInfo | undefined;
+    readonly error: StorystickError | null;
+    readonly isFetching: boolean;
+    refetch(): Promise<TData>;
+}
+export type UseQueryResult<TData, TPageInfo extends QueryPageInfo | null> = (UseQueryCommon<TData, TPageInfo> & {
+    readonly status: 'pending';
+    readonly data: undefined;
+    readonly pageInfo: undefined;
+    readonly error: null;
+}) | (UseQueryCommon<TData, TPageInfo> & {
+    readonly status: 'success';
+    readonly data: TData;
+    readonly pageInfo: TPageInfo;
+    readonly error: null;
+}) | (UseQueryCommon<TData, TPageInfo> & {
+    readonly status: 'error';
+    readonly error: StorystickError;
+});
+export declare function useQuery<TData, TPageInfo extends QueryPageInfo | null>(executableQuery: ExecutableQuery<TData, TPageInfo>, options?: UseQueryOptions): UseQueryResult<TData, TPageInfo>;
+export {};