@bubblydoo/uxp-toolkit-react 0.0.2

package/README.md

@@ -0,0 +1,24 @@
+# @bubblydoo/uxp-toolkit-react
+
+React hooks for Photoshop UXP plugins. Generic, non–app-specific utilities built on `@bubblydoo/uxp-toolkit`.
+
+## Peer dependencies
+
+- `react` (^18 or ^19)
+- `@tanstack/react-query` (^5)
+- `@bubblydoo/uxp-toolkit` (workspace)
+- `zod` (^3 or ^4)
+
+## Exports
+
+- **useEventListenerSkippable** – Subscribe to events with optional skip/filter so triggers can be queued or ignored
+- **useApplicationInfoQuery** – React Query for Photoshop application info (e.g. panel list)
+- **useIsPluginPanelVisible** – Whether the plugin panel is visible (optionally for a given `panelId`)
+- **useOnDocumentEdited** – Run a callback when the given document is edited (select, delete, make, set, move, close, show, hide, etc.)
+- **useActiveDocument** – Sync external store for the current active document
+- **useOnDocumentLayersEdited** – Run a callback when layers change (delete, make, set, move, close)
+- **useOnDocumentLayersSelection** – Run a callback when layer selection changes (select, deselect)
+- **useOnEvent** – Run a callback for arbitrary Photoshop action events on a given document
+- **useOpenDocuments** – Sync external store for the list of open documents
+
+All document/event hooks that take a `document` only fire when that document is the active document and (where applicable) when the plugin panel is visible.

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { Document } from 'photoshop/dom/Document';
+
+declare function useEventListenerSkippable({ subscribe, trigger, skip, filter, }: {
+    subscribe: (boundTrigger: () => void) => (() => void);
+    trigger: () => void;
+    /** If true, the trigger will be queued until the skip is false */
+    skip: boolean;
+    /** If false, the trigger will be skipped altogether */
+    filter: boolean;
+}): void;
+
+declare function useApplicationInfoQuery(refetchInterval?: number): _tanstack_react_query.UseQueryResult<{
+    active: boolean;
+    autoShowHomeScreen: boolean;
+    available: number;
+    buildNumber: string;
+    documentArea: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    hostName: string;
+    hostVersion: {
+        versionMajor: number;
+        versionMinor: number;
+        versionFix: number;
+    };
+    localeInfo: {
+        decimalPoint: string;
+    };
+    osVersion: string;
+    panelList: {
+        ID: string;
+        name: string;
+        obscured: boolean;
+        visible: boolean;
+    }[];
+}, Error>;
+declare function useIsPluginPanelVisible(panelId: string): boolean | null;
+
+declare function useOnDocumentEdited(document: Document, trigger: () => void): void;
+declare function useActiveDocument(): Document | null;
+
+declare function useOnDocumentLayersEdited(document: Document, trigger: () => void): void;
+
+declare function useOnDocumentLayersSelection(document: Document, trigger: () => void): void;
+
+declare function useOnEvent(document: Document, events: string[], trigger: () => void): void;
+
+declare function useOpenDocuments(): Document[];
+
+export { useActiveDocument, useApplicationInfoQuery, useEventListenerSkippable, useIsPluginPanelVisible, useOnDocumentEdited, useOnDocumentLayersEdited, useOnDocumentLayersSelection, useOnEvent, useOpenDocuments };

package/dist/index.js

@@ -0,0 +1,239 @@
+// src/useEventListenerSkippable.ts
+import { useEffect, useState } from "react";
+function useEventListenerSkippable({
+  subscribe,
+  trigger,
+  skip,
+  filter
+}) {
+  const [queuedWhileSkipped, setQueuedWhileSkipped] = useState(false);
+  useEffect(() => {
+    const unsubscribe = subscribe(() => {
+      if (filter) {
+        if (skip) {
+          setQueuedWhileSkipped(true);
+        } else {
+          trigger();
+        }
+      }
+    });
+    return unsubscribe;
+  }, [subscribe, trigger, skip, filter]);
+  useEffect(() => {
+    if (queuedWhileSkipped && !skip) {
+      trigger();
+      setQueuedWhileSkipped(false);
+    }
+  }, [queuedWhileSkipped, trigger, skip]);
+}
+
+// src/useIsPluginVisible.tsx
+import { useQuery } from "@tanstack/react-query";
+import { entrypoints } from "uxp";
+import { photoshopGetApplicationInfo, uxpEntrypointsSchema } from "@bubblydoo/uxp-toolkit";
+var pluginInfo = uxpEntrypointsSchema.parse(entrypoints)._pluginInfo;
+function useApplicationInfoQuery(refetchInterval = 1e3) {
+  return useQuery({
+    queryKey: ["application-info"],
+    queryFn: async () => {
+      const appInfo = await photoshopGetApplicationInfo();
+      return appInfo;
+    },
+    refetchInterval
+  });
+}
+function useIsPluginPanelVisible(panelId) {
+  const appInfoQuery = useApplicationInfoQuery(1e3);
+  if (!appInfoQuery.data) return null;
+  const pluginPanel = appInfoQuery.data.panelList.find((panel) => {
+    const idParts = panel.ID.split("/");
+    return idParts.includes(pluginInfo.id) && idParts.includes(panelId);
+  });
+  if (!pluginPanel) return false;
+  return pluginPanel.visible;
+}
+function useIsAnyPluginPanelVisible() {
+  const appInfoQuery = useApplicationInfoQuery(1e3);
+  if (!appInfoQuery.data) return null;
+  const pluginPanel = appInfoQuery.data.panelList.find((panel) => {
+    const idParts = panel.ID.split("/");
+    return idParts.includes(pluginInfo.id);
+  });
+  if (!pluginPanel) return false;
+  return pluginPanel.visible;
+}
+
+// src/useOnDocumentEdited.tsx
+import { action, app } from "photoshop";
+import { useSyncExternalStore } from "react";
+var EVENTS = [
+  "select",
+  "delete",
+  "make",
+  "set",
+  "move",
+  "close",
+  "show",
+  "hide",
+  "convertToProfile",
+  "selectNoLayers",
+  "historyStateChanged"
+  // this might have changed the document
+];
+function useOnDocumentEdited(document, trigger) {
+  const isPluginPanelVisible = useIsAnyPluginPanelVisible() ?? true;
+  useEventListenerSkippable({
+    trigger,
+    subscribe: (boundTrigger) => {
+      action.addNotificationListener(EVENTS, boundTrigger);
+      return () => {
+        action.removeNotificationListener(EVENTS, boundTrigger);
+      };
+    },
+    skip: !isPluginPanelVisible,
+    filter: document === app.activeDocument
+  });
+}
+var DOCUMENT_CHANGE_EVENTS = [
+  "select",
+  "open",
+  "close",
+  "smartBrushWorkspace",
+  "layersFiltered"
+];
+var activeDocumentExternalStore = {
+  subscribe: (fn) => {
+    action.addNotificationListener(DOCUMENT_CHANGE_EVENTS, fn);
+    return () => {
+      action.removeNotificationListener(DOCUMENT_CHANGE_EVENTS, fn);
+    };
+  },
+  getSnapshot: () => app.activeDocument
+};
+function useActiveDocument() {
+  return useSyncExternalStore(
+    activeDocumentExternalStore.subscribe,
+    activeDocumentExternalStore.getSnapshot
+  );
+}
+
+// src/useOnDocumentLayersEdited.tsx
+import { action as action2, app as app2 } from "photoshop";
+var EVENTS2 = [
+  // "select",
+  "delete",
+  "make",
+  "set",
+  "move",
+  "close",
+  // "show",
+  // "hide",
+  // "convertToProfile",
+  // "selectNoLayers",
+  "historyStateChanged"
+  // this might have changed the layers
+];
+function useOnDocumentLayersEdited(document, trigger) {
+  const isPluginPanelVisible = useIsAnyPluginPanelVisible() ?? true;
+  useEventListenerSkippable({
+    trigger,
+    subscribe: (boundTrigger) => {
+      action2.addNotificationListener(EVENTS2, boundTrigger);
+      return () => {
+        action2.removeNotificationListener(EVENTS2, boundTrigger);
+      };
+    },
+    skip: !isPluginPanelVisible,
+    filter: document === app2.activeDocument
+  });
+}
+
+// src/useOnDocumentLayersSelection.tsx
+import { action as action3, app as app3 } from "photoshop";
+var EVENTS3 = [
+  "select",
+  "deselect",
+  // "delete",
+  // "make",
+  // "set",
+  // "move",
+  // "close",
+  // "show",
+  // "hide",
+  // "convertToProfile",
+  // "selectNoLayers",
+  "historyStateChanged"
+  // this might have changed the layers selection, e.g. when deleting an undo
+];
+function useOnDocumentLayersSelection(document, trigger) {
+  const isPluginPanelVisible = useIsAnyPluginPanelVisible() ?? true;
+  useEventListenerSkippable({
+    trigger,
+    subscribe: (boundTrigger) => {
+      action3.addNotificationListener(EVENTS3, boundTrigger);
+      return () => {
+        action3.removeNotificationListener(EVENTS3, boundTrigger);
+      };
+    },
+    skip: !isPluginPanelVisible,
+    filter: document === app3.activeDocument
+  });
+}
+
+// src/useOnEvent.tsx
+import { action as action4, app as app4 } from "photoshop";
+function useOnEvent(document, events, trigger) {
+  const isPluginPanelVisible = useIsAnyPluginPanelVisible() ?? true;
+  useEventListenerSkippable({
+    trigger,
+    subscribe: (boundTrigger) => {
+      action4.addNotificationListener(events, boundTrigger);
+      return () => {
+        action4.removeNotificationListener(events, boundTrigger);
+      };
+    },
+    skip: !isPluginPanelVisible,
+    filter: document === app4.activeDocument
+  });
+}
+
+// src/useOpenDocuments.tsx
+import { action as action5, app as app5 } from "photoshop";
+import { useSyncExternalStore as useSyncExternalStore2 } from "react";
+var OPEN_DOCUMENTS_EVENTS = ["open", "close"];
+var cachedDocuments = null;
+var cachedDocumentsSnapshot = null;
+var openDocumentsExternalStore = {
+  subscribe: (fn) => {
+    action5.addNotificationListener(OPEN_DOCUMENTS_EVENTS, fn);
+    return () => {
+      action5.removeNotificationListener(OPEN_DOCUMENTS_EVENTS, fn);
+    };
+  },
+  getSnapshot: () => {
+    const currentDocuments = Array.from(app5.documents);
+    const currentSnapshot = currentDocuments.map((doc) => doc.id || doc.name).join(",");
+    if (currentSnapshot !== cachedDocumentsSnapshot) {
+      cachedDocuments = currentDocuments;
+      cachedDocumentsSnapshot = currentSnapshot;
+    }
+    return cachedDocuments || [];
+  }
+};
+function useOpenDocuments() {
+  return useSyncExternalStore2(
+    openDocumentsExternalStore.subscribe,
+    openDocumentsExternalStore.getSnapshot
+  );
+}
+export {
+  useActiveDocument,
+  useApplicationInfoQuery,
+  useEventListenerSkippable,
+  useIsPluginPanelVisible,
+  useOnDocumentEdited,
+  useOnDocumentLayersEdited,
+  useOnDocumentLayersSelection,
+  useOnEvent,
+  useOpenDocuments
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@bubblydoo/uxp-toolkit-react",
+  "version": "0.0.2",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "zod": "^3.0.0 || ^4.0.0",
+    "@bubblydoo/uxp-toolkit": "0.0.2"
+  },
+  "devDependencies": {
+    "@adobe-uxp-types/uxp": "^0.0.9",
+    "@tanstack/react-query": "^5.0.0",
+    "@types/photoshop": "^25.0.2",
+    "@types/react": "^19.0.0",
+    "@types/node": "^20.8.7",
+    "react": "^19.0.0",
+    "typescript": "^5.8.3",
+    "tsup": "^8.5.1",
+    "zod": "^4.3.6",
+    "@bubblydoo/tsconfig": "0.0.1",
+    "@bubblydoo/uxp-toolkit": "0.0.2"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}