@sanity/workflow-studio-plugin 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,119 @@
+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 type { StructureBuilder } from "sanity/structure";
+import type { ViewBuilder } from "sanity/structure";
+
+export declare function mappingForDocType(
+  mappings: readonly WorkflowMapping[],
+  docType: string,
+): WorkflowMapping | undefined;
+
+/**
+ * Convenience `defaultDocumentNode`: mapped document types get the form view
+ * plus the Workflows view; everything else keeps the structure default.
+ *
+ * ```ts
+ * structureTool({defaultDocumentNode: workflowDefaultDocumentNode({mappings})})
+ * ```
+ */
+export declare function workflowDefaultDocumentNode(options: {
+  mappings: readonly WorkflowMapping[];
+}): DefaultDocumentNodeResolver;
+
+/** The schema types the plugin contributes workflow surfaces to. */
+export declare function workflowDocTypes(
+  mappings: readonly WorkflowMapping[],
+): ReadonlySet<string>;
+
+/**
+ * Doctype → workflow binding. Drives every per-doctype contribution the
+ * plugin makes: which document actions and badges to add, which document
+ * view to offer, what to project as the subject when starting an instance.
+ * Adding a workflow-driven doctype to a studio is one entry in the host's
+ * mapping table.
+ */
+export declare interface WorkflowMapping {
+  /** Studio schema type. */
+  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.
+   */
+  readonly mandatory?: boolean;
+  /** The definition `name` the engine deployed under. */
+  readonly definition: string;
+  /** Logical role of the doc — sets the GDR `type` discriminator in the
+   *  builders. Subject lives on a field `doc.ref` entry, not an envelope. */
+  readonly subjectKind: "document" | "release";
+  /** Schema type stamped into the `doc.ref` field entry's `value.type`. */
+  readonly subjectGdrType: string;
+  /** Human-readable label for menus and dialogs. */
+  readonly label: string;
+  /** Optional initial workflow field entries to seed on Start. */
+  readonly initialStateBuilder?: (
+    subjectGdr: GlobalDocumentReference,
+  ) => InitialFieldValue[];
+  /** Optional effectsContext seed. */
+  readonly effectsContextBuilder?: (
+    subjectGdr: GlobalDocumentReference,
+  ) => EffectsContext;
+  /**
+   * When set, the Start action reads Studio's `usePerspective()` to pull the
+   * active release. If a release is selected, the named `release.ref` field
+   * entry is seeded with the release's system-document GDR plus its bare
+   * `releaseName`, and the engine derives the instance's perspective from
+   * it — so editors can pick a release in the Studio header and start the
+   * workflow against it.
+   */
+  readonly perspectiveField?: {
+    /** Field entry name on the workflow definition (e.g. "release"). */
+    readonly name: string;
+    /**
+     * If true, the Start action stays disabled until a release is selected
+     * in Studio's perspective. If false (default), the action runs without
+     * perspective and the workflow uses its defaults.
+     */
+    readonly required?: boolean;
+  };
+}
+
+export declare interface WorkflowPluginConfig {
+  /** Engine tag partition — scopes every workflow read and write. */
+  readonly tag: string;
+  /** Dataset holding workflow definitions + instances. Defaults to the
+   *  workspace's own dataset (single-dataset setup). */
+  readonly workflowDataset?: string;
+  /** Document type → workflow definition bindings. */
+  readonly mappings: readonly WorkflowMapping[];
+  /**
+   * Browser-side effect handlers keyed by effect name (the engine's
+   * {@link EffectHandler}). Registered handlers drain in the Studio after
+   * each committed action; anything unregistered stays pending for another
+   * runtime to claim.
+   */
+  readonly effectHandlers?: Record<string, EffectHandler>;
+}
+
+declare interface WorkflowPreviewProps extends PreviewProps {
+  readonly _id?: string;
+  readonly documentId?: string;
+}
+
+export declare function WorkflowStagePreview(
+  props: WorkflowPreviewProps,
+): JSX.Element;
+
+export declare const workflowStudioPlugin: Plugin_2<WorkflowPluginConfig>;
+
+/** The Workflows view for one document — append it to any `views([...])`. */
+export declare function workflowsView(S: StructureBuilder): ViewBuilder;
+
+export {};

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+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 type { StructureBuilder } from "sanity/structure";
+import type { ViewBuilder } from "sanity/structure";
+
+export declare function mappingForDocType(
+  mappings: readonly WorkflowMapping[],
+  docType: string,
+): WorkflowMapping | undefined;
+
+/**
+ * Convenience `defaultDocumentNode`: mapped document types get the form view
+ * plus the Workflows view; everything else keeps the structure default.
+ *
+ * ```ts
+ * structureTool({defaultDocumentNode: workflowDefaultDocumentNode({mappings})})
+ * ```
+ */
+export declare function workflowDefaultDocumentNode(options: {
+  mappings: readonly WorkflowMapping[];
+}): DefaultDocumentNodeResolver;
+
+/** The schema types the plugin contributes workflow surfaces to. */
+export declare function workflowDocTypes(
+  mappings: readonly WorkflowMapping[],
+): ReadonlySet<string>;
+
+/**
+ * Doctype → workflow binding. Drives every per-doctype contribution the
+ * plugin makes: which document actions and badges to add, which document
+ * view to offer, what to project as the subject when starting an instance.
+ * Adding a workflow-driven doctype to a studio is one entry in the host's
+ * mapping table.
+ */
+export declare interface WorkflowMapping {
+  /** Studio schema type. */
+  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.
+   */
+  readonly mandatory?: boolean;
+  /** The definition `name` the engine deployed under. */
+  readonly definition: string;
+  /** Logical role of the doc — sets the GDR `type` discriminator in the
+   *  builders. Subject lives on a field `doc.ref` entry, not an envelope. */
+  readonly subjectKind: "document" | "release";
+  /** Schema type stamped into the `doc.ref` field entry's `value.type`. */
+  readonly subjectGdrType: string;
+  /** Human-readable label for menus and dialogs. */
+  readonly label: string;
+  /** Optional initial workflow field entries to seed on Start. */
+  readonly initialStateBuilder?: (
+    subjectGdr: GlobalDocumentReference,
+  ) => InitialFieldValue[];
+  /** Optional effectsContext seed. */
+  readonly effectsContextBuilder?: (
+    subjectGdr: GlobalDocumentReference,
+  ) => EffectsContext;
+  /**
+   * When set, the Start action reads Studio's `usePerspective()` to pull the
+   * active release. If a release is selected, the named `release.ref` field
+   * entry is seeded with the release's system-document GDR plus its bare
+   * `releaseName`, and the engine derives the instance's perspective from
+   * it — so editors can pick a release in the Studio header and start the
+   * workflow against it.
+   */
+  readonly perspectiveField?: {
+    /** Field entry name on the workflow definition (e.g. "release"). */
+    readonly name: string;
+    /**
+     * If true, the Start action stays disabled until a release is selected
+     * in Studio's perspective. If false (default), the action runs without
+     * perspective and the workflow uses its defaults.
+     */
+    readonly required?: boolean;
+  };
+}
+
+export declare interface WorkflowPluginConfig {
+  /** Engine tag partition — scopes every workflow read and write. */
+  readonly tag: string;
+  /** Dataset holding workflow definitions + instances. Defaults to the
+   *  workspace's own dataset (single-dataset setup). */
+  readonly workflowDataset?: string;
+  /** Document type → workflow definition bindings. */
+  readonly mappings: readonly WorkflowMapping[];
+  /**
+   * Browser-side effect handlers keyed by effect name (the engine's
+   * {@link EffectHandler}). Registered handlers drain in the Studio after
+   * each committed action; anything unregistered stays pending for another
+   * runtime to claim.
+   */
+  readonly effectHandlers?: Record<string, EffectHandler>;
+}
+
+declare interface WorkflowPreviewProps extends PreviewProps {
+  readonly _id?: string;
+  readonly documentId?: string;
+}
+
+export declare function WorkflowStagePreview(
+  props: WorkflowPreviewProps,
+): JSX.Element;
+
+export declare const workflowStudioPlugin: Plugin_2<WorkflowPluginConfig>;
+
+/** The Workflows view for one document — append it to any `views([...])`. */
+export declare function workflowsView(S: StructureBuilder): ViewBuilder;
+
+export {};