Merge branch 'develop' into feat/replace-schemaio-revert-position

Author: Gavin McDonald

app/packages/annotation/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@fiftyone/annotation",
+    "version": "1.0.0",
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "preview": "vite preview",
+        "watch": "nodemon --watch ./src --ext js,jsx,ts,tsx --exec 'yarn build'",
+        "test": "vitest"
+    },
+    "files": [
+        "dist"
+    ],
+    "main": "src/index.ts",
+    "devDependencies": {
+        "@testing-library/dom": "^10.4.0",
+        "@testing-library/react": "^16.2.0",
+        "@typescript-eslint/eslint-plugin": "^6.0.0",
+        "@typescript-eslint/parser": "^6.0.0",
+        "eslint": "^8.0.0",
+        "jsdom": "^26.0.0",
+        "typescript": "^4.7.4",
+        "vite": "^5.4.12",
+        "vite-plugin-externals": "^0.5.0",
+        "vitest": "^1.6.0"
+    },
+    "fiftyone": {
+        "script": "dist/index.umd.js"
+    },
+    "packageManager": "[email protected]",
+    "peerDependencies": {
+        "@fiftyone/commands": "*",
+        "@fiftyone/events": "*",
+        "jotai": "*",
+        "react": "*"
+    }
+}

app/packages/annotation/src/commands.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright 2017-2025, Voxel51, Inc.
+ */
+
+import { Command } from "@fiftyone/commands";
+import { AnnotationLabel } from "@fiftyone/state";
+import { Field } from "@fiftyone/utilities";
+
+/**
+ * Command to upsert (create or update) an annotation label.
+ */
+export class UpsertAnnotationCommand extends Command<boolean> {
+  constructor(
+    public readonly label: AnnotationLabel,
+    public readonly schema: Field
+  ) {
+    super();
+  }
+}
+
+/**
+ * Command to delete an annotation label.
+ */
+export class DeleteAnnotationCommand extends Command<boolean> {
+  constructor(
+    public readonly label: AnnotationLabel,
+    public readonly schema: Field
+  ) {
+    super();
+  }
+}

app/packages/core/src/components/Modal/Lighter/deltas.ts renamed to app/packages/annotation/src/deltas.ts

@@ -8,8 +8,11 @@ import {
   PolylineAnnotationLabel,
   Sample,
 } from "@fiftyone/state";
-import { JSONDeltas } from "../../../client";
-import { extractNestedField, generateJsonPatch } from "../../../utils/json";
+import { JSONDeltas } from "@fiftyone/core/src/client";
+import {
+  extractNestedField,
+  generateJsonPatch,
+} from "@fiftyone/core/src/utils/json";
 import { Field, Schema } from "@fiftyone/utilities";
 
 /**

app/packages/annotation/src/events.ts

@@ -0,0 +1,80 @@
+import { createUseEventHandler, useEventBus } from "@fiftyone/events";
+import { AnnotationLabel } from "@fiftyone/state";
+import { Field } from "@fiftyone/utilities";
+
+export const AnnotationChannelId = "default";
+
+type MutationError<T> = {
+  labelId: string;
+  type: T;
+  error?: Error;
+};
+
+type MutationSuccess<T> = {
+  labelId: string;
+  type: T;
+};
+
+export type AnnotationEventGroup = {
+  /**
+   * Notification event emitted when a label is upserted successfully.
+   */
+  "annotation:notification:upsertSuccess": MutationSuccess<"upsert">;
+  /**
+   * Notification event emitted when an error occurs while upserting a label.
+   */
+  "annotation:notification:upsertError": MutationError<"upsert">;
+  /**
+   * Notification event emitted when a label is deleted successfully.
+   */
+  "annotation:notification:deleteSuccess": MutationSuccess<"delete">;
+  /**
+   * Notification event emitted when an error occurs while deleting a label.
+   */
+  "annotation:notification:deleteError": MutationError<"delete">;
+  /**
+   * Notification event emitted when a sidebar value is updated.
+   */
+  "annotation:notification:sidebarValueUpdated": {
+    overlayId: string;
+    currentLabel: AnnotationLabel["data"];
+    value: Partial<AnnotationLabel["data"]>;
+  };
+  /**
+   * Notification event emitted when a label is selected.
+   */
+  "annotation:notification:sidebarLabelSelected": {
+    id: string;
+    type: AnnotationLabel["type"];
+    data?: Partial<AnnotationLabel["data"]>;
+  };
+  /**
+   * Notification event emitted when a label is hovered.
+   */
+  "annotation:notification:sidebarLabelHover": {
+    id: string;
+    tooltip?: boolean;
+  };
+  /**
+   * Notification event emitted when a label is unhovered.
+   */
+  "annotation:notification:sidebarLabelUnhover": {
+    id: string;
+  };
+  /**
+   * Notification event emitted when a canvas overlay is hovered.
+   * TODO: FOR NOW THIS IS ONLY FOR 3D LABELS.
+   * USE THIS FOR 2D ONCE WE GET RID OF LIGHTER HOVER EVENTS.
+   */
+  "annotation:notification:canvasOverlayHover": {
+    id: string;
+  };
+  /**
+   * Notification event emitted when a canvas overlay is unhovered.
+   * TODO: FOR NOW THIS IS ONLY FOR 3D LABELS.
+   * USE THIS FOR 2D ONCE WE GET RID OF LIGHTER HOVER EVENTS.
+   */
+  "annotation:notification:canvasOverlayUnhover": {
+    id: string;
+  };
+};

app/packages/annotation/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./useAnnotationEventBus";
+export * from "./useAnnotationEventHandler";
+export * from "./useRegisterAnnotationCommandHandlers";

app/packages/annotation/src/hooks/useAnnotationEventBus.ts

@@ -0,0 +1,4 @@
+import { useEventBus } from "@fiftyone/events";
+import { AnnotationEventGroup } from "../events";
+
+export const useAnnotationEventBus = () => useEventBus<AnnotationEventGroup>();

app/packages/annotation/src/hooks/useAnnotationEventHandler.ts

@@ -0,0 +1,5 @@
+import { createUseEventHandler } from "@fiftyone/events";
+import { AnnotationEventGroup } from "../events";
+
+export const useAnnotationEventHandler =
+  createUseEventHandler<AnnotationEventGroup>();

app/packages/annotation/src/hooks/useRegisterAnnotationCommandHandlers.ts

@@ -0,0 +1,211 @@
+/**
+ * Copyright 2017-2025, Voxel51, Inc.
+ */
+
+import { useAnnotationEventBus } from "@fiftyone/annotation";
+import { useRegisterCommandHandler } from "@fiftyone/commands";
+import { JSONDeltas, patchSample } from "@fiftyone/core/src/client";
+import { transformSampleData } from "@fiftyone/core/src/client/transformer";
+import { parseTimestamp } from "@fiftyone/core/src/client/util";
+import { Sample } from "@fiftyone/looker";
+import { isSampleIsh } from "@fiftyone/looker/src/util";
+import {
+  AnnotationLabel,
+  datasetId as fosDatasetId,
+  modalSample,
+  useRefreshSample,
+} from "@fiftyone/state";
+import { Field } from "@fiftyone/utilities";
+import { useCallback } from "react";
+import { useRecoilCallback, useRecoilValue } from "recoil";
+import { DeleteAnnotationCommand, UpsertAnnotationCommand } from "../commands";
+import { OpType, buildJsonPath, buildLabelDeltas } from "../deltas";
+
+/**
+ * Hook that registers command handlers for annotation persistence.
+ * This should be called once in the composition root.
+ */
+export const useRegisterAnnotationCommandHandlers = () => {
+  const datasetId = useRecoilValue(fosDatasetId);
+  const refreshSample = useRefreshSample();
+  const eventBus = useAnnotationEventBus();
+
+  // The annotation endpoint requires a version token in order to execute
+  // mutations.
+  // Updated version tokens are returned in the response body,
+  // but the server also allows the current sample timestamp to be used as
+  // a version token.
+  const getVersionToken = useRecoilCallback(
+    ({ snapshot }) =>
+      async (): Promise<string | undefined> => {
+        const currentSample = (await snapshot.getPromise(modalSample))?.sample;
+        if (!currentSample?.last_modified_at) {
+          return undefined;
+        }
+
+        const isoTimestamp = parseTimestamp(
+          currentSample.last_modified_at as unknown as string
+        )?.toISOString();
+
+        // server doesn't like the iso timestamp ending in 'Z'
+        if (isoTimestamp?.endsWith("Z")) {
+          return isoTimestamp.substring(0, isoTimestamp.length - 1);
+        } else {
+          return isoTimestamp;
+        }
+      },
+    []
+  );
+
+  const handlePatchSample = useRecoilCallback(
+    ({ snapshot }) =>
+      async (sampleDeltas: JSONDeltas): Promise<boolean> => {
+        const currentSample = (await snapshot.getPromise(modalSample))?.sample;
+        const versionToken = await getVersionToken();
+
+        if (!datasetId || !currentSample?._id || !versionToken) {
+          return false;
+        }
+
+        if (sampleDeltas.length > 0) {
+          try {
+            const response = await patchSample({
+              datasetId,
+              sampleId: currentSample._id,
+              deltas: sampleDeltas,
+              versionToken,
+            });
+
+            // transform response data to match the graphql sample format
+            const cleanedSample = transformSampleData(response.sample);
+            if (isSampleIsh(cleanedSample)) {
+              refreshSample(cleanedSample as Sample);
+            } else {
+              console.error(
+                "response data does not adhere to sample format",
+                cleanedSample
+              );
+            }
+          } catch (error) {
+            console.error("error patching sample", error);
+
+            return false;
+          }
+        }
+
+        return true;
+      },
+    [datasetId, refreshSample, getVersionToken]
+  );
+
+  // callback which handles both mutation (upsert) and deletion
+  const handlePersistence = useRecoilCallback(
+    ({ snapshot }) =>
+      async (
+        annotationLabel: AnnotationLabel,
+        schema: Field,
+        opType: OpType
+      ): Promise<boolean> => {
+        const currentSample = (await snapshot.getPromise(modalSample))?.sample;
+
+        if (!currentSample) {
+          console.error("missing sample data!");
+          return false;
+        }
+
+        if (!annotationLabel) {
+          console.error("missing annotation label!");
+          return false;
+        }
+
+        // calculate label deltas between current sample data and new label data
+        const sampleDeltas = buildLabelDeltas(
+          currentSample,
+          annotationLabel,
+          schema,
+          opType
+        ).map((delta) => ({
+          ...delta,
+          // convert label delta to sample delta
+          path: buildJsonPath(annotationLabel.path, delta.path),
+        }));
+
+        return await handlePatchSample(sampleDeltas);
+      },
+    [handlePatchSample]
+  );
+
+  useRegisterCommandHandler(
+    UpsertAnnotationCommand,
+    useCallback(
+      async (cmd) => {
+        const labelId = cmd.label.data._id;
+        try {
+          const success = await handlePersistence(
+            cmd.label,
+            cmd.schema,
+            "mutate"
+          );
+
+          if (success) {
+            eventBus.dispatch("annotation:notification:upsertSuccess", {
+              labelId,
+              type: "upsert",
+            });
+          } else {
+            eventBus.dispatch("annotation:notification:upsertError", {
+              labelId,
+              type: "upsert",
+            });
+          }
+          return success;
+        } catch (error) {
+          eventBus.dispatch("annotation:notification:upsertError", {
+            labelId,
+            type: "upsert",
+            error: error as Error,
+          });
+          throw error;
+        }
+      },
+      [handlePersistence, eventBus]
+    )
+  );
+
+  useRegisterCommandHandler(
+    DeleteAnnotationCommand,
+    useCallback(
+      async (cmd) => {
+        const labelId = cmd.label.data._id;
+        try {
+          const success = await handlePersistence(
+            cmd.label,
+            cmd.schema,
+            "delete"
+          );
+
+          if (success) {
+            eventBus.dispatch("annotation:notification:deleteSuccess", {
+              labelId,
+              type: "delete",
+            });
+          } else {
+            eventBus.dispatch("annotation:notification:deleteError", {
+              labelId,
+              type: "delete",
+            });
+          }
+          return success;
+        } catch (error) {
+          eventBus.dispatch("annotation:notification:deleteError", {
+            labelId,
+            type: "delete",
+            error: error as Error,
+          });
+          throw error;
+        }
+      },
+      [handlePersistence, eventBus]
+    )
+  );
+};

app/packages/annotation/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./commands";
+export * from "./deltas";
+export * from "./events";
+export * from "./hooks";