@supernova-studio/client 1.96.5 → 1.96.7

package/src/yjs/version-room/compute-dto.ts

@@ -0,0 +1,387 @@
+import {
+  DocumentationItemConfigurationV2,
+  DocumentationPageSnapshot,
+  ElementGroupSnapshot,
+  defaultDocumentationItemConfigurationV2,
+  mapByUnique,
+  pickLatestGroupSnapshots,
+  pickLatestPageSnapshots,
+  recordToMap,
+} from "@supernova-studio/model";
+import {
+  DTODocumentationDraftState,
+  DTODocumentationDraftStateUpdated,
+  DTODocumentationGroupApprovalState,
+  DTODocumentationHierarchyV2,
+  documentationItemConfigurationToDTOV2,
+  documentationPagesToDTOV2,
+  elementGroupsToDocumentationGroupDTOV2,
+} from "../../api";
+import { DTODocumentationPublishMetadata } from "../../api/dto/elements/documentation/metadata";
+import { LocalApproval, LocalDocsPage, LocalDocsPageGroup } from "../../sync/types";
+import { generateHash } from "../../utils";
+import { DocumentationHierarchySettings } from "../design-system-content";
+import { VersionRoomApproval, VersionRoomDocsPage, VersionRoomDocsPageGroup } from "./types";
+
+type ItemState = {
+  title: string;
+  configuration: DocumentationItemConfigurationV2;
+  contentHash: string;
+};
+
+type DocsPage = VersionRoomDocsPage | LocalDocsPage;
+type DocsPageGroup = VersionRoomDocsPageGroup | LocalDocsPageGroup;
+type Approval = VersionRoomApproval | LocalApproval;
+
+type Input = {
+  pages: DocsPage[];
+  pageSnapshots: DocumentationPageSnapshot[];
+  pageContentHashes: Record<string, string>;
+  pageLiveblockRoomIds: Record<string, string>;
+
+  groups: DocsPageGroup[];
+  groupSnapshots: ElementGroupSnapshot[];
+
+  approvals: Approval[];
+  settings: DocumentationHierarchySettings;
+};
+
+export function computeDocsHierarchy(
+  input: Input,
+  options: { includeDeletedContent?: boolean; debug?: boolean } = {}
+): DTODocumentationHierarchyV2 {
+  const includeDeletedContent = options.includeDeletedContent ?? false;
+  const debug = options.debug ?? false;
+
+  // Read current room data
+  const { pages, groups, pageSnapshots, groupSnapshots, settings, pageContentHashes, approvals, pageLiveblockRoomIds } =
+    input;
+
+  if (settings.isDraftFeatureAdopted && includeDeletedContent) {
+    pages.push(...getDeletedPages(pages, pageSnapshots));
+    groups.push(...getDeletedGroups(groups, groupSnapshots));
+  }
+
+  // Convert pages to DTOs
+  const pageDTOs = documentationPagesToDTOV2(pages, groups, settings.routingVersion, recordToMap(pageLiveblockRoomIds));
+  const groupDTOs = elementGroupsToDocumentationGroupDTOV2(groups, pages);
+
+  // Calculate hasPublishedDocumentationContent
+  const hasPublishedPages = pageSnapshots.some(s => s.reason === "Publish");
+  const hasPublishedGroups = groupSnapshots.some(s => s.reason === "Publish");
+  const hasPublishedDocumentationContent = hasPublishedPages || hasPublishedGroups;
+
+  // If draft feature is not yet adopted, no snapshot-based features should not be provided
+  if (!settings.isDraftFeatureAdopted) {
+    return {
+      hasPublishedDocumentationContent,
+      pages: pageDTOs,
+      groups: groupDTOs,
+    };
+  }
+
+  const pageDraftStates = buildPageDraftCreatedAndUpdatedStates(pages, pageSnapshots, pageContentHashes, debug);
+  const pageDraftDeletedStates = buildPageDraftDeletedStates(pages, pageSnapshots);
+  const pagePublishedMetadata = buildPagePublishedMetadata(pages, pageSnapshots);
+  const pageApprovalStates = mapByUnique(approvals, a => a.pagePersistentId);
+
+  pageDTOs.forEach(p => {
+    // Assign draft state
+    const draftState = pageDraftDeletedStates.get(p.persistentId) ?? pageDraftStates.get(p.persistentId);
+    draftState && (p.draftState = draftState);
+
+    // Assign publish metadata
+    const publishMetadata = pagePublishedMetadata.get(p.persistentId);
+    publishMetadata && (p.publishMetadata = publishMetadata);
+
+    // Assign approval state
+    const approvalState = pageApprovalStates.get(p.persistentId);
+    approvalState && (p.approvalState = approvalState);
+  });
+
+  const groupDraftStates = buildGroupDraftCreatedAndUpdatedStates(groups, groupSnapshots, debug);
+  const groupDraftDeletedStates = buildGroupDraftDeletedStates(groups, groupSnapshots);
+  const groupPublishedMetadata = buildGroupPublishedMetadata(groups, groupSnapshots);
+  const groupApprovalStates = buildGroupApprovalStates(groups, groupSnapshots);
+  groupDTOs.forEach(g => {
+    // Assign draft state
+    const draftState = groupDraftDeletedStates.get(g.persistentId) ?? groupDraftStates.get(g.persistentId);
+    draftState && (g.draftState = draftState);
+
+    // Assign publish metadata
+    const publishMetadata = groupPublishedMetadata.get(g.persistentId);
+    publishMetadata && (g.publishMetadata = publishMetadata);
+
+    const approvalState = groupApprovalStates.get(g.persistentId);
+    approvalState && (g.approvalState = approvalState);
+  });
+
+  return {
+    hasPublishedDocumentationContent,
+    pages: pageDTOs,
+    groups: groupDTOs,
+  };
+}
+
+function getDeletedPages(pages: DocsPage[], pageSnapshots: DocumentationPageSnapshot[]): DocsPage[] {
+  const existingPagePersistentIds = new Set(pages.map(p => p.persistentId));
+  const latestSnapshots = pickLatestPageSnapshots(pageSnapshots);
+  return latestSnapshots.filter(s => !existingPagePersistentIds.has(s.page.persistentId)).map(s => s.page);
+}
+
+function getDeletedGroups(groups: DocsPageGroup[], groupSnapshots: ElementGroupSnapshot[]): DocsPageGroup[] {
+  const existingGroupPersistentIds = new Set(groups.map(p => p.persistentId));
+  const latestSnapshots = pickLatestGroupSnapshots(groupSnapshots);
+  return latestSnapshots.filter(s => !existingGroupPersistentIds.has(s.group.persistentId)).map(s => s.group);
+}
+
+function buildPageDraftCreatedAndUpdatedStates(
+  pages: DocsPage[],
+  pageSnapshots: DocumentationPageSnapshot[],
+  pageHashes: Record<string, string>,
+  debug: boolean
+): Map<string, DTODocumentationDraftState> {
+  // Read room data
+  const publishedSnapshots = pickLatestPageSnapshots(pageSnapshots.filter(s => s.reason === "Publish"));
+  const publishedSnapshotsByPagePersistentId = mapByUnique(publishedSnapshots, s => s.page.persistentId);
+
+  const result = new Map<string, DTODocumentationDraftState>();
+
+  pages.forEach(page => {
+    // Published state
+    const snapshot = publishedSnapshotsByPagePersistentId.get(page.persistentId);
+    let publishedState: ItemState | undefined;
+    if (snapshot) {
+      publishedState = itemStateFromPage(snapshot.page, snapshot.pageContentHash);
+    }
+
+    // Current state - if content hash is undefined, it means that the page hasn't changed
+    const currentPageContentHash = pageHashes[page.persistentId] ?? snapshot?.pageContentHash ?? "";
+    const currentState: ItemState = itemStateFromPage(page, currentPageContentHash);
+
+    // Calculate draft
+    const draftState = createDraftState(page.persistentId, currentState, publishedState, debug);
+    if (draftState) result.set(page.persistentId, draftState);
+  });
+
+  return result;
+}
+
+function itemStateFromPage(page: DocsPage, pageContentHash: string): ItemState {
+  return {
+    title: page.meta.name,
+    configuration: page.data.configuration ?? defaultDocumentationItemConfigurationV2,
+    contentHash: pageContentHash,
+  };
+}
+
+function buildPagePublishedMetadata(
+  pages: DocsPage[],
+  pageSnapshots: DocumentationPageSnapshot[]
+): Map<string, DTODocumentationPublishMetadata> {
+  const publishedPageSnapshotsByPersistentId = mapByUnique(
+    pickLatestPageSnapshots(pageSnapshots.filter(s => s.reason === "Publish")),
+    s => s.page.persistentId
+  );
+
+  const result = new Map<string, DTODocumentationPublishMetadata>();
+
+  pages.forEach(p => {
+    const publishedSnapshot = publishedPageSnapshotsByPersistentId.get(p.persistentId);
+    if (!publishedSnapshot) return;
+
+    result.set(p.persistentId, {
+      lastPublishedAt: publishedSnapshot.createdAt,
+      lastPublishedByUserId: publishedSnapshot.createdByUserId,
+    });
+  });
+
+  return result;
+}
+
+function createDraftState(
+  itemPersistentId: string,
+  currentState: ItemState,
+  publishedState: ItemState | undefined,
+  debug: boolean
+): DTODocumentationDraftState | undefined {
+  if (!publishedState) {
+    // New item (hasn't been published yet)
+    return { changeType: "Created" };
+  }
+
+  // Compare current item state to the published state
+  const updatedDraftState: DTODocumentationDraftStateUpdated = {
+    changeType: "Updated",
+    changes: {},
+  };
+
+  if (currentState.title !== publishedState.title) {
+    if (debug) {
+      console.log(`Item ${itemPersistentId} (${currentState.title}): updated title`);
+    }
+
+    updatedDraftState.changes.previousTitle = publishedState.title;
+  }
+
+  const currentConfigHash = generateHash(currentState.configuration, debug);
+  const publishedConfigHash = generateHash(publishedState.configuration, debug);
+
+  if (currentConfigHash !== publishedConfigHash) {
+    if (debug) {
+      console.log(`Item ${itemPersistentId} (${currentState.title}): updated configuration`);
+    }
+
+    const configurationDto = documentationItemConfigurationToDTOV2(publishedState.configuration);
+    updatedDraftState.changes.previousConfiguration = configurationDto;
+  }
+
+  if (currentState.contentHash !== publishedState.contentHash) {
+    if (debug) {
+      console.log(`Item ${itemPersistentId} (${currentState.title}): updated content hash`);
+    }
+
+    updatedDraftState.changes.previousContentHash = publishedState.contentHash;
+  }
+
+  if (Object.keys(updatedDraftState.changes).length) {
+    // Item has at least one of the draft changes
+    return updatedDraftState;
+  }
+
+  // Item has no draft changes compared to the published item
+  return undefined;
+}
+
+function buildGroupApprovalStates(groups: DocsPageGroup[], groupSnapshots: ElementGroupSnapshot[]) {
+  const result = new Map<string, DTODocumentationGroupApprovalState>();
+  const allGroups = [...groups, ...groupSnapshots];
+  for (const g of allGroups) {
+    const approvalState: DTODocumentationGroupApprovalState = {
+      approvalState: "Approved",
+      designSystemVersionId: g.designSystemVersionId,
+      persistentId: g.persistentId,
+      groupPersistentId: g.persistentId,
+    };
+    result.set(g.persistentId, approvalState);
+  }
+  return result;
+}
+
+function buildPageDraftDeletedStates(
+  pages: DocsPage[],
+  pageSnapshots: DocumentationPageSnapshot[]
+): Map<string, DTODocumentationDraftState> {
+  const deletedSnapshotsByPagePersistentId = mapByUnique(
+    pickLatestPageSnapshots(pageSnapshots.filter(s => s.reason === "Deletion")),
+    s => s.page.persistentId
+  );
+
+  const result = new Map<string, DTODocumentationDraftState>();
+
+  pages.forEach(page => {
+    const deletedSnapshot = deletedSnapshotsByPagePersistentId.get(page.persistentId);
+    if (!deletedSnapshot) return;
+
+    result.set(page.persistentId, {
+      changeType: "Deleted",
+      deletedAt: deletedSnapshot.createdAt,
+      deletedByUserId: deletedSnapshot.createdByUserId,
+    });
+  });
+
+  return result;
+}
+
+function buildGroupDraftDeletedStates(
+  groups: DocsPageGroup[],
+  groupSnapshots: ElementGroupSnapshot[]
+): Map<string, DTODocumentationDraftState> {
+  const deletedSnapshotsByGroupPersistentId = mapByUnique(
+    pickLatestGroupSnapshots(groupSnapshots.filter(s => s.reason === "Deletion")),
+    s => s.group.persistentId
+  );
+
+  const result = new Map<string, DTODocumentationDraftState>();
+
+  groups.forEach(group => {
+    if (!group.parentPersistentId) return;
+
+    const deletedSnapshot = deletedSnapshotsByGroupPersistentId.get(group.persistentId);
+    if (!deletedSnapshot) return;
+
+    result.set(group.persistentId, {
+      changeType: "Deleted",
+      deletedAt: deletedSnapshot.createdAt,
+      deletedByUserId: deletedSnapshot.createdByUserId,
+    });
+  });
+
+  return result;
+}
+
+function buildGroupDraftCreatedAndUpdatedStates(
+  groups: DocsPageGroup[],
+  groupSnapshots: ElementGroupSnapshot[],
+  debug: boolean
+): Map<string, DTODocumentationDraftState> {
+  // Read room data
+  const publishedSnapshots = pickLatestGroupSnapshots(groupSnapshots.filter(s => s.reason === "Publish"));
+  const publishedSnapshotsByGroupPersistent = mapByUnique(publishedSnapshots, s => s.group.persistentId);
+
+  const result = new Map<string, DTODocumentationDraftState>();
+
+  groups.forEach(group => {
+    if (!group.parentPersistentId) return;
+
+    // Current state
+    const currentState: ItemState = itemStateFromGroup(group);
+
+    // Published state
+    const snapshot = publishedSnapshotsByGroupPersistent.get(group.persistentId);
+    let publishedState: ItemState | undefined;
+    if (snapshot) {
+      publishedState = itemStateFromGroup(snapshot.group);
+    }
+
+    // Calculate draft
+    const draftState = createDraftState(group.persistentId, currentState, publishedState, debug);
+    if (draftState) result.set(group.persistentId, draftState);
+  });
+
+  return result;
+}
+
+function itemStateFromGroup(group: DocsPageGroup): ItemState {
+  return {
+    title: group.meta.name,
+    configuration: group.data?.configuration ?? defaultDocumentationItemConfigurationV2,
+    contentHash: "-",
+  };
+}
+
+function buildGroupPublishedMetadata(
+  groups: DocsPageGroup[],
+  groupSnapshots: ElementGroupSnapshot[]
+): Map<string, DTODocumentationPublishMetadata> {
+  const publishedGroupSnapshotsByPersistentId = mapByUnique(
+    pickLatestGroupSnapshots(groupSnapshots.filter(s => s.reason === "Publish")),
+    s => s.group.persistentId
+  );
+
+  const result = new Map<string, DTODocumentationPublishMetadata>();
+
+  groups.forEach(g => {
+    if (!g.parentPersistentId) return;
+
+    const publishedSnapshot = publishedGroupSnapshotsByPersistentId.get(g.persistentId);
+    if (!publishedSnapshot) return;
+
+    result.set(g.persistentId, {
+      lastPublishedAt: publishedSnapshot.createdAt,
+      lastPublishedByUserId: publishedSnapshot.createdByUserId,
+    });
+  });
+
+  return result;
+}

package/src/yjs/version-room/frontend.ts

@@ -0,0 +1,76 @@
+import { PageBlockDefinition } from "@supernova-studio/model";
+import * as Y from "yjs";
+import { DTODocumentationHierarchyV2 } from "../../api";
+import { DocumentationPageEditorModel } from "../docs-editor";
+import { VersionRoomBaseYDoc } from "./base";
+import { computeDocsHierarchy } from "./compute-dto";
+import { generatePageContentHash } from "./utils";
+
+export class FrontendVersionRoomYDoc {
+  private readonly yDoc: Y.Doc;
+
+  constructor(yDoc: Y.Doc, private readonly debug = false) {
+    this.yDoc = yDoc;
+  }
+
+  //
+  // Hierarchy
+  //
+
+  getDocumentationHierarchy(
+    options: { includeDeletedContent?: boolean; debug?: boolean } = {}
+  ): DTODocumentationHierarchyV2 {
+    const doc = new VersionRoomBaseYDoc(this.yDoc);
+    return computeDocsHierarchy(doc.getState(), options);
+  }
+
+  //
+  // Update page content hash
+  //
+
+  notifyDocumentationPageContentUpdated(
+    pageId: string,
+    content: DocumentationPageEditorModel,
+    definitions: PageBlockDefinition[]
+  ) {
+    const pageContentHash = generatePageContentHash(content, definitions, this.debug);
+    if (this.debug) {
+      console.log(`Will set page content hash: '${pageId}' : '${pageContentHash}'`);
+    }
+
+    new VersionRoomBaseYDoc(this.yDoc).updateDocumentationPageContentHashes({
+      [pageId]: pageContentHash,
+    });
+  }
+
+  //
+  // Misc
+  //
+
+  isDraftFeatureAdopted() {
+    const doc = new VersionRoomBaseYDoc(this.yDoc);
+    const settings = doc.getDocumentationInternalSettings();
+    return settings.isDraftFeatureAdopted;
+  }
+
+  hasPublishedDocumentationContent() {
+    const doc = new VersionRoomBaseYDoc(this.yDoc);
+
+    return (
+      doc.getPageSnapshots().filter(s => s.reason === "Publish").length > 0 ||
+      doc.getGroupSnapshots().filter(s => s.reason === "Publish").length > 0
+    );
+  }
+
+  isApprovalsFeatureEnabled() {
+    const doc = new VersionRoomBaseYDoc(this.yDoc);
+    const settings = doc.getDocumentationInternalSettings();
+    return settings.isApprovalFeatureEnabled;
+  }
+
+  isApprovalRequiredForPublishing() {
+    const doc = new VersionRoomBaseYDoc(this.yDoc);
+    const settings = doc.getDocumentationInternalSettings();
+    return settings.approvalRequiredForPublishing;
+  }
+}

package/src/yjs/version-room/index.ts

@@ -0,0 +1,6 @@
+export * from "./backend";
+export * from "./base";
+export * from "./compute-dto";
+export * from "./frontend";
+export * from "./types";
+export * from "./utils";

package/src/yjs/version-room/types.ts

@@ -0,0 +1,31 @@
+import {
+  DocumentationPageApproval,
+  DocumentationPageSnapshot,
+  DocumentationPageV2,
+  ElementGroup,
+  ElementGroupSnapshot,
+} from "@supernova-studio/model";
+import { DocumentationHierarchySettings } from "../design-system-content";
+
+export type VersionRoomDocsPage = DocumentationPageV2;
+export type VersionRoomDocsPageGroup = ElementGroup;
+export type VersionRoomApproval = DocumentationPageApproval;
+
+export type VersionRoomBaseYDocState = {
+  isLoaded: boolean;
+
+  pages: VersionRoomDocsPage[];
+  pageSnapshots: DocumentationPageSnapshot[];
+  pageContentHashes: Record<string, string>;
+  pageLiveblockRoomIds: Record<string, string>;
+
+  groups: VersionRoomDocsPageGroup[];
+  groupSnapshots: ElementGroupSnapshot[];
+
+  approvals: DocumentationPageApproval[];
+  settings: DocumentationHierarchySettings;
+
+  executedTransactionIds: string[];
+
+  storageVersion: number;
+};

package/src/yjs/version-room/utils.ts

@@ -0,0 +1,109 @@
+import {
+  PageBlockDefinition,
+  PageBlockDefinitionsMap,
+  PageBlockItemMultiRichTextValue,
+  PageBlockItemRichTextValue,
+  PageBlockItemTableValue,
+  PageBlockText,
+  mapPageBlockItemValuesV2,
+  removeCommentSpans,
+} from "@supernova-studio/model";
+import { generateHash } from "../../utils";
+import { DocumentationPageEditorModel } from "../docs-editor";
+
+export function generatePageContentHash(
+  content: DocumentationPageEditorModel,
+  definitions: PageBlockDefinition[],
+  debug = false
+) {
+  let sanitizedContent = structuredClone(content);
+
+  // Remove comment spans
+  sanitizedContent = sanitizePageContents(sanitizedContent, definitions);
+
+  // Make sure hashes of empty pages always match
+  if (isPageContentEmpty(sanitizedContent)) {
+    sanitizedContent = { blocks: [] };
+  }
+
+  return generateHash(sanitizedContent, debug);
+}
+
+/**
+ * Empty page content can be one of the following:
+ *   - page without any blocks
+ *   - page with a single block, the block is a paragraph whithout any text
+ */
+function isPageContentEmpty(content: DocumentationPageEditorModel): boolean {
+  if (content.blocks.length > 1) return false;
+  if (content.blocks.length < 1) return true;
+
+  const singleBlock = content.blocks[0];
+  if (singleBlock.type !== "Block" || singleBlock.data.packageId !== "io.supernova.block.rich-text") {
+    return false;
+  }
+
+  const singleItem = singleBlock.data.items[0];
+
+  // Block has no value, effectively the same as empty value
+  if (!singleItem || !singleItem.props["text"]) return true;
+
+  const textValue = singleItem.props["text"] as PageBlockItemRichTextValue;
+  return !textValue.value.spans.length;
+}
+
+function sanitizePageContents(
+  content: DocumentationPageEditorModel,
+  definitions: PageBlockDefinition[]
+): DocumentationPageEditorModel {
+  const defMap = new PageBlockDefinitionsMap(definitions);
+
+  mapPageBlockItemValuesV2(content.blocks, defMap, (block, item, prop, value) => {
+    if (prop.type === "RichText") {
+      const richTextValue = value as PageBlockItemRichTextValue;
+      return {
+        ...richTextValue,
+        value: sanitizeRichText(richTextValue.value),
+      };
+    }
+
+    if (prop.type === "MultiRichText") {
+      const multiRichTextValue = value as PageBlockItemMultiRichTextValue;
+      return {
+        ...multiRichTextValue,
+        value: multiRichTextValue.value.map(sanitizeRichText),
+      };
+    }
+
+    if (prop.type === "Table") {
+      const tableValue = value as PageBlockItemTableValue;
+      tableValue.value.forEach(r => {
+        r.cells.forEach(c => {
+          c.nodes.forEach(n => {
+            if (n.type === "RichText") {
+              n.value = sanitizeRichText(n.value);
+            }
+          });
+        });
+      });
+
+      return tableValue;
+    }
+
+    return value;
+  });
+
+  return content;
+}
+
+function sanitizeRichText(richText: PageBlockText): PageBlockText {
+  return sortSpanAttributes(removeCommentSpans(richText));
+}
+
+function sortSpanAttributes(richText: PageBlockText) {
+  richText.spans.forEach(s => {
+    s.attributes.sort((lhs, rhs) => lhs.type.localeCompare(rhs.type));
+  });
+
+  return richText;
+}