@knkcs/contenthub-ui 0.3.0 → 0.4.0

package/dist/testing.d.ts

@@ -14,6 +14,17 @@ 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;
+    /** 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;
@@ -116,6 +127,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 +166,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[];
@@ -182,6 +203,11 @@ declare interface ChangeSetStatusInfo {
     name: string;
     /** Its colour as statushub holds it (a CSS colour); absent for none. */
     color?: string;
+    /**
+     * statushub's default for the catalogue: what a Change Set without a
+     * status reads as (ADR 0014 D9). At most one status has it.
+     */
+    isDefault?: boolean;
 }
 
 /** What `updateChangeSet` changes of a Change Set. */
@@ -370,6 +396,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;
@@ -452,6 +482,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
@@ -544,6 +597,39 @@ 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;
+    }): 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[]>;
     /**
@@ -714,12 +800,15 @@ declare interface ContenthubClient {
     }): Promise<Content>;
     /**
      * One Content with its Blueprint Release and attributes: on Main, or
-     * inside `changeSetId`. Content born in an open Change Set exists only
-     * there, so read anywhere else it is a NotFound ConnectError.
+     * inside `changeSetId`, at the head of its Chain's last Branch, or of
+     * `branchId`, a Branch of that Chain, when given (#252). Content born in
+     * an open Change Set exists only there, so read anywhere else it is a
+     * NotFound ConnectError, as is a Branch outside the Chain.
      */
     getContent(input: {
         id: string;
         changeSetId?: string;
+        branchId?: string;
     }): Promise<ContentDetail>;
     /** Its Timeline, with the Planned Releases of open Change Sets beside it. */
     getTimeline(contentId: string): Promise<ContentTimeline>;
@@ -795,6 +884,43 @@ 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 the Content is Dated, `ContentBlockedError`, `ContentArchivedError`,
+     * and `InvalidInputError` for anything else the service refuses.
+     */
+    openDirectEdit(input: {
+        contentId: string;
+        /** Makes a retry safe (CONTEXT.md, Idempotency Key). */
+        idempotencyKey?: string;
+    }): Promise<{
+        changeSet: ChangeSet;
+        content: Content;
+        reopened: boolean;
+    }>;
+    /**
+     * Publishes a Direct Edit at `expectedHeadId`, the head of its Branch the
+     * editor saw: one Release, In Force from its Publish. Rejects as
+     * `publish` does, and with `DirectEditRefusedError` for a Change Set that
+     * is not a Direct Edit.
+     */
+    publishDirectEdit(input: {
+        id: string;
+        expectedHeadId: string;
+        idempotencyKey?: string;
+    }): Promise<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>;
     startEditing(input: {
         contentId: string;
         changeSetId?: string;
@@ -973,6 +1099,28 @@ 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";
 
+/**
+ * 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 editing settings in effect for one Blueprint, and which its override decides. */
+declare interface EffectiveEditingSettings {
+    effective: EditingSettings;
+    editingModeOverridden: boolean;
+    editingBlockOverridden: boolean;
+}
+
 /** One field that differs between two Revisions. */
 declare interface FieldChange {
     /** "/" and the field's accessor. */
@@ -1252,6 +1400,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. */
@@ -1321,7 +1474,8 @@ declare interface RevisionList {
  * The port a host fills with statushub (ADR 0020): the workspace's Change Set
  * statuses, for their display names and colours. contenthub-ui depends on no
  * statushub package. A host without statushub leaves the port empty, and the
- * screens then show the bare slug and offer no status picker.
+ * screens then show the bare slug and offer no status picker. The status
+ * marked `isDefault` names a Change Set that has none yet (ADR 0014 D9).
  */
 declare interface StatusSource {
     /** Every status of the workspace's `contenthub/change_set` catalogue, in its order. */
@@ -1517,6 +1671,13 @@ 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.
+     */
+    editingSettings?: EditingSettings;
+    /** The per-Blueprint overrides of the editing settings; none by default. */
+    editingOverrides?: StubEditingOverride[];
 }
 
 /**
@@ -1527,6 +1688,13 @@ 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;
+}
+
 /** One head of a Content: its Revision, data and when it was written. */
 export declare interface StubHead {
     revisionId: string;
@@ -1567,6 +1735,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. */
@@ -1604,4 +1780,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 { }