@sanity/workbench 0.1.0-alpha.12 → 0.1.0-alpha.14

package/src/system/root.machine.ts

@@ -0,0 +1,190 @@
+import { createSanityInstance, type SanityInstance } from "@sanity/sdk";
+import { raise, sendTo, setup, type ActorOptions } from "xstate";
+
+import { authLogic } from "./auth.machine";
+import { inspect } from "./inspect";
+import {
+  type SystemPreferencesAdapter,
+  systemPreferencesLogic,
+} from "./system-preferences.machine";
+import {
+  telemetryLogic,
+  type WorkbenchUserProperties,
+} from "./telemetry.machine";
+
+type OSInput = WorkbenchUserProperties & {
+  systemPreferencesAdapter?: SystemPreferencesAdapter;
+};
+
+type OSContext = {
+  instance: SanityInstance;
+  userProperties: WorkbenchUserProperties;
+  systemPreferencesAdapter: SystemPreferencesAdapter | undefined;
+};
+
+/**
+ * The base inputs for the OS machine.
+ * @internal
+ */
+export interface OSBaseInput extends Pick<OSContext, "instance"> {}
+
+/**
+ * The sanity OS machine, responsible for managing the global state of the OS.
+ * @public
+ * @example
+ * ```ts
+ * import { os, createOSOptions } from "@sanity/workbench/system";
+ * import { useActor } from "@xstate/react";
+ *
+ * const [state, send] = useActor(os, createOSOptions({
+ *   version: "1.0.0",
+ *   organizationId: "...",
+ *   environment: "production",
+ *   userAgent: navigator.userAgent,
+ * }));
+ * ```
+ */
+export const os = setup({
+  types: {
+    input: {} as OSInput,
+    context: {} as OSContext,
+    events: {} as
+      | { type: "boot.auth.ready" }
+      | { type: "boot.auth.failed" }
+      | { type: "boot.telemetry.ready" },
+    // https://github.com/statelyai/xstate/issues/5515
+    children: {} as {
+      auth: "auth";
+      telemetry: "telemetry";
+      "system-preferences": "systemPreferences";
+    },
+  },
+  actors: {
+    auth: authLogic,
+    telemetry: telemetryLogic,
+    systemPreferences: systemPreferencesLogic,
+  },
+  guards: {
+    hasTag: (_, params: { hasTag: boolean }) => params.hasTag,
+  },
+  actions: {
+    raiseAuthReady: raise({ type: "boot.auth.ready" }),
+    raiseAuthFailed: raise({ type: "boot.auth.failed" }),
+    raiseTelemetryReady: raise({
+      type: "boot.telemetry.ready",
+    }),
+    startTelemetry: sendTo("telemetry", {
+      type: "telemetry.start",
+    }),
+  },
+}).createMachine({
+  id: "os",
+  context: ({ input }) => ({
+    instance: createSanityInstance(),
+    userProperties: {
+      version: input.version,
+      organizationId: input.organizationId,
+      environment: input.environment,
+      userAgent: input.userAgent,
+    },
+    systemPreferencesAdapter: input.systemPreferencesAdapter,
+  }),
+  initial: "booting",
+  invoke: [
+    {
+      id: "auth",
+      systemId: "auth",
+      src: "auth",
+      input: ({ context }) => ({ instance: context.instance }),
+      onSnapshot: [
+        {
+          guard: {
+            type: "hasTag",
+            params: ({ event }) => ({
+              hasTag: event.snapshot.hasTag("authenticated"),
+            }),
+          },
+          actions: [{ type: "raiseAuthReady" }],
+        },
+        {
+          guard: {
+            type: "hasTag",
+            params: ({ event }) => ({
+              hasTag: event.snapshot.hasTag("error"),
+            }),
+          },
+          actions: [{ type: "raiseAuthFailed" }],
+        },
+      ],
+    },
+    {
+      id: "telemetry",
+      systemId: "telemetry",
+      src: "telemetry",
+      input: ({ context }) => ({
+        instance: context.instance,
+        ...context.userProperties,
+      }),
+      onSnapshot: [
+        {
+          guard: {
+            type: "hasTag",
+            params: ({ event }) => ({
+              hasTag: event.snapshot.hasTag("telemetry-resolved"),
+            }),
+          },
+          actions: [{ type: "raiseTelemetryReady" }],
+        },
+      ],
+    },
+    {
+      id: "system-preferences",
+      systemId: "system-preferences",
+      src: "systemPreferences",
+      input: ({ context }) => ({ adapter: context.systemPreferencesAdapter }),
+    },
+  ],
+  states: {
+    booting: {
+      initial: "auth",
+      states: {
+        auth: {
+          on: {
+            "boot.auth.ready": {
+              target: "telemetry",
+              actions: [{ type: "startTelemetry" }],
+            },
+            "boot.auth.failed": { target: "error" },
+          },
+        },
+        telemetry: {
+          on: {
+            "boot.telemetry.ready": { target: "done" },
+          },
+        },
+        error: {},
+        done: { type: "final" },
+      },
+      onDone: { target: "running" },
+    },
+    running: {
+      type: "parallel",
+    },
+  },
+});
+
+/**
+ * Creates a set of default options for the OS machine. Forwards the workbench
+ * user properties to the machine's input and wires the structured-logging
+ * `inspect` callback. Browser-specific concerns (color-scheme seeding,
+ * persistence) live in the {@link SystemPreferencesAdapter} the host passes
+ * via `systemPreferencesAdapter`.
+ * @public
+ */
+export function createOSOptions(input: OSInput) {
+  return {
+    id: "os",
+    input,
+    inspect,
+  } satisfies ActorOptions<typeof os>;
+}

package/src/system/system-preferences.machine.ts

@@ -0,0 +1,215 @@
+import { assign, fromCallback, sendTo, setup } from "xstate";
+
+type ColorScheme = "light" | "dark";
+
+type ColorSchemePreference = "system" | ColorScheme;
+
+/**
+ * The system-preferences machine's context. Consumers read fields directly
+ * (e.g. via `useSelector`) rather than going through a resolver utility —
+ * the action handlers keep `colorScheme` in sync with `preferredColorScheme`
+ * and `osColorScheme`.
+ *
+ * Note: `colorScheme` is intentionally stored as derived state in context so
+ * consumers can read the resolved value directly without a utility. The
+ * action handlers below are the single source of truth for the resolution.
+ * @public
+ */
+export type SystemPreferencesContext = {
+  /** User's color scheme choice; `system` defers to the OS preference. */
+  preferredColorScheme: ColorSchemePreference;
+  /** Last reported OS color scheme. Used to resolve `colorScheme` when the
+   * preference is `system`. */
+  osColorScheme: ColorScheme;
+  /** Resolved color scheme — what the UI should render. Recomputed by the
+   * action handlers whenever an input changes. */
+  colorScheme: ColorScheme;
+};
+
+const DEFAULT_PREFERRED_COLOR_SCHEME: ColorSchemePreference = "system";
+const DEFAULT_OS_COLOR_SCHEME: ColorScheme = "light";
+
+/**
+ * Events the system-preferences machine accepts. Both originate from the
+ * host's adapter — `preferredColorScheme.set` is also forwarded back to it
+ * so it can persist the user's choice.
+ * @public
+ */
+export type SystemPreferencesEvent =
+  | {
+      type: "preferredColorScheme.set";
+      preferredColorScheme: ColorSchemePreference;
+    }
+  | {
+      type: "osColorScheme.set";
+      osColorScheme: ColorScheme;
+    };
+
+/**
+ * Adapter interface the host implements to give the system-preferences
+ * machine access to the user's environment (OS color scheme, persistent
+ * storage, cross-context change notifications).
+ *
+ * The package owns all orchestration — synchronous seeding, idempotent
+ * persistence, mapping cleared storage to `"system"`. The host's
+ * implementation is pure DOM/storage glue: read, write, subscribe.
+ * @public
+ */
+export type SystemPreferencesAdapter = {
+  /** Read the user's stored preference. `null` means "no preference set"
+   * (the machine treats this as `"system"`). */
+  getPreferredColorScheme: () => ColorSchemePreference | null;
+  /** Write the user's preference to persistent storage. */
+  persistPreferredColorScheme: (value: ColorSchemePreference) => void;
+  /** Subscribe to cross-context preference changes (e.g. another tab
+   * writing to the shared storage). The callback receives the new stored
+   * value (or `null` if it was cleared). Returns an unsubscribe function. */
+  subscribePreferredColorScheme: (
+    callback: (next: ColorSchemePreference | null) => void,
+  ) => () => void;
+  /** Read the current OS-detected color scheme. */
+  getOsColorScheme: () => ColorScheme;
+  /** Subscribe to OS color-scheme changes (e.g. user flipping dark mode).
+   * Returns an unsubscribe function. */
+  subscribeOsColorScheme: (callback: (next: ColorScheme) => void) => () => void;
+};
+
+const resolveColorScheme = (
+  preferred: ColorSchemePreference,
+  osColorScheme: ColorScheme,
+): ColorScheme => (preferred === "system" ? osColorScheme : preferred);
+
+// Internal bridge actor — subscribes to the host's adapter for runtime
+// changes and persists user-driven preference changes when the parent
+// forwards them. No-op if the host didn't pass an adapter (SSR, tests).
+type AdapterBridgeReceiveEvent = Extract<
+  SystemPreferencesEvent,
+  { type: "preferredColorScheme.set" }
+>;
+
+const adapterBridgeLogic = fromCallback<
+  AdapterBridgeReceiveEvent,
+  SystemPreferencesAdapter | undefined,
+  SystemPreferencesEvent
+>(({ input: adapter, sendBack, receive }) => {
+  if (!adapter) return;
+
+  const unsubscribePreferredColorScheme = adapter.subscribePreferredColorScheme(
+    (next) => {
+      // Falls back to `"system"` so an external clear (another tab deleting
+      // the key) resets the preference rather than silently keeping the
+      // previous value.
+      sendBack({
+        type: "preferredColorScheme.set",
+        preferredColorScheme: next ?? "system",
+      });
+    },
+  );
+
+  const unsubscribeOs = adapter.subscribeOsColorScheme((next) => {
+    sendBack({ type: "osColorScheme.set", osColorScheme: next });
+  });
+
+  receive((event) => {
+    // Idempotent: skip writes that match the current stored value so a
+    // `preferredColorScheme.set` originating from cross-context change
+    // doesn't loop back into another write.
+    if (adapter.getPreferredColorScheme() === event.preferredColorScheme)
+      return;
+
+    adapter.persistPreferredColorScheme(event.preferredColorScheme);
+  });
+
+  return () => {
+    unsubscribePreferredColorScheme();
+    unsubscribeOs();
+  };
+});
+
+/**
+ * @internal
+ */
+export const systemPreferencesLogic = setup({
+  types: {
+    input: {} as { adapter?: SystemPreferencesAdapter },
+    context: {} as SystemPreferencesContext & {
+      adapter: SystemPreferencesAdapter | undefined;
+    },
+    events: {} as SystemPreferencesEvent,
+  },
+  actors: {
+    adapterBridge: adapterBridgeLogic,
+  },
+  actions: {
+    setPreferredColorScheme: assign({
+      preferredColorScheme: (
+        _,
+        params: { preferredColorScheme: ColorSchemePreference },
+      ) => params.preferredColorScheme,
+      colorScheme: (
+        { context },
+        params: { preferredColorScheme: ColorSchemePreference },
+      ) =>
+        resolveColorScheme(params.preferredColorScheme, context.osColorScheme),
+    }),
+    setOsColorScheme: assign({
+      osColorScheme: (_, params: { osColorScheme: ColorScheme }) =>
+        params.osColorScheme,
+      colorScheme: ({ context }, params: { osColorScheme: ColorScheme }) =>
+        resolveColorScheme(context.preferredColorScheme, params.osColorScheme),
+    }),
+  },
+}).createMachine({
+  id: "system-preferences",
+  initial: "ready",
+  context: ({ input }) => {
+    const adapter = input.adapter;
+    const preferredColorScheme =
+      adapter?.getPreferredColorScheme() ?? DEFAULT_PREFERRED_COLOR_SCHEME;
+    const osColorScheme =
+      adapter?.getOsColorScheme() ?? DEFAULT_OS_COLOR_SCHEME;
+
+    return {
+      adapter,
+      preferredColorScheme,
+      osColorScheme,
+      colorScheme: resolveColorScheme(preferredColorScheme, osColorScheme),
+    };
+  },
+  invoke: {
+    id: "adapter",
+    src: "adapterBridge",
+    input: ({ context }) => context.adapter,
+  },
+  states: {
+    ready: {
+      on: {
+        "preferredColorScheme.set": {
+          actions: [
+            {
+              type: "setPreferredColorScheme",
+              params: ({ event }) => ({
+                preferredColorScheme: event.preferredColorScheme,
+              }),
+            },
+            // Forward to the adapter bridge so it can persist the user's
+            // choice. The bridge guards against redundant writes, so
+            // round-tripping a `preferredColorScheme.set` it sourced itself
+            // (e.g. from a `storage` event in another tab) is a no-op.
+            sendTo("adapter", ({ event }) => event),
+          ],
+        },
+        "osColorScheme.set": {
+          actions: [
+            {
+              type: "setOsColorScheme",
+              params: ({ event }) => ({
+                osColorScheme: event.osColorScheme,
+              }),
+            },
+          ],
+        },
+      },
+    },
+  },
+});

package/src/system/telemetry.machine.ts

@@ -0,0 +1,179 @@
+import { getClient, type SanityInstance } from "@sanity/sdk";
+import {
+  type ConsentStatus,
+  createBatchedStore,
+  createSessionId,
+  type TelemetryEvent,
+  type TelemetryStore,
+} from "@sanity/telemetry";
+import { assign, fromPromise, setup } from "xstate";
+
+import type { OSBaseInput } from "./root.machine";
+
+/**
+ * @public
+ */
+export type WorkbenchUserProperties = {
+  version: string;
+  organizationId: string;
+  environment: string;
+  userAgent: string;
+};
+
+/**
+ * @internal
+ */
+export interface TelemetryInput extends OSBaseInput, WorkbenchUserProperties {}
+
+/**
+ * TODO: this shouldn't be unique to the telemetry machine,
+ * remove this and set it globally with a single client actor.
+ */
+const TELEMETRY_API_VERSION = "2024-11-12";
+/**
+ * 30 seconds, in milliseconds, is the default flush interval
+ * for the telemetry store.
+ */
+const FLUSH_INTERVAL_MS = 30_000;
+
+type ConsentResult = { status: ConsentStatus };
+
+const checkConsentLogic = fromPromise<
+  ConsentResult,
+  { instance: SanityInstance }
+>(async ({ input, signal }) => {
+  try {
+    const client = getClient(input.instance, {
+      apiVersion: TELEMETRY_API_VERSION,
+    });
+    return await client.request<ConsentResult>({
+      uri: "/intake/telemetry-status",
+      tag: "telemetry-consent",
+      signal,
+    });
+  } catch {
+    return { status: "undetermined" } satisfies ConsentResult;
+  }
+});
+
+type TelemetryContext = {
+  instance: SanityInstance;
+  store: TelemetryStore<WorkbenchUserProperties> | null;
+  userProperties: WorkbenchUserProperties;
+};
+
+type TelemetryMachineEvent =
+  | { type: "telemetry.start" }
+  | { type: "telemetry.stop" };
+
+export const telemetryLogic = setup({
+  types: {
+    input: {} as TelemetryInput,
+    context: {} as TelemetryContext,
+    events: {} as TelemetryMachineEvent,
+  },
+  actors: {
+    checkConsent: checkConsentLogic,
+  },
+  guards: {
+    isConsentGranted: (_, params: { status: ConsentStatus }) =>
+      params.status === "granted",
+  },
+  actions: {
+    createStore: assign({
+      store: ({ context }) => {
+        const sessionId = createSessionId();
+        const client = getClient(context.instance, {
+          apiVersion: TELEMETRY_API_VERSION,
+        });
+        const store = createBatchedStore<WorkbenchUserProperties>(sessionId, {
+          flushInterval: FLUSH_INTERVAL_MS,
+          resolveConsent: () =>
+            client.request<{ status: ConsentStatus }>({
+              uri: "/intake/telemetry-status",
+              tag: "telemetry-consent",
+            }),
+          sendEvents: (batch: TelemetryEvent[]) =>
+            client.request({
+              uri: "/intake/batch",
+              method: "POST",
+              body: { batch },
+              tag: "telemetry.batch",
+            }),
+          sendBeacon: (batch: TelemetryEvent[]) => {
+            if (typeof navigator === "undefined") {
+              return false;
+            }
+            return navigator.sendBeacon(
+              client.getUrl("/intake/batch"),
+              JSON.stringify({ batch }),
+            );
+          },
+        });
+        store.logger.updateUserProperties(context.userProperties);
+        return store;
+      },
+    }),
+    teardownStore: ({ context }) => {
+      context.store?.end();
+    },
+  },
+}).createMachine({
+  id: "telemetry",
+  initial: "idle",
+  context: ({ input }) => ({
+    instance: input.instance,
+    store: null,
+    userProperties: {
+      version: input.version,
+      organizationId: input.organizationId,
+      environment: input.environment,
+      userAgent: input.userAgent,
+    },
+  }),
+  states: {
+    idle: {
+      on: {
+        "telemetry.start": {
+          target: "checkingConsent",
+        },
+      },
+    },
+    checkingConsent: {
+      invoke: {
+        src: "checkConsent",
+        input: ({ context }) => ({
+          instance: context.instance,
+        }),
+        onDone: [
+          {
+            guard: {
+              type: "isConsentGranted",
+              params: ({ event }) => ({
+                status: event.output.status,
+              }),
+            },
+            actions: [{ type: "createStore" }],
+            target: "active",
+          },
+          {
+            target: "denied",
+          },
+        ],
+      },
+    },
+    active: {
+      tags: ["telemetry-resolved"],
+      exit: [{ type: "teardownStore" }],
+      on: {
+        "telemetry.stop": { target: "stopped" },
+      },
+    },
+    stopped: {
+      type: "final",
+    },
+    denied: {
+      tags: ["telemetry-resolved"],
+    },
+  },
+});