@supernova-studio/client 1.96.6 → 1.96.7

package/src/sync/docs-local-action-executor.ts

@@ -0,0 +1,412 @@
+import {
+  defaultDocumentationItemConfigurationV2,
+  generateShortPersistentId,
+  mapByUnique,
+  RoomType,
+  slugify,
+} from "@supernova-studio/model";
+import { DTOElementActionInput, DTOElementActionInputOfType } from "../api";
+import { VersionRoomApproval, VersionRoomBaseYDocState, VersionRoomDocsPage, VersionRoomDocsPageGroup } from "../yjs";
+import { LocalApproval, LocalDocsPage, LocalDocsPageGroup } from "./types";
+
+//
+// Types
+//
+
+type Page = LocalDocsPage | VersionRoomDocsPage;
+type Group = LocalDocsPageGroup | VersionRoomDocsPageGroup;
+type ApprovalState = LocalApproval | VersionRoomApproval;
+
+//
+// Interface
+//
+
+type Input = LocalExecutorConfig & {
+  actions: DTOElementActionInput[];
+};
+
+export function applyActionsLocally(input: Input) {
+  const actionExecutor = new LocalDocsElementActionExecutor(input);
+  actionExecutor.applyActions(input.actions);
+  return actionExecutor.localState;
+}
+
+//
+// Executor
+//
+
+type LocalExecutorConfig = {
+  userId: string;
+  designSystemVersionId: string;
+  remoteState: VersionRoomBaseYDocState;
+};
+
+export class LocalDocsElementActionExecutor {
+  private readonly userId: string;
+  private readonly designSystemVersionId: string;
+
+  private readonly pages: Map<string, Page>;
+  private readonly groups: Map<string, Group>;
+  private readonly approvalStates: Map<string, ApprovalState>;
+  private readonly pageLiveblockRoomIds: Record<string, string>;
+
+  constructor(config: LocalExecutorConfig) {
+    const { designSystemVersionId, remoteState, userId } = config;
+
+    this.userId = userId;
+    this.designSystemVersionId = designSystemVersionId;
+
+    // Seed the state with remote state
+    this.pages = mapByUnique(remoteState.pages, p => p.persistentId);
+    this.groups = mapByUnique(remoteState.groups, p => p.persistentId);
+    this.approvalStates = mapByUnique(remoteState.approvals, a => a.pagePersistentId);
+    this.pageLiveblockRoomIds = { ...remoteState.pageLiveblockRoomIds };
+  }
+
+  get localState() {
+    return {
+      pages: Array.from(this.pages.values()),
+      groups: Array.from(this.groups.values()),
+      approvals: Array.from(this.approvalStates.values()),
+      pageLiveblockRoomIds: this.pageLiveblockRoomIds,
+    };
+  }
+
+  applyActions(trx: DTOElementActionInput[]) {
+    trx.forEach(trx => this.applyTransaction(trx));
+  }
+
+  applyTransaction(trx: DTOElementActionInput) {
+    switch (trx.type) {
+      // Groups
+      case "DocumentationGroupCreate":
+        return this.documentationGroupCreate(trx);
+      case "DocumentationGroupUpdate":
+        return this.documentationGroupUpdate(trx);
+      case "DocumentationGroupMove":
+        return this.documentationGroupMove(trx);
+
+      // Groups - unsupported
+      case "DocumentationGroupDelete":
+      case "DocumentationGroupDuplicate":
+      case "DocumentationGroupRestore":
+        throw new Error(`Transaction type ${trx.type} is not yet implemented`);
+
+      // Pages
+      case "DocumentationPageCreate":
+        return this.documentationPageCreate(trx);
+      case "DocumentationPageUpdate":
+        return this.documentationPageUpdate(trx);
+      case "DocumentationPageMove":
+        return this.documentationPageMove(trx);
+      case "DocumentationPageDelete":
+        return this.documentationPageDelete(trx);
+
+      // Pages - unsupported
+      case "DocumentationPageApprovalStateChange":
+        return this.documentationApprovalStateUpdate(trx);
+
+      case "DocumentationPageDuplicate":
+      case "DocumentationPageRestore":
+        throw new Error(`Transaction type ${trx.type} is not yet implemented`);
+
+      // Tabs
+      case "DocumentationTabCreate":
+        return this.documentationTabCreate(trx);
+
+      case "DocumentationTabGroupDelete":
+        throw new Error(`Transaction type ${trx.type} is not yet implemented`);
+
+      // Won't ever be supported
+      case "FigmaNodeRenderAsync":
+        throw new Error(`Transaction type ${trx.type} is not a documentation element action`);
+    }
+  }
+
+  //
+  // Pages
+  //
+
+  private documentationPageCreate(trx: DTOElementActionInputOfType<"DocumentationPageCreate">) {
+    const { input } = trx;
+    const { persistentId } = input;
+
+    if (this.pages.has(input.persistentId)) {
+      // TODO Artem: uncomment when this is synced with remote state
+      // throw new Error(`Cannot create page: persistent id ${input.persistentId} already exists`);
+      return;
+    }
+
+    if (!this.groups.has(input.parentPersistentId)) {
+      throw new Error(`Cannot create page: parent persistent id ${input.parentPersistentId} was not found`);
+    }
+
+    const localPage: LocalDocsPage = {
+      persistentId,
+      createdAt: new Date(),
+      parentPersistentId: input.parentPersistentId,
+      shortPersistentId: generateShortPersistentId(),
+      slug: slugify(input.title),
+      meta: { name: input.title },
+      updatedAt: new Date(),
+      data: {
+        // TODO Artem: move somewhere reusable
+        configuration: input.configuration
+          ? { ...defaultDocumentationItemConfigurationV2, ...input.configuration }
+          : input.configuration,
+      },
+      sortOrder: this.calculateSortOrder(input.parentPersistentId, input.afterPersistentId),
+      designSystemVersionId: this.designSystemVersionId,
+    };
+
+    this.pages.set(persistentId, localPage);
+
+    const roomId = `${RoomType.DocumentationPage}:${this.designSystemVersionId}:${persistentId}`;
+    this.pageLiveblockRoomIds[persistentId] = roomId;
+  }
+
+  private documentationPageUpdate(trx: DTOElementActionInputOfType<"DocumentationPageUpdate">) {
+    const { input } = trx;
+
+    const existingPage = this.pages.get(input.id);
+    if (!existingPage) {
+      throw new Error(`Cannot update page: page id ${input.id} was not found`);
+    }
+
+    const localPage: LocalDocsPage = {
+      ...existingPage,
+      userSlug: undefined,
+      meta: {
+        ...existingPage.meta,
+        name: input.title ?? existingPage.meta.name,
+      },
+      data: {
+        // TODO Artem: move somewhere reusable
+        configuration: input.configuration
+          ? { ...(existingPage.data.configuration ?? defaultDocumentationItemConfigurationV2), ...input.configuration }
+          : existingPage.data.configuration,
+      },
+    };
+
+    this.pages.set(localPage.persistentId, localPage);
+  }
+
+  private documentationPageMove(trx: DTOElementActionInputOfType<"DocumentationPageMove">) {
+    const { input } = trx;
+
+    if (!this.groups.has(input.parentPersistentId)) {
+      throw new Error(`Cannot move page: page parent id ${input.parentPersistentId} was not found`);
+    }
+
+    const existingPage = this.pages.get(input.id);
+    if (!existingPage) {
+      throw new Error(`Cannot update page: page id ${input.id} was not found`);
+    }
+
+    const localPage: LocalDocsPage = {
+      ...existingPage,
+      userSlug: undefined,
+      sortOrder: this.calculateSortOrder(input.parentPersistentId, input.afterPersistentId),
+      parentPersistentId: input.parentPersistentId,
+    };
+
+    this.pages.set(localPage.persistentId, localPage);
+  }
+
+  private documentationPageDelete(trx: DTOElementActionInputOfType<"DocumentationPageDelete">) {
+    const { input } = trx;
+
+    if (!this.pages.delete(trx.input.id)) {
+      throw new Error(`Cannot delete page: page id ${input.id} was not found`);
+    }
+
+    delete this.pageLiveblockRoomIds[trx.input.id];
+  }
+
+  //
+  // Group
+  //
+
+  private documentationGroupCreate(trx: DTOElementActionInputOfType<"DocumentationGroupCreate">) {
+    const { input } = trx;
+
+    if (this.groups.has(input.persistentId)) {
+      // TODO Artem: uncomment when this is synced with remote state
+      // throw new Error(`Cannot create page: persistent id ${input.persistentId} already exists`);
+      return;
+    }
+
+    const localGroup: LocalDocsPageGroup = {
+      parentPersistentId: input.parentPersistentId,
+      persistentId: input.persistentId,
+      shortPersistentId: generateShortPersistentId(),
+      slug: slugify(input.title),
+      meta: { name: input.title },
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      data: {
+        // TODO Artem: move somewhere reusable
+        configuration: input.configuration
+          ? { ...defaultDocumentationItemConfigurationV2, ...input.configuration }
+          : input.configuration,
+      },
+      sortOrder: this.calculateSortOrder(input.parentPersistentId, input.afterPersistentId),
+      designSystemVersionId: this.designSystemVersionId,
+    };
+
+    this.groups.set(localGroup.persistentId, localGroup);
+  }
+
+  private documentationGroupUpdate(trx: DTOElementActionInputOfType<"DocumentationGroupUpdate">) {
+    const { input } = trx;
+
+    const existingGroup = this.groups.get(input.id);
+    if (!existingGroup) {
+      throw new Error(`Cannot update group: group id ${input.id} was not found`);
+    }
+
+    const localGroup: LocalDocsPageGroup = {
+      ...existingGroup,
+      userSlug: undefined,
+      meta: {
+        ...existingGroup.meta,
+        name: input.title ?? existingGroup.meta.name,
+      },
+      data: {
+        ...existingGroup.data,
+
+        // TODO Artem: move somewhere reusable
+        configuration: input.configuration
+          ? {
+              ...(existingGroup.data?.configuration ?? defaultDocumentationItemConfigurationV2),
+              ...input.configuration,
+            }
+          : existingGroup.data?.configuration,
+      },
+    };
+
+    this.groups.set(localGroup.persistentId, localGroup);
+  }
+
+  private documentationGroupMove(trx: DTOElementActionInputOfType<"DocumentationGroupMove">) {
+    const { input } = trx;
+
+    if (!this.groups.has(input.parentPersistentId)) {
+      throw new Error(`Cannot move group: group parent id ${input.parentPersistentId} was not found`);
+    }
+
+    const existingGroup = this.groups.get(input.id);
+    if (!existingGroup) {
+      throw new Error(`Cannot update group: group id ${input.id} was not found`);
+    }
+
+    const localGroup: LocalDocsPageGroup = {
+      ...existingGroup,
+      userSlug: undefined,
+      sortOrder: this.calculateSortOrder(input.parentPersistentId, input.afterPersistentId),
+      parentPersistentId: input.parentPersistentId,
+    };
+
+    this.groups.set(localGroup.persistentId, localGroup);
+  }
+
+  //
+  // Tabs
+  //
+
+  private documentationTabCreate(trx: DTOElementActionInputOfType<"DocumentationTabCreate">) {
+    const { input } = trx;
+
+    const page = this.pages.get(input.fromItemPersistentId);
+    if (!page) {
+      throw new Error(`Cannot create tab: page id ${input.fromItemPersistentId} was not found`);
+    }
+
+    // Create tab group in place of the page
+    const tabGroup: LocalDocsPageGroup = {
+      parentPersistentId: page.parentPersistentId,
+      persistentId: input.persistentId,
+      shortPersistentId: generateShortPersistentId(),
+      slug: page.slug,
+      meta: page.meta,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      data: {
+        behavior: "Tabs",
+        configuration: page?.data.configuration,
+      },
+      sortOrder: page.sortOrder,
+      designSystemVersionId: this.designSystemVersionId,
+    };
+    this.groups.set(input.persistentId, tabGroup);
+
+    const newLocalPage: LocalDocsPage = {
+      ...page,
+      userSlug: undefined,
+      sortOrder: 0,
+      parentPersistentId: input.persistentId,
+      meta: { name: input.tabName },
+    };
+    this.pages.set(newLocalPage.persistentId, newLocalPage);
+  }
+
+  //
+  // Approval states
+  //
+
+  private documentationApprovalStateUpdate(trx: DTOElementActionInputOfType<"DocumentationPageApprovalStateChange">) {
+    const { input } = trx;
+
+    const existingApproval = this.approvalStates.get(input.persistentId);
+
+    if (input.approvalState) {
+      this.approvalStates.set(input.persistentId, {
+        approvalState: input.approvalState,
+        createdAt: existingApproval?.createdAt ?? new Date(),
+        designSystemVersionId: this.designSystemVersionId,
+        pagePersistentId: input.persistentId,
+        updatedAt: new Date(),
+        updatedByUserId: this.userId,
+      } satisfies LocalApproval);
+    } else {
+      this.approvalStates.delete(input.persistentId);
+    }
+  }
+
+  //
+  // Utils
+  //
+
+  private calculateSortOrder(parentPersistentId: string, afterPersistentId?: string | null): number {
+    const sortOrderStep = Math.pow(2, 16);
+
+    const neighbours = [
+      ...Array.from(this.pages.values()).filter(p => p.parentPersistentId === parentPersistentId),
+      ...Array.from(this.groups.values()).filter(g => g.parentPersistentId === parentPersistentId),
+    ];
+
+    // If no neighbors, just assign 0
+    if (!neighbours.length) return 0;
+
+    neighbours.sort((lhs, rhs) => lhs.sortOrder - rhs.sortOrder);
+
+    // Null afterPersistentId means beginning
+    if (afterPersistentId === null) return neighbours[0].sortOrder - sortOrderStep;
+
+    // Undefined afterPersistentId means default behavior (end of the list)
+    if (!afterPersistentId) return neighbours[neighbours.length - 1].sortOrder + sortOrderStep;
+
+    const index = neighbours.findIndex(e => e.persistentId === afterPersistentId);
+
+    // If page is not found or adding after the last item is requested, assign last position
+    if (index < 0 || index === neighbours.length - 1) {
+      return neighbours[neighbours.length - 1].sortOrder + sortOrderStep;
+    }
+
+    // Insert in between items
+    const left = neighbours[index].sortOrder;
+    const right = neighbours[index + 1]?.sortOrder ?? left + sortOrderStep * 2;
+
+    return (right + left) / 2;
+  }
+}

package/src/sync/docs-structure-repo.ts

@@ -0,0 +1,283 @@
+import { OmitStrict } from "@supernova-studio/model";
+import PQueue from "p-queue";
+import * as Y from "yjs";
+import {
+  DTODocumentationHierarchyV2,
+  DTODocumentationSettings,
+  DTOElementActionInput,
+  DTOElementActionInputOfType,
+  DTOPageBlockDefinition,
+} from "../api";
+import { DocumentationPageEditorModel, generatePageContentHash, VersionRoomBaseYDoc } from "../yjs";
+import { computeDocsHierarchy } from "../yjs/version-room/compute-dto";
+import { VersionRoomBaseYDocState } from "../yjs/version-room/types";
+import { applyActionsLocally } from "./docs-local-action-executor";
+import { SupportedElementActionType } from "./types";
+
+type YObserver = () => void;
+type HierarchyObserver = (hierarchy: DTODocumentationHierarchyV2) => void;
+type SettingsObserver = (settings: DTODocumentationSettings) => void;
+type ErrorObserver<T> = (error: unknown, actionMetadata: T | undefined) => void;
+
+type TransactionExecutor = (trx: DTOElementActionInput) => Promise<void>;
+type InternalTransactionExecutor<T> = (trx: InternalAction<T>) => Promise<void>;
+type TransactionIdGenerator = () => string;
+
+type Action = DTOElementActionInputOfType<SupportedElementActionType>;
+type InputAction<T> = OmitStrict<Action, "tId">;
+type InternalAction<T> = { action: Action; metadata?: T };
+
+export class DocsStructureRepository<T> {
+  private userId: string;
+  private designSystemVersionId: string;
+
+  private readonly yDoc: Y.Doc;
+  private readonly yObserver: YObserver;
+  private _yState: VersionRoomBaseYDocState | undefined;
+
+  private _currentHierarchy: DTODocumentationHierarchyV2 | undefined;
+  private _currentSettings: DTODocumentationSettings | undefined;
+
+  private localActions: DTOElementActionInput[] = [];
+  private readonly actionQueue: TransactionQueue<T>;
+  private readonly hierarchyObservers = new Set<HierarchyObserver>();
+  private readonly settingsObservers = new Set<SettingsObserver>();
+  private readonly errorObservers = new Set<ErrorObserver<T>>();
+  private readonly initCallbacks = new Set<() => void>();
+
+  private readonly transactionIdGenerator: TransactionIdGenerator;
+  private readonly transactionExecutor: TransactionExecutor;
+
+  constructor(config: {
+    userId: string;
+    designSystemVersionId: string;
+    yDoc: Y.Doc;
+    transactionExecutor: TransactionExecutor;
+    transactionIdGenerator: TransactionIdGenerator;
+  }) {
+    this.userId = config.userId;
+    this.designSystemVersionId = config.designSystemVersionId;
+    this.yDoc = config.yDoc;
+
+    this.yObserver = this.yDoc.on("update", () => this.onYUpdate()) as YObserver;
+    this.onYUpdate();
+
+    this.transactionExecutor = config.transactionExecutor;
+    this.transactionIdGenerator = config.transactionIdGenerator;
+
+    this.actionQueue = new TransactionQueue(action => this.executeInternalAction(action));
+  }
+
+  //
+  // Lifecycle
+  //
+
+  get isInitialized(): boolean {
+    return !!this._currentHierarchy;
+  }
+
+  onInitialized(): Promise<void> {
+    if (this.isInitialized) return Promise.resolve();
+    return new Promise(resolve => {
+      this.initCallbacks.add(resolve);
+    });
+  }
+
+  addHierarchyObserver(observer: HierarchyObserver) {
+    this.hierarchyObservers.add(observer);
+    if (this._currentHierarchy) observer(this._currentHierarchy);
+  }
+
+  removeHierarchyObserver(observer: HierarchyObserver) {
+    this.hierarchyObservers.delete(observer);
+  }
+
+  addSettingsObserver(observer: SettingsObserver) {
+    this.settingsObservers.add(observer);
+    if (this._currentSettings) observer(this._currentSettings);
+  }
+
+  removeSettingsObserver(observer: SettingsObserver) {
+    this.settingsObservers.delete(observer);
+  }
+
+  addErrorObserver(observer: ErrorObserver<T>) {
+    this.errorObservers.add(observer);
+  }
+
+  removeErrorObserver(observer: ErrorObserver<T>) {
+    this.errorObservers.delete(observer);
+  }
+
+  dispose() {
+    this.yDoc.off("update", this.yObserver);
+    this.hierarchyObservers.clear();
+    this.settingsObservers.clear();
+    this.errorObservers.clear();
+    this.actionQueue.clear();
+  }
+
+  //
+  // Accessors
+  //
+
+  get currentHierarchy(): DTODocumentationHierarchyV2 {
+    const hierarchy = this._currentHierarchy;
+    if (!hierarchy) throw new Error(`Hierarchy cannot be accessed while it's still loading`);
+    return hierarchy;
+  }
+
+  //
+  // Actions
+  //
+
+  executeAction(action: InputAction<T>, metadata?: T) {
+    void this.executeActionPromise(action, metadata);
+  }
+
+  executeActionPromise(action: InputAction<T>, metadata?: T) {
+    const fullAction: DTOElementActionInput = { ...action, tId: this.transactionIdGenerator() };
+    this.localActions.push(fullAction);
+    this.refreshHierarchy();
+    return this.actionQueue.enqueue({ action: fullAction, metadata });
+  }
+
+  notifyPageContentUpdated(
+    pagePersistentId: string,
+    content: DocumentationPageEditorModel,
+    definitions: DTOPageBlockDefinition[]
+  ) {
+    const pageContentHash = generatePageContentHash(content, definitions);
+    new VersionRoomBaseYDoc(this.yDoc).updateDocumentationPageContentHashes({
+      [pagePersistentId]: pageContentHash,
+    });
+  }
+
+  private async executeInternalAction(action: InternalAction<T>) {
+    try {
+      return await this.transactionExecutor(action.action);
+    } catch (e: unknown) {
+      // Remove this action from local actions and reload hierarchy
+      this.localActions = this.localActions.filter(a => a.tId !== action.action.tId);
+      this.refreshHierarchy();
+
+      this.errorObservers.forEach(o => o(e, action.metadata));
+    }
+  }
+
+  //
+  // Reactions
+  //
+
+  private refreshState() {
+    this.refreshHierarchy();
+    this.refreshSettings();
+  }
+
+  private refreshSettings() {
+    const yState = this._yState;
+    if (!yState) return;
+
+    // Calculate new settings
+    const newSettings: DTODocumentationSettings = {
+      isApprovalRequiredForPublishing: yState.settings.approvalRequiredForPublishing,
+      isApprovalsFeatureEnabled: yState.settings.isApprovalFeatureEnabled,
+      isDraftFeatureAdopted: yState.settings.isDraftFeatureAdopted,
+    };
+
+    // Only invoke when changed
+    if (
+      !this._currentSettings ||
+      newSettings.isApprovalRequiredForPublishing !== this._currentSettings.isApprovalRequiredForPublishing ||
+      newSettings.isApprovalsFeatureEnabled !== this._currentSettings.isApprovalsFeatureEnabled ||
+      newSettings.isDraftFeatureAdopted !== this._currentSettings.isDraftFeatureAdopted
+    ) {
+      this._currentSettings = newSettings;
+
+      // Invoke observers
+      this.settingsObservers.forEach(o => o(newSettings));
+    }
+  }
+
+  private refreshHierarchy() {
+    const yState = this._yState;
+    if (!yState) return;
+
+    // Calculate new hierarchy
+    const hierarchy = this.calculateHierarchy(yState);
+    if (!hierarchy) return;
+    this._currentHierarchy = hierarchy;
+
+    // Invoke observers
+    this.hierarchyObservers.forEach(o => o(hierarchy));
+  }
+
+  private calculateHierarchy(yState: VersionRoomBaseYDocState) {
+    // Remove local actions that have been applied remotely
+    const executedTransactionIds = new Set(yState.executedTransactionIds);
+    const localActions = this.localActions.filter(a => a.tId && !executedTransactionIds.has(a.tId));
+    this.localActions = localActions;
+
+    // Apply local actions onto the Yjs state
+    const { pages, groups, approvals, pageLiveblockRoomIds } = applyActionsLocally({
+      userId: this.userId,
+      designSystemVersionId: this.designSystemVersionId,
+      remoteState: yState,
+      actions: localActions,
+    });
+
+    const hierarchy = computeDocsHierarchy(
+      {
+        // Merged remote + local
+        pages,
+        groups,
+        approvals,
+        pageLiveblockRoomIds,
+
+        // Remote only
+        groupSnapshots: yState.groupSnapshots,
+        pageContentHashes: yState.pageContentHashes,
+        pageSnapshots: yState.pageSnapshots,
+        settings: yState.settings,
+      },
+      { includeDeletedContent: true }
+    );
+
+    return hierarchy;
+  }
+
+  private onYUpdate() {
+    const newState = new VersionRoomBaseYDoc(this.yDoc).getState();
+    if (newState.groups.length) {
+      this._yState = newState;
+      this.refreshState();
+
+      // Flush init callbacks
+      this.initCallbacks.forEach(f => f());
+      this.initCallbacks.clear();
+    }
+  }
+}
+
+class TransactionQueue<T> {
+  private readonly executor: InternalTransactionExecutor<T>;
+  private readonly queue = new PQueue({
+    concurrency: 1,
+  });
+
+  constructor(executor: InternalTransactionExecutor<T>) {
+    this.executor = executor;
+  }
+
+  enqueue(trx: InternalAction<T>) {
+    return this.queue.add(() => this.executor(trx));
+  }
+
+  onEmpty() {
+    return this.queue.onEmpty();
+  }
+
+  clear() {
+    this.queue.clear();
+  }
+}

package/src/sync/index.ts

@@ -0,0 +1,5 @@
+export * from "./docs-local-action-executor";
+export * from "./docs-structure-repo";
+export * from "./project-content-repo";
+export * from "./project-local-action-executor";
+export * from "./types";