@sanity/workflow-studio-plugin 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,14 +1,17 @@
 import type { DefaultDocumentNodeResolver } from "sanity/structure";
 import { EffectHandler } from "@sanity/workflow-engine";
-import { EffectsContext } from "@sanity/workflow-engine";
 import { GlobalDocumentReference } from "@sanity/workflow-engine";
 import { InitialFieldValue } from "@sanity/workflow-engine";
 import { JSX } from "react";
 import { Plugin as Plugin_2 } from "sanity";
 import { PreviewProps } from "sanity";
+import { ResourceClientResolver } from "@sanity/workflow-engine";
+import { StartContext } from "@sanity/workflow-engine";
 import type { StructureBuilder } from "sanity/structure";
 import type { ViewBuilder } from "sanity/structure";
 
+/** The first mapping row for a document type — the tie-break wherever a
+ *  surface binds to exactly one row. */
 export declare function mappingForDocType(
   mappings: readonly WorkflowMapping[],
   docType: string,
@@ -43,9 +46,11 @@ export declare interface WorkflowMapping {
   readonly docType: string;
   /**
    * The document type must have a workflow: the editor form is gated until
-   * an instance references the document. Advisory, UI-only enforcement —
-   * any raw API client can still write; the Content Lake is the only
-   * enforcement point.
+   * an instance references the document. Doctype-level: the flag on ANY
+   * mapping row for a docType gates the form, and starting any mapped
+   * workflow satisfies the gate. Advisory, UI-only enforcement — any raw
+   * API client can still write; the Content Lake is the only enforcement
+   * point.
    */
   readonly mandatory?: boolean;
   /** The definition `name` the engine deployed under. */
@@ -61,10 +66,10 @@ export declare interface WorkflowMapping {
   readonly initialStateBuilder?: (
     subjectGdr: GlobalDocumentReference,
   ) => InitialFieldValue[];
-  /** Optional effectsContext seed. */
-  readonly effectsContextBuilder?: (
+  /** Optional `$context` seed passed to `startInstance` as its `context`. */
+  readonly contextBuilder?: (
     subjectGdr: GlobalDocumentReference,
-  ) => EffectsContext;
+  ) => StartContext;
   /**
    * When set, the Start action reads Studio's `usePerspective()` to pull the
    * active release. If a release is selected, the named `release.ref` field
@@ -100,6 +105,15 @@ export declare interface WorkflowPluginConfig {
    * runtime to claim.
    */
   readonly effectHandlers?: Record<string, EffectHandler>;
+  /**
+   * Routing override for cross-resource reads, replacing the Studio's
+   * default per-dataset routing — see `useWorkflowEngine`. A served resource
+   * is also part of the declared surface for written refs, so this is how a
+   * plugin setup admits runtime-supplied `doc.ref` values to a foreign
+   * resource (media-library, canvas, another dataset). Keep the value
+   * stable (module scope or memoized).
+   */
+  readonly resourceClients?: ResourceClientResolver;
 }
 
 declare interface WorkflowPreviewProps extends PreviewProps {

package/dist/index.d.ts

@@ -1,14 +1,17 @@
 import type { DefaultDocumentNodeResolver } from "sanity/structure";
 import { EffectHandler } from "@sanity/workflow-engine";
-import { EffectsContext } from "@sanity/workflow-engine";
 import { GlobalDocumentReference } from "@sanity/workflow-engine";
 import { InitialFieldValue } from "@sanity/workflow-engine";
 import { JSX } from "react";
 import { Plugin as Plugin_2 } from "sanity";
 import { PreviewProps } from "sanity";
+import { ResourceClientResolver } from "@sanity/workflow-engine";
+import { StartContext } from "@sanity/workflow-engine";
 import type { StructureBuilder } from "sanity/structure";
 import type { ViewBuilder } from "sanity/structure";
 
+/** The first mapping row for a document type — the tie-break wherever a
+ *  surface binds to exactly one row. */
 export declare function mappingForDocType(
   mappings: readonly WorkflowMapping[],
   docType: string,
@@ -43,9 +46,11 @@ export declare interface WorkflowMapping {
   readonly docType: string;
   /**
    * The document type must have a workflow: the editor form is gated until
-   * an instance references the document. Advisory, UI-only enforcement —
-   * any raw API client can still write; the Content Lake is the only
-   * enforcement point.
+   * an instance references the document. Doctype-level: the flag on ANY
+   * mapping row for a docType gates the form, and starting any mapped
+   * workflow satisfies the gate. Advisory, UI-only enforcement — any raw
+   * API client can still write; the Content Lake is the only enforcement
+   * point.
    */
   readonly mandatory?: boolean;
   /** The definition `name` the engine deployed under. */
@@ -61,10 +66,10 @@ export declare interface WorkflowMapping {
   readonly initialStateBuilder?: (
     subjectGdr: GlobalDocumentReference,
   ) => InitialFieldValue[];
-  /** Optional effectsContext seed. */
-  readonly effectsContextBuilder?: (
+  /** Optional `$context` seed passed to `startInstance` as its `context`. */
+  readonly contextBuilder?: (
     subjectGdr: GlobalDocumentReference,
-  ) => EffectsContext;
+  ) => StartContext;
   /**
    * When set, the Start action reads Studio's `usePerspective()` to pull the
    * active release. If a release is selected, the named `release.ref` field
@@ -100,6 +105,15 @@ export declare interface WorkflowPluginConfig {
    * runtime to claim.
    */
   readonly effectHandlers?: Record<string, EffectHandler>;
+  /**
+   * Routing override for cross-resource reads, replacing the Studio's
+   * default per-dataset routing — see `useWorkflowEngine`. A served resource
+   * is also part of the declared surface for written refs, so this is how a
+   * plugin setup admits runtime-supplied `doc.ref` values to a foreign
+   * resource (media-library, canvas, another dataset). Keep the value
+   * stable (module scope or memoized).
+   */
+  readonly resourceClients?: ResourceClientResolver;
 }
 
 declare interface WorkflowPreviewProps extends PreviewProps {