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

package/dist/provenance/direct-edit-locator.js

@@ -0,0 +1,218 @@
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+export function directEditLocatorForSourceSet(sourceSet) {
+    if (sourceSet?.editable !== 'single-field' ||
+        sourceSet.sources.length !== 1) {
+        return null;
+    }
+    const source = sourceSet.primary ?? sourceSet.sources[0];
+    if (!source)
+        return null;
+    return directEditLocatorForSource(sourceSet.id, source);
+}
+export function directEditLocatorForSource(sourceSetId, source) {
+    const documentId = normalizedBoundedString(source.documentId, 256);
+    const canonicalPath = normalizedBoundedString(source.canonicalPath, 4_096);
+    const normalizedSourceSetId = normalizedBoundedString(sourceSetId, 512);
+    if (!documentId || !canonicalPath || !normalizedSourceSetId)
+        return null;
+    const pathAnchors = normalizePathAnchors(source.pathAnchors);
+    if (pathAnchors === null)
+        return null;
+    const navigationAnchors = source.navigationAnchors === undefined
+        ? undefined
+        : normalizePathAnchors(source.navigationAnchors);
+    if (navigationAnchors === null)
+        return null;
+    const variantId = normalizePreviewVariantId(source.variantId);
+    if (source.variantId !== undefined && variantId === null)
+        return null;
+    let navigationPath;
+    if (source.navigationPath !== undefined) {
+        const normalized = normalizedBoundedString(source.navigationPath, 4_096);
+        if (normalized === null)
+            return null;
+        navigationPath = normalized;
+    }
+    const textNodeIndex = normalizeTextNodeIndex(source.textNodeIndex);
+    if (source.textNodeIndex !== undefined && textNodeIndex === undefined) {
+        return null;
+    }
+    return {
+        version: 1,
+        sourceSetId: normalizedSourceSetId,
+        documentId,
+        ...(variantId !== null ? { variantId } : {}),
+        canonicalPath,
+        pathAnchors,
+        ...(navigationPath !== undefined ? { navigationPath } : {}),
+        ...(navigationAnchors !== undefined ? { navigationAnchors } : {}),
+        ...(textNodeIndex !== undefined ? { textNodeIndex } : {}),
+        sourceKind: source.sourceKind,
+        ...(source.readScope !== undefined ? { readScope: source.readScope } : {}),
+    };
+}
+export function normalizeDirectEditLocator(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const candidate = value;
+    if (candidate.version !== 1 || !isSourceKind(candidate.sourceKind))
+        return null;
+    const pathAnchors = normalizePathAnchors(candidate.pathAnchors);
+    if (pathAnchors === null)
+        return null;
+    const navigationAnchors = candidate.navigationAnchors === undefined
+        ? undefined
+        : normalizePathAnchors(candidate.navigationAnchors);
+    if (navigationAnchors === null)
+        return null;
+    const sourceSetId = normalizedBoundedString(candidate.sourceSetId, 512);
+    const documentId = normalizedBoundedString(candidate.documentId, 256);
+    const canonicalPath = normalizedBoundedString(candidate.canonicalPath, 4_096);
+    if (!sourceSetId || !documentId || !canonicalPath)
+        return null;
+    const variantId = normalizePreviewVariantId(candidate.variantId);
+    if (candidate.variantId !== undefined &&
+        (typeof candidate.variantId !== 'string' || variantId === null)) {
+        return null;
+    }
+    let navigationPath;
+    if (candidate.navigationPath !== undefined) {
+        const normalized = normalizedBoundedString(candidate.navigationPath, 4_096);
+        if (normalized === null)
+            return null;
+        navigationPath = normalized;
+    }
+    const textNodeIndex = normalizeTextNodeIndex(candidate.textNodeIndex);
+    if (candidate.textNodeIndex !== undefined && textNodeIndex === undefined) {
+        return null;
+    }
+    let readScope;
+    if (candidate.readScope !== undefined) {
+        const normalized = normalizePreviewReadScopeEcho(candidate.readScope);
+        if (normalized === null)
+            return null;
+        readScope = normalized;
+    }
+    return {
+        version: 1,
+        sourceSetId,
+        documentId,
+        ...(variantId !== null ? { variantId } : {}),
+        canonicalPath,
+        pathAnchors,
+        ...(navigationPath !== undefined ? { navigationPath } : {}),
+        ...(navigationAnchors !== undefined ? { navigationAnchors } : {}),
+        ...(textNodeIndex !== undefined ? { textNodeIndex } : {}),
+        sourceKind: candidate.sourceKind,
+        ...(readScope !== undefined ? { readScope } : {}),
+    };
+}
+export function normalizePreviewReadScopeEcho(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const scope = value;
+    if (!isNullableBoundedString(scope.requestedVariantId, 256) ||
+        !isNullableBoundedString(scope.requestedDocumentId, 256) ||
+        !(scope.requestedLocale === undefined || isNullableBoundedString(scope.requestedLocale, 128)) ||
+        !(scope.appliedLocale === undefined || isNullableBoundedString(scope.appliedLocale, 128)) ||
+        !(scope.appliesToDocument === null || typeof scope.appliesToDocument === 'boolean') ||
+        !isNullableBoundedString(scope.appliedVariantId, 256) ||
+        !isNullableBoundedString(scope.requestedReleaseId, 256) ||
+        !isReleaseScopeStatus(scope.releaseScopeStatus) ||
+        !(scope.releaseLifecycleStatus === undefined || isBoundedString(scope.releaseLifecycleStatus, 64)) ||
+        !isNullableBoundedString(scope.appliedReleaseId, 256) ||
+        !isReleaseMemberState(scope.releaseMemberState) ||
+        !isReleaseDegradedReason(scope.degradedReason)) {
+        return null;
+    }
+    return {
+        requestedVariantId: scope.requestedVariantId,
+        requestedDocumentId: scope.requestedDocumentId,
+        ...(scope.requestedLocale !== undefined
+            ? { requestedLocale: scope.requestedLocale }
+            : {}),
+        ...(scope.appliedLocale !== undefined
+            ? { appliedLocale: scope.appliedLocale }
+            : {}),
+        appliesToDocument: scope.appliesToDocument,
+        appliedVariantId: scope.appliedVariantId,
+        requestedReleaseId: scope.requestedReleaseId,
+        releaseScopeStatus: scope.releaseScopeStatus,
+        ...(scope.releaseLifecycleStatus !== undefined
+            ? { releaseLifecycleStatus: scope.releaseLifecycleStatus }
+            : {}),
+        appliedReleaseId: scope.appliedReleaseId,
+        ...(scope.releaseMemberState !== undefined
+            ? { releaseMemberState: scope.releaseMemberState }
+            : {}),
+        ...(scope.degradedReason !== undefined
+            ? { degradedReason: scope.degradedReason }
+            : {}),
+    };
+}
+function normalizePathAnchors(value) {
+    if (!Array.isArray(value) || value.length > 64)
+        return null;
+    const anchors = [];
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            return null;
+        }
+        const candidate = entry;
+        const path = normalizedBoundedString(candidate.path, 4_096, true);
+        const key = normalizedBoundedString(candidate.key, 512);
+        if (path === null || !key)
+            return null;
+        anchors.push({ path, key });
+    }
+    return anchors;
+}
+function normalizedBoundedString(value, maxLength, allowEmpty = false) {
+    if (typeof value !== 'string' || value.length > maxLength)
+        return null;
+    const normalized = value.trim();
+    return normalized.length > 0 || allowEmpty ? normalized : null;
+}
+function normalizeTextNodeIndex(value) {
+    return Number.isInteger(value) && value >= 0
+        ? value
+        : undefined;
+}
+function isSourceKind(value) {
+    return value === 'stored' ||
+        value === 'binding' ||
+        value === 'model' ||
+        value === 'computed' ||
+        value === 'richtext' ||
+        value === 'embed' ||
+        value === 'emptyFallback' ||
+        value === 'unknown';
+}
+function isNullableBoundedString(value, maxLength) {
+    return value === null || isBoundedString(value, maxLength);
+}
+function isBoundedString(value, maxLength) {
+    return typeof value === 'string' && value.length > 0 && value.length <= maxLength;
+}
+function isReleaseScopeStatus(value) {
+    return value === 'none' ||
+        value === 'active' ||
+        value === 'missing' ||
+        value === 'not-previewable' ||
+        value === 'unbound';
+}
+function isReleaseMemberState(value) {
+    return value === undefined ||
+        value === 'active' ||
+        value === 'archived' ||
+        value === 'missing' ||
+        value === 'locale-removed';
+}
+function isReleaseDegradedReason(value) {
+    return value === undefined ||
+        value === 'archived' ||
+        value === 'missing' ||
+        value === 'locale-removed';
+}

package/dist/provenance/editable-leaf.d.ts

@@ -0,0 +1,134 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { type PublicProvenanceSidecar } from './sidecar.js';
+import type { MarkerRecord, PathAnchor, PreviewProvenanceCarrierPlan, ProvenanceAnchorKind, ProvenanceFrame, ProvenanceId, ProvenanceMarkerModality, SourceSet } from './types.js';
+export { formatPreviewProvenanceCanonicalPath } from './field-leaf-walker.js';
+export type PreviewProvenancePathPart = string | number;
+export interface PreviewProvenanceEditableLeaf extends ProvenanceId {
+    readonly key: string;
+    readonly sourceSetId: string;
+    readonly outputKind: 'text' | 'element';
+    readonly modality: ProvenanceMarkerModality;
+    readonly anchorKind: ProvenanceAnchorKind;
+    readonly renderedText?: string;
+    readonly sourceSet?: PreviewProvenanceEditableLeafSourceSet;
+    readonly codedText?: boolean;
+    readonly codedTextRoot?: unknown;
+    readonly codedTextPath?: readonly PreviewProvenancePathPart[];
+    readonly codedRichTextTextNodeIndex?: number;
+    readonly anchorMultiplicity?: MarkerRecord['anchorMultiplicity'];
+    readonly presence?: MarkerRecord['presence'];
+}
+export interface PreviewProvenanceEditableLeafSourceSet {
+    readonly kind: SourceSet['kind'];
+    readonly sources: readonly ProvenanceId[];
+    readonly primary?: ProvenanceId;
+    readonly derivation?: SourceSet['derivation'];
+    readonly editable: SourceSet['editable'];
+}
+export interface CreatePreviewProvenanceEditableLeafInput {
+    readonly key: string;
+    readonly documentId: string;
+    readonly variantId?: string | null;
+    readonly readScope?: PreviewReadScopeEcho;
+    readonly rootPath?: readonly PreviewProvenancePathPart[];
+    readonly leafPath: readonly PreviewProvenancePathPart[];
+    readonly pathAnchors?: readonly PathAnchor[];
+    readonly navigationPath?: string;
+    readonly navigationAnchors?: readonly PathAnchor[];
+    readonly relativePathAnchors?: readonly PathAnchor[];
+    readonly sourceKind?: ProvenanceId['sourceKind'];
+    readonly sourceSetId: string;
+    readonly outputKind?: PreviewProvenanceEditableLeaf['outputKind'];
+    readonly modality?: ProvenanceMarkerModality;
+    readonly anchorKind?: ProvenanceAnchorKind;
+    readonly renderedText?: string;
+    readonly sourceSet?: PreviewProvenanceEditableLeafSourceSet;
+    readonly codedText?: boolean;
+    readonly codedTextRoot?: unknown;
+    readonly codedTextPath?: readonly PreviewProvenancePathPart[];
+    readonly codedRichTextTextNodeIndex?: number;
+    readonly anchorMultiplicity?: MarkerRecord['anchorMultiplicity'];
+    readonly presence?: MarkerRecord['presence'];
+}
+export interface RecordPreviewProvenanceEditableLeavesInput {
+    readonly sessionId?: string;
+    readonly readContext?: PreviewReadContext;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string | null;
+    readonly previewScope?: PreviewReadScopeEcho;
+    readonly renderId: string;
+    readonly generation: number;
+    readonly renderNonce?: string;
+    readonly emissionRevision?: number;
+    readonly enabled?: boolean;
+    readonly leaves: readonly PreviewProvenanceEditableLeaf[];
+    readonly codedTextRoot?: unknown;
+    readonly codedTextRootPrefix?: readonly PreviewProvenancePathPart[];
+    readonly codedTextRootsByDocumentId?: PreviewProvenanceCodedTextRootsByDocumentId;
+}
+export type PreviewProvenanceCodedTextRootsByDocumentId = ReadonlyMap<string, unknown> | Readonly<Record<string, unknown>>;
+export interface RecordedPreviewProvenanceEditableLeaves {
+    readonly attrsByKey: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly carrierPlansByKey: Readonly<Record<string, readonly PreviewProvenanceCarrierPlan[]>>;
+    readonly renderFrame: ProvenanceFrame;
+    readonly publicSidecar: PublicProvenanceSidecar | null;
+    readonly codedTextWrites: PreviewProvenanceCodedTextWriteSummary;
+}
+export interface PreviewProvenanceCodedTextWriteSummary {
+    readonly attempted: number;
+    readonly written: number;
+    readonly failures: readonly PreviewProvenanceCodedTextWriteFailure[];
+}
+export interface PreviewProvenanceCodedTextWriteFailure {
+    readonly key: string;
+    readonly documentId: string;
+    readonly sourceSetId: string;
+    readonly canonicalPath: string;
+    readonly operation: 'text' | 'richtext' | 'object';
+    readonly reason: 'root-missing' | 'path-unresolvable' | 'path-or-text-mismatch' | 'path-or-object-mismatch' | 'coded-text-disallowed';
+}
+export interface PreviewProvenanceEditableTextLeafCandidate {
+    readonly path: readonly PreviewProvenancePathPart[];
+    readonly leaf: PreviewProvenanceEditableLeaf;
+}
+export interface PreviewProvenanceEditableTextLeafContext {
+    readonly path: readonly PreviewProvenancePathPart[];
+    readonly fieldName: string | null;
+    readonly value?: unknown;
+    readonly sourceKind: 'stored' | 'richtext';
+    readonly outputKind: 'text' | 'element';
+    readonly textNodeIndex?: number;
+}
+export type PreviewProvenanceEditableTextPathToken = PreviewProvenancePathPart | '*';
+export interface PreviewProvenanceEditableTextPathPattern {
+    readonly path: readonly PreviewProvenanceEditableTextPathToken[];
+    readonly sourceKind?: PreviewProvenanceEditableTextLeafContext['sourceKind'];
+    readonly outputKind?: PreviewProvenanceEditableTextLeafContext['outputKind'];
+    readonly modality?: ProvenanceMarkerModality;
+    readonly anchorKind?: ProvenanceAnchorKind;
+}
+export type PreviewProvenanceEditableTextPathManifest = Readonly<Record<string, readonly PreviewProvenanceEditableTextPathPattern[]>>;
+export interface PlanPreviewProvenanceEditableTextLeavesInput {
+    readonly documentId: string;
+    readonly variantId?: string | null;
+    readonly readScope?: PreviewReadScopeEcho;
+    readonly root: unknown;
+    readonly rootPath?: readonly PreviewProvenancePathPart[];
+    readonly pathAnchors?: readonly PathAnchor[];
+    readonly keyPrefix: string;
+    readonly sourceSetPrefix: string;
+    readonly presence?: MarkerRecord['presence'];
+    readonly include?: (context: PreviewProvenanceEditableTextLeafContext) => boolean;
+    readonly match?: (context: PreviewProvenanceEditableTextLeafContext) => PreviewProvenanceEditableTextPathPattern | null;
+}
+export declare function createPreviewProvenanceEditableLeaf(input: CreatePreviewProvenanceEditableLeafInput): PreviewProvenanceEditableLeaf;
+export declare function planPreviewProvenanceEditableTextLeaves(input: PlanPreviewProvenanceEditableTextLeavesInput): readonly PreviewProvenanceEditableTextLeafCandidate[];
+export declare function createPreviewProvenanceEditableTextManifestInclude(manifest: PreviewProvenanceEditableTextPathManifest, storyType: string | null | undefined): (context: PreviewProvenanceEditableTextLeafContext) => boolean;
+export declare function createPreviewProvenanceEditableManifestMatcher(manifest: PreviewProvenanceEditableTextPathManifest, storyType: string | null | undefined): (context: PreviewProvenanceEditableTextLeafContext) => PreviewProvenanceEditableTextPathPattern | null;
+export declare function previewProvenanceEditableTextPathPatternMatches(context: PreviewProvenanceEditableTextLeafContext, pattern: PreviewProvenanceEditableTextPathPattern): boolean;
+export declare function matchingPreviewProvenanceEditablePathPattern(context: PreviewProvenanceEditableTextLeafContext, patterns: readonly PreviewProvenanceEditableTextPathPattern[]): PreviewProvenanceEditableTextPathPattern | null;
+export declare function recordPreviewProvenanceEditableLeaves(input: RecordPreviewProvenanceEditableLeavesInput): Promise<RecordedPreviewProvenanceEditableLeaves>;
+export declare function previewProvenanceSourceSetForLeaf(leaf: PreviewProvenanceEditableLeaf): SourceSet;
+export declare function prefixPreviewProvenancePathAnchors(prefixPath: readonly PreviewProvenancePathPart[], anchors: readonly PathAnchor[]): readonly PathAnchor[];