@thatopen/services 0.5.0 → 0.6.0

package/src/built-in/UIManager/src/git-history-panel/example.ts

@@ -0,0 +1,70 @@
+/* MD
+  ## git-history-panel
+  ---
+  `top-git-history` is a GitKraken-style commit timeline for the **revit-flow**
+  feature. It lists the commits pushed by the Revit add-in (newest first) and,
+  when you click a commit, drives the shared 3D viewer to color that commit's
+  changed elements — created green, modified blue, deleted red — on the loaded
+  baseline model.
+
+  All viewer mutation lives in the headless `GitHistoryManager`; the panel is
+  intent-only. Mounting it is a single line of markup once `UIManager` and
+  `GitHistoryManager` are in the setup call.
+*/
+
+import { html } from "lit";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient, UIManager, GitHistoryManager } from "@thatopen/services";
+import type { App } from "../app/index";
+
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+  { uuid: GitHistoryManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// The panel self-wires init(client) on connect, but calling it here keeps the
+// timeline populated before the panel mounts.
+await components.get(GitHistoryManager).init(client);
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  waitUntil(
+    (async () => {
+      const fragments = components.get(OBC.FragmentsManager);
+      const workerUrl = await FRAGS.FragmentsModels.getWorker();
+      fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+    })(),
+    "Fragments Core",
+  );
+  return { components, client };
+};
+
+app.elements = {
+  viewer: () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+  history: () => html`<top-git-history></top-git-history>`,
+};
+
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:branching-paths-up-bold",
+    template: `"viewer history" 1fr / 1fr 24rem`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";

package/src/built-in/index.ts

@@ -949,6 +949,191 @@ export type FileList = InstanceType<typeof _FileList>;
  */
 export const FileList = { uuid: 'b0b5e2a2-0b3a-4a6b-8b1c-0b1c4a6b8b1c' } as typeof _FileList & { uuid: 'b0b5e2a2-0b3a-4a6b-8b1c-0b1c4a6b8b1c' };
 
+/** One element mutation inside a revit-flow commit. */
+export interface RevitFlowChange {
+    /** create → element added, update → geometry/data changed, delete → removed. */
+    type: "create" | "update" | "delete" | string;
+    /** Revit UniqueId (GUID). Resolves to a fragments localId via getLocalIdsByGuids. */
+    uniqueId: string;
+}
+/** Per-commit change tallies, mirrored from the add-in's `counts` block. */
+export interface RevitFlowCounts {
+    added: number;
+    modified: number;
+    removed: number;
+}
+/**
+ * A revit-flow commit — one push of changes from the Revit add-in. `id` is a
+ * monotonic integer; `parent` points at the previous commit (null for the
+ * root). The commit whose scan was full (earliest with a .frag) carries the
+ * WHOLE model in `revitflow_frag_<id>.frag`; later frags are incremental.
+ */
+export interface RevitFlowCommit {
+    id: number;
+    parent: number | null;
+    author: string;
+    source: string;
+    timestamp: string;
+    changes: RevitFlowChange[];
+    counts: RevitFlowCounts;
+}
+/** Shape of `revitflow_history.json`. */
+export interface RevitFlowHistory {
+    model: string;
+    commits: RevitFlowCommit[];
+}
+/** Dominant change type of a commit, used to color its timeline node. */
+export type DominantChange = "create" | "update" | "delete";
+
+/** Dominant change type of a commit: delete → create → update. */
+export declare function dominantChange(commit: RevitFlowCommit): DominantChange;
+/**
+ * GitHistoryManager — headless engine for the revit-flow git-history built-in.
+ *
+ * Owns ALL viewer mutation: it fetches the commit history + fragment artifacts
+ * from project storage, loads the baseline (full-model) .frag into the shared
+ * viewer, and colors a commit's changed elements (create → green, update →
+ * blue, delete → red) via named Highlighter styles. The Lit panel
+ * (`top-git-history`) is intent-only: it calls these methods and subscribes to
+ * the events below, and never touches the Highlighter / FragmentsManager
+ * directly.
+ *
+ * Data model (per model, in `bimterop/revit-<docId>/`):
+ *   - revitflow_history.json — { model, commits: [{ id, parent, author,
+ *       source, timestamp, changes:[{type,uniqueId}], counts }] }
+ *   - revitflow_frag_<N>.frag — fragments file for commit N. The earliest
+ *       commit with a frag is the FULL model (baseline); later frags are
+ *       incremental (only that commit's created+modified geometry).
+ */
+declare class _GitHistoryManager extends OBC.Component {
+    static readonly uuid: "3f9c1a7e-6b2d-4e18-9a5c-7d0e2f4b6c81";
+    enabled: boolean;
+    readonly onCommitsChanged: OBC.Event<RevitFlowCommit[]>;
+    readonly onCommitChanged: OBC.Event<number | null>;
+    readonly onLoadingChanged: OBC.Event<boolean>;
+    readonly onError: OBC.Event<string>;
+    world?: OBC.World;
+    /** When true, showCommit() ghosts (dims) every non-changed element. */
+    isolateChanges: boolean;
+    /** Green — created elements. */
+    readonly STYLE_CREATED = "#22c55e";
+    /** Blue — modified elements. */
+    readonly STYLE_MODIFIED = "#3b82f6";
+    /** Red — deleted elements. */
+    readonly STYLE_DELETED = "#ef4444";
+    private _client?;
+    private _projectId?;
+    private _docFolderId?;
+    private _modelName;
+    private _commits;
+    private _currentCommitId;
+    /** filename(lowercase) → fileId, for the doc folder's current listing. */
+    private _fileIndex;
+    /** modelIds (== frag fileIds) already loaded into the viewer. */
+    private _loadedFrags;
+    /** Ghosted localIds per modelId, so isolate can be cleared/re-applied. */
+    private _ghosted;
+    private _baselineCommitId?;
+    private _stylesRegistered;
+    private _loading;
+    constructor(components: OBC.Components);
+    get ready(): boolean;
+    get loading(): boolean;
+    get commits(): RevitFlowCommit[];
+    get currentCommitId(): number | null;
+    get modelName(): string;
+    get baselineCommitId(): number | undefined;
+    /** True if commit `id` has a fragments file available in storage. */
+    hasFrag(commitId: number): boolean;
+    /**
+     * Wire the platform client and load the commit history. Resolves the
+     * viewer world in the background (it may not exist until <top-viewer>
+     * mounts). Consumer panels call this once on connect.
+     */
+    init(client: PlatformClient): Promise<void>;
+    /**
+     * (Re)fetch `revitflow_history.json` from the project's
+     * `bimterop/revit-*` folder and publish the commit list. Also indexes the
+     * folder's files so frag lookups are a local map hit.
+     */
+    loadHistory(): Promise<void>;
+    /**
+     * Show commit `commitId`: ensure the baseline (full-model) .frag is loaded,
+     * load the commit's own incremental frag (so created elements are present),
+     * then color its changed elements. Deleted elements that no longer exist in
+     * any loaded model are skipped. Fires onCommitChanged.
+     */
+    showCommit(commitId: number): Promise<void>;
+    /** Remove all revit-flow coloring + ghosting and reset the selection. */
+    clear(): Promise<void>;
+    /** Toggle isolate mode; re-applies to the current commit if one is shown. */
+    setIsolateChanges(on: boolean): Promise<void>;
+    private _colorStyle;
+    private _registerStyles;
+    private _clearHighlights;
+    /**
+     * Resolve each change bucket's GUIDs to localIds across every loaded model
+     * and paint them with the matching named style.
+     */
+    private _colorCommit;
+    /** GUIDs → { modelId: Set<localId> } across the given models. */
+    private _buildMap;
+    private _mergeMaps;
+    private _ghostAllExcept;
+    private _clearGhost;
+    private _ensureBaselineLoaded;
+    /** Load commit `commitId`'s .frag into the viewer under modelId == fileId. */
+    private _ensureFragLoaded;
+    /**
+     * Resolve (and cache) the `bimterop/revit-*` doc subfolder id. Filters the
+     * project-wide folder list locally by parentId + name prefix, mirroring the
+     * SnapshotList prototype (the server-side parentFolderId filter is
+     * unreliable). Returns null if the project hasn't been pushed to yet.
+     */
+    private _resolveDocFolderId;
+    private _setLoading;
+    private _firstWorld;
+}
+
+/**
+ * GitHistoryManager — headless engine for the revit-flow git-history built-in.
+ *
+ * Owns ALL viewer mutation: it fetches the commit history + fragment artifacts
+ * from project storage, loads the baseline (full-model) .frag into the shared
+ * viewer, and colors a commit's changed elements (create → green, update →
+ * blue, delete → red) via named Highlighter styles. The Lit panel
+ * (`top-git-history`) is intent-only: it calls these methods and subscribes to
+ * the events below, and never touches the Highlighter / FragmentsManager
+ * directly.
+ *
+ * Data model (per model, in `bimterop/revit-<docId>/`):
+ *   - revitflow_history.json — { model, commits: [{ id, parent, author,
+ *       source, timestamp, changes:[{type,uniqueId}], counts }] }
+ *   - revitflow_frag_<N>.frag — fragments file for commit N. The earliest
+ *       commit with a frag is the FULL model (baseline); later frags are
+ *       incremental (only that commit's created+modified geometry).
+ */
+export type GitHistoryManager = InstanceType<typeof _GitHistoryManager>;
+/**
+ * GitHistoryManager — headless engine for the revit-flow git-history built-in.
+ *
+ * Owns ALL viewer mutation: it fetches the commit history + fragment artifacts
+ * from project storage, loads the baseline (full-model) .frag into the shared
+ * viewer, and colors a commit's changed elements (create → green, update →
+ * blue, delete → red) via named Highlighter styles. The Lit panel
+ * (`top-git-history`) is intent-only: it calls these methods and subscribes to
+ * the events below, and never touches the Highlighter / FragmentsManager
+ * directly.
+ *
+ * Data model (per model, in `bimterop/revit-<docId>/`):
+ *   - revitflow_history.json — { model, commits: [{ id, parent, author,
+ *       source, timestamp, changes:[{type,uniqueId}], counts }] }
+ *   - revitflow_frag_<N>.frag — fragments file for commit N. The earliest
+ *       commit with a frag is the FULL model (baseline); later frags are
+ *       incremental (only that commit's created+modified geometry).
+ */
+export const GitHistoryManager = { uuid: '3f9c1a7e-6b2d-4e18-9a5c-7d0e2f4b6c81' } as typeof _GitHistoryManager & { uuid: '3f9c1a7e-6b2d-4e18-9a5c-7d0e2f4b6c81' };
+
 /**
  * A simple test component to validate the built-in component pipeline.
  * Replace this with real components once the infrastructure is verified.