@knkcs/contenthub-ui 0.3.1 → 0.5.0

package/dist/testing.d.ts

@@ -14,6 +14,19 @@ declare interface BlockReason {
     updateTime: string;
 }
 
+/** One Blueprint's override of the workspace's editing settings. */
+declare interface BlueprintEditingOverride {
+    blueprintAccessor: string;
+    /** null follows the workspace's. */
+    editingMode: EditingMode | null;
+    /** null follows the workspace's. */
+    editingBlock: boolean | null;
+    /** The people beside the admins; null follows the workspace's, [] is the admins alone. */
+    forceGroup: string[] | null;
+    /** What applies to the Blueprint's Content: this override over the workspace's. */
+    effective: EditingSettings;
+}
+
 /** A content Blueprint, as the `BlueprintSource` port names it. */
 declare interface BlueprintInfo {
     id: string;
@@ -72,6 +85,13 @@ declare interface BlueprintSource {
 /** What a Branch is for: one an editor works on, or a Carry-forward link. */
 declare type BranchKind = "editorial" | "carry_forward";
 
+/** Whether a Direct Edit's change carries forward into one later wording (#270). */
+declare interface CarryForwardAnswer {
+    /** The later wording: the Release a Carry-forward link carries. */
+    releaseId: string;
+    carry: boolean;
+}
+
 /** What a Chain on Dated Content, effective on a date, would be and meet (PreviewChain). */
 declare interface ChainPreview {
     /** The Release it would fork from; "" in a gap. */
@@ -116,6 +136,10 @@ declare interface ChangeSet {
      * planned. Empty in a list.
      */
     plannedReleases: PlannedRelease[];
+    /** A Direct Edit, or one editors build; absent reads as "change_set". */
+    kind?: ChangeSetKind;
+    /** A Direct Edit's editor, an odon user id; absent or "" for any other kind. */
+    editorId?: string;
 }
 
 /** One Branch of a Chain, with the head a save on it names. */
@@ -151,6 +175,12 @@ declare interface ChangeSetChain {
     branches: ChangeSetBranch[];
 }
 
+/**
+ * What kind of Change Set one is (ADR 0022): a Direct Edit, opened from one
+ * Content for one editor, or one editors build Chain by Chain.
+ */
+declare type ChangeSetKind = "change_set" | "direct_edit";
+
 /** One page of `listChangeSets`. */
 declare interface ChangeSetList {
     changeSets: ChangeSet[];
@@ -307,6 +337,8 @@ declare interface ContentAttributes {
     block?: ContentBlock;
     /** When it was archived, ISO 8601; absent while it is not Archived. */
     archiveTime?: string;
+    /** Its Editing Block; absent while no open Direct Edit holds one. */
+    editingBlock?: EditingBlock;
 }
 
 /**
@@ -375,6 +407,10 @@ declare interface ContenthubClient {
         assigneeId?: string;
         /** Only those with a Chain on this Content. */
         contentId?: string;
+        /** Only those of this kind: the index asks for "change_set", hiding Direct Edits. */
+        kind?: ChangeSetKind;
+        /** Only the Direct Edits of this odon user. */
+        editorId?: string;
         /** At most 200; 50 when absent. */
         pageSize?: number;
         pageToken?: string;
@@ -457,6 +493,29 @@ declare interface ContenthubClient {
         id: string;
         reviewedHeads: Record<string, string>;
     }): Promise<PublishOutcome>;
+    /**
+     * Change validity (ADR 0022): corrects only a published Release's
+     * Validity Period, in one request and without a Direct Edit. It opens a
+     * Change Set, plans the date-only Release re-pinning the Release's
+     * Revision and superseding it, and publishes it with the proposals for
+     * the neighbouring Releases; the outcome is that Publish's. Refused as a
+     * whole, it leaves no Change Set behind: rejects with
+     * `EditingModeRefusedError` where the Content's Blueprint is "Change Sets
+     * only", `CoversReleaseError` (`changeSetRequired`) when the period would
+     * cover another Release entirely, `PublishRefusedError` with every
+     * blocker (an outstanding Required Check among them),
+     * `AccessDeniedError` for a caller who may not publish,
+     * `ContentBlockedError` and `InvalidInputError` for what else the service
+     * refuses.
+     */
+    changeValidity(input: {
+        releaseId: string;
+        validityPeriod: ValidityPeriod;
+        /** The Change Set's name; the service names it after the Content when absent. */
+        changeSetName?: string;
+        /** Makes a retry safe (CONTEXT.md, Idempotency Key). */
+        idempotencyKey?: string;
+    }): Promise<PublishOutcome>;
     /**
      * Merges what Main (and each dependency) gained since into every Chain
      * of the Change Set. A Branch whose merge has Conflicts, or fails its
@@ -549,6 +608,41 @@ declare interface ContenthubClient {
         requiredCheckId: string;
         recorder: RecorderGrant;
     }): Promise<void>;
+    /**
+     * How the workspace's Content may be changed (ADR 0022): its own Editing
+     * Mode and Editing Block, and every per-Blueprint override with the
+     * values it makes effective. A workspace that never set them reads as
+     * "Change Sets only" without an Editing Block.
+     */
+    getEditingSettings(): Promise<WorkspaceEditingSettings>;
+    /**
+     * The editing settings in effect for the Content of the Blueprint with
+     * `blueprintAccessor`: its override over the workspace's, field by
+     * field. A host's Blueprint page reads it.
+     */
+    getEffectiveEditingSettings(blueprintAccessor: string): Promise<EffectiveEditingSettings>;
+    /**
+     * Replaces the workspace's own editing settings; admin only. It takes
+     * effect at once. Rejects with `AccessDeniedError` for a non-admin and
+     * `InvalidInputError` for what the service refuses.
+     */
+    setEditingSettings(settings: EditingSettings): Promise<EditingSettings>;
+    /**
+     * Replaces one Blueprint's override; admin only. A null field follows the
+     * workspace's, and at least one must be set. Rejects as
+     * `setEditingSettings` does.
+     */
+    setBlueprintEditingOverride(input: {
+        blueprintAccessor: string;
+        editingMode: EditingMode | null;
+        editingBlock: boolean | null;
+        /** null follows the workspace's; [] is the admins alone. */
+        forceGroup: string[] | null;
+    }): Promise<BlueprintEditingOverride>;
+    /** Removes one Blueprint's override, so it follows the workspace's; admin only. */
+    deleteBlueprintEditingOverride(input: {
+        blueprintAccessor: string;
+    }): Promise<void>;
     /** Every Collection of the workspace, by name, then id: a tree by `parentId`. */
     listCollections(): Promise<Collection[]>;
     /**
@@ -803,6 +897,115 @@ declare interface ContenthubClient {
      * `ChangeSetClosedError`, and `InvalidInputError` for anything else the
      * service refuses (a missing or needless effective date).
      */
+    /**
+     * Opens a Direct Edit of a published Content for the caller (ADR 0022),
+     * or answers the one the caller has open on it, with `reopened`. Answers
+     * the Direct Edit and the Content as read on its Branch. Rejects with
+     * `EditingModeRefusedError` where the Editing Mode is "Change Sets only",
+     * `DirectEditRefusedError` where another editor's Direct Edit holds its
+     * Editing Block (naming them), `ContentBlockedError`, `ContentArchivedError`,
+     * and `InvalidInputError` for anything else the service refuses (a day
+     * for undated Content among it).
+     */
+    openDirectEdit(input: {
+        contentId: string;
+        /**
+         * Dated Content only (#270): the day the change takes effect, as
+         * YYYY-MM-DD; absent is today. Its Branch forks from the Release In
+         * Force that day: on today it corrects that Release, on a later day
+         * it is a new wording.
+         */
+        effectiveOn?: string;
+        /** Makes a retry safe (CONTEXT.md, Idempotency Key). */
+        idempotencyKey?: string;
+    }): Promise<{
+        changeSet: ChangeSet;
+        content: Content;
+        reopened: boolean;
+    }>;
+    /**
+     * What a Direct Edit's Publish of Dated Content would plan (#270): its
+     * Release's Validity Period with `validityLastDay` as Publish takes it,
+     * the Release it corrects, the date-only Releases contenthub derives and
+     * the later wordings Publish asks about. Writes nothing. Rejects with
+     * `CoversReleaseError` (`changeSetRequired`) when the period would cover
+     * a Release entirely.
+     */
+    previewDirectEditPublish(input: {
+        id: string;
+        validityLastDay?: string;
+    }): Promise<DirectEditPublishPreview>;
+    /**
+     * Publishes a Direct Edit at `expectedHeadId`, the head of its Branch the
+     * editor saw: one Release, In Force from its Publish, carrying
+     * `releaseSpec`. Rejects as `publish` does, with `ContentRefusedError`
+     * for Release Spec values the Blueprint Release refuses (a required one
+     * missing among them), and with `DirectEditRefusedError` for a Change
+     * Set that is not a Direct Edit. On Dated Content (#270) it takes the
+     * Validity Period's last day and one carry-forward answer per later
+     * wording, and rejects with `CoversReleaseError` (`changeSetRequired`)
+     * when the period would cover a Release entirely.
+     */
+    publishDirectEdit(input: {
+        id: string;
+        expectedHeadId: string;
+        /** The Release's Release Spec values; absent is none. */
+        releaseSpec?: Record<string, unknown>;
+        /** Dated Content: the period's last day, "" for an open end; absent keeps the default. */
+        validityLastDay?: string;
+        /** Dated Content: whether the change carries into each later wording. */
+        carryForward?: CarryForwardAnswer[];
+        idempotencyKey?: string;
+    }): Promise<PublishOutcome>;
+    /**
+     * Saves on a Direct Edit's Branch on top of `expectedHeadId`, as
+     * `saveRevision` does, and publishes the Revision saved, as
+     * `publishDirectEdit` does, in one request (ADR 0022). Refused as a
+     * whole, with nothing saved: rejects as either does (`StaleHeadError`,
+     * `ContentRefusedError` for the data or the Release Spec values,
+     * `PublishRefusedError` with every blocker).
+     */
+    saveAndPublishDirectEdit(input: {
+        id: string;
+        expectedHeadId: string;
+        data: Record<string, unknown>;
+        /** Top-level field accessors; absent saves `data` as the whole Revision. */
+        fieldMask?: string[];
+        releaseSpec?: Record<string, unknown>;
+        /** As `publishDirectEdit`'s. */
+        validityLastDay?: string;
+        carryForward?: CarryForwardAnswer[];
+        idempotencyKey?: string;
+    }): Promise<{
+        content: Content;
+        outcome: PublishOutcome;
+    }>;
+    /**
+     * Discards a Direct Edit: its work is dropped, Main and the Releases stay.
+     * Rejects as `discardChangeSet` does, and with `DirectEditRefusedError`
+     * for a Change Set that is not a Direct Edit.
+     */
+    discardDirectEdit(input: {
+        id: string;
+        idempotencyKey?: string;
+    }): Promise<ChangeSet>;
+    /**
+     * Forces an Editing Block (ADR 0022): hands the Direct Edit `id` holding
+     * it, with its work and its Editing Block, to the caller. Answers it with
+     * the caller as its editor, the Content as read on its Branch, and who
+     * edited it until now. Rejects with `AccessDeniedError` outside the
+     * Force Group, `DirectEditRefusedError` where the caller has a Direct
+     * Edit of the Content of their own or it holds no Editing Block any more,
+     * and as `discardDirectEdit` does otherwise.
+     */
+    forceDirectEdit(input: {
+        id: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        changeSet: ChangeSet;
+        content: Content;
+        previousEditorId: string;
+    }>;
     startEditing(input: {
         contentId: string;
         changeSetId?: string;
@@ -963,6 +1166,21 @@ export declare function createStubContenthubClient(options?: StubContenthubClien
 
 export declare function createStubStatusSource(statuses?: ChangeSetStatusInfo[]): StatusSource;
 
+/**
+ * What a Direct Edit's Publish of Dated Content would plan (#270), for its
+ * Publish dialog: nothing of it is written.
+ */
+declare interface DirectEditPublishPreview {
+    /** Its Release's Validity Period; an empty last day is an open end. */
+    validityPeriod?: ValidityPeriod;
+    /** The Release it corrects and Supersedes; "" for a new wording. */
+    correctsReleaseId: string;
+    /** The date-only Releases contenthub derives, read-only. */
+    dateOnlyReleases: PlannedRelease[];
+    /** The later wordings Publish asks about, by first day. */
+    laterWordings: LaterWording[];
+}
+
 /** One edge of one Revision. */
 declare interface Edge {
     sourceContentId: string;
@@ -981,6 +1199,56 @@ declare interface Edge {
 /** What kind of edge of the Content Graph (ADR 0009). */
 declare type EdgeKind = "reference" | "toc" | "include" | "exclude" | "replace" | "annotate" | "link" | "footnote" | "anchor" | "media" | "blueprint" | "unspecified";
 
+/**
+ * The Block a Direct Edit sets on its Content (CONTEXT.md, Editing Block):
+ * "being edited by" its editor. It keeps out only other editors' Direct
+ * Edits, ends with its Direct Edit's Publish or Discard, and can't be
+ * lifted. It is independent of `block`: a Content can hold both.
+ */
+declare interface EditingBlock {
+    /** The Direct Edit's editor, an odon user id. */
+    editorId: string;
+    /** The Direct Edit holding it. */
+    changeSetId: string;
+    /** ISO 8601. */
+    blockTime: string;
+}
+
+/**
+ * Which ways of changing a Blueprint's Content the workspace offers (ADR
+ * 0022, CONTEXT.md Editing Mode): Direct Edits only, Change Sets only, or
+ * both. Only "change_sets" is a rule: contenthub refuses a Direct Edit on
+ * such Content.
+ */
+declare type EditingMode = "direct_edits" | "change_sets" | "both";
+
+/** The workspace's editing settings, or the ones in effect for a Blueprint. */
+declare interface EditingSettings {
+    editingMode: EditingMode;
+    /** Whether opening a Direct Edit sets an Editing Block on its Content. */
+    editingBlock: boolean;
+    /**
+     * The Force Group: who may force an Editing Block (ADR 0022). The
+     * workspace's admins always may; these are the people beside them, by
+     * odon user id, sorted. Empty is the admins alone.
+     */
+    forceGroup: string[];
+}
+
+/** The editing settings in effect for one Blueprint, and which its override decides. */
+declare interface EffectiveEditingSettings {
+    effective: EditingSettings;
+    editingModeOverridden: boolean;
+    editingBlockOverridden: boolean;
+    forceGroupOverridden: boolean;
+    /**
+     * Whether the caller is in the effective Force Group: an admin, or named
+     * by it. It is how a screen knows to offer Force (#269); the service
+     * asks the same when it is used.
+     */
+    callerInForceGroup: boolean;
+}
+
 /** One field that differs between two Revisions. */
 declare interface FieldChange {
     /** "/" and the field's accessor. */
@@ -1007,6 +1275,12 @@ declare interface GapReferrer {
     releaseId: string;
 }
 
+/** A later wording a Direct Edit's change may carry into (#270). */
+declare interface LaterWording {
+    releaseId: string;
+    validityPeriod?: ValidityPeriod;
+}
+
 /** One field a merge resolution must decide, with each side's value. */
 declare interface MergeField {
     /** "/" and the field's accessor, as a Violation spells it. */
@@ -1260,6 +1534,11 @@ declare interface RequiredCheckRecorders {
 declare interface ResolvedBlueprintRelease {
     /** The Blueprint's name, as the released Revision holds it; "" if it holds none. */
     displayName: string;
+    /**
+     * The Blueprint's accessor, which its editing settings are keyed by;
+     * "" or absent when the Resolved Release names none.
+     */
+    accessor?: string;
     /** Whether its Content is Dated: its Releases carry a Validity Period. */
     dated: boolean;
     /** fieldkit's Resolved Spec fields, in Blueprint order. */
@@ -1407,6 +1686,8 @@ export declare interface StubContent {
     assigneeIds?: string[];
     /** Its Block; absent while it is not blocked. */
     block?: ContentBlock;
+    /** Its Editing Block; absent while no open Direct Edit holds one. */
+    editingBlock?: EditingBlock;
     /** When it was archived, ISO 8601; absent while it is not Archived. */
     archiveTime?: string;
     /** Its Main head; absent while it was born in an open Change Set. */
@@ -1484,6 +1765,13 @@ export declare interface StubContenthubClientOptions {
      * derive (moved_head, the dependencies', outstanding_check).
      */
     publishBlockers?: Record<string, PublishBlocker[]>;
+    /**
+     * The Branches behind their base, by id, as a Change Set published past
+     * them leaves them (#268): `validatePublish` and `publish` report
+     * behind_base for each until `updateFromMain` merges it or a resolution
+     * of its Pending Merge does. An aborted merge leaves it behind.
+     */
+    behind?: string[];
     /** The Pending Merges `updateFromMain` leaves, by Change Set id; none by default. */
     pendingMerges?: Record<string, PendingMergeRef[]>;
     /**
@@ -1526,6 +1814,16 @@ export declare interface StubContenthubClientOptions {
     userId?: string;
     /** The time every write stamps; STUB_NOW by default. */
     now?: () => string;
+    /**
+     * The workspace's own editing settings; "Change Sets only" without an
+     * Editing Block by default, as for a workspace that never set them. A
+     * Force Group left out is the admins alone.
+     */
+    editingSettings?: Omit<EditingSettings, "forceGroup"> & {
+        forceGroup?: string[];
+    };
+    /** The per-Blueprint overrides of the editing settings; none by default. */
+    editingOverrides?: StubEditingOverride[];
 }
 
 /**
@@ -1536,6 +1834,15 @@ export declare interface StubContenthubClientOptions {
  */
 export declare function stubContents(): StubContent[];
 
+/** One stored override: a null field follows the workspace's. */
+export declare interface StubEditingOverride {
+    blueprintAccessor: string;
+    editingMode: EditingMode | null;
+    editingBlock: boolean | null;
+    /** The people beside the admins; null follows the workspace's. Absent is null. */
+    forceGroup?: string[] | null;
+}
+
 /** One head of a Content: its Revision, data and when it was written. */
 export declare interface StubHead {
     revisionId: string;
@@ -1576,6 +1883,14 @@ export declare function stubResolvedReleases(): Record<string, ResolvedBlueprint
  */
 export declare function stubStatusTransitions(): Record<string, string[]>;
 
+/**
+ * An editorial note, undated and published, whose Blueprint `note` is what a
+ * Direct Edit edits (ADR 0022, #264): Dated Content takes none yet. Not among
+ * `stubContents()`, so the Library's fixtures stay as they are; pass it in
+ * with `contents`, and set the stub's `editingSettings` to offer Edit.
+ */
+export declare function stubUndatedContent(): StubContent;
+
 /** One Release of a Content's Timeline (CONTEXT.md, Timeline), without its data. */
 declare interface TimelineEntry {
     /** Its place in the Timeline, from 1. */
@@ -1613,4 +1928,10 @@ declare interface ValidityPeriod {
     lastDay: string;
 }
 
+/** The workspace's editing settings and every per-Blueprint override, by accessor. */
+declare interface WorkspaceEditingSettings {
+    workspace: EditingSettings;
+    overrides: BlueprintEditingOverride[];
+}
+
 export { }