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

package/dist/system.d.ts

@@ -0,0 +1,681 @@
+import { ActorRefFromLogic } from "xstate";
+import { AuthState } from "@sanity/sdk";
+import { AuthStateType } from "@sanity/sdk";
+import { CallbackActorLogic } from "xstate";
+import { ConsentStatus } from "@sanity/telemetry";
+import { CurrentUser } from "@sanity/sdk";
+import { EventObject } from "xstate";
+import { InspectionEvent } from "xstate";
+import { MetaObject } from "xstate";
+import { NonReducibleUnknown } from "xstate";
+import { ObservableActorLogic } from "xstate";
+import { PromiseActorLogic } from "xstate";
+import { SanityInstance } from "@sanity/sdk";
+import { StateMachine } from "xstate";
+import { TelemetryStore } from "@sanity/telemetry";
+
+/**
+ * @internal
+ */
+export declare interface AuthInput extends OSBaseInput {}
+
+declare type ColorScheme = "light" | "dark";
+
+declare type ColorSchemePreference = "system" | ColorScheme;
+
+/**
+ * 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 declare function createOSOptions(input: OSInput): {
+  id: string;
+  input: OSInput;
+  inspect: (event: InspectionEvent) => void;
+};
+
+/**
+ * @internal
+ */
+export declare interface LogoutInput extends OSBaseInput {}
+
+/**
+ * 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 declare const os: StateMachine<
+  OSContext,
+  | {
+      type: "boot.auth.ready";
+    }
+  | {
+      type: "boot.auth.failed";
+    }
+  | {
+      type: "boot.telemetry.ready";
+    },
+  {
+    telemetry?:
+      | ActorRefFromLogic<
+          StateMachine<
+            {
+              instance: SanityInstance;
+              store: TelemetryStore<WorkbenchUserProperties> | null;
+              userProperties: WorkbenchUserProperties;
+            },
+            | {
+                type: "telemetry.start";
+              }
+            | {
+                type: "telemetry.stop";
+              },
+            {
+              [x: string]:
+                | ActorRefFromLogic<
+                    PromiseActorLogic<
+                      {
+                        status: ConsentStatus;
+                      },
+                      {
+                        instance: SanityInstance;
+                      },
+                      EventObject
+                    >
+                  >
+                | undefined;
+            },
+            {
+              src: "checkConsent";
+              logic: PromiseActorLogic<
+                {
+                  status: ConsentStatus;
+                },
+                {
+                  instance: SanityInstance;
+                },
+                EventObject
+              >;
+              id: string | undefined;
+            },
+            | {
+                type: "createStore";
+                params: NonReducibleUnknown;
+              }
+            | {
+                type: "teardownStore";
+                params: unknown;
+              },
+            {
+              type: "isConsentGranted";
+              params: {
+                status: ConsentStatus;
+              };
+            },
+            never,
+            "active" | "stopped" | "denied" | "idle" | "checkingConsent",
+            string,
+            TelemetryInput,
+            NonReducibleUnknown,
+            EventObject,
+            MetaObject,
+            {
+              id: "telemetry";
+              states: {
+                readonly idle: {};
+                readonly checkingConsent: {};
+                readonly active: {};
+                readonly stopped: {};
+                readonly denied: {};
+              };
+            }
+          >
+        >
+      | undefined;
+    auth?:
+      | ActorRefFromLogic<
+          StateMachine<
+            {
+              instance: SanityInstance;
+              token: string | null;
+              currentUser: CurrentUser | null;
+              error: unknown;
+            },
+            {
+              type: "auth.logout";
+            },
+            {
+              [x: string]:
+                | ActorRefFromLogic<
+                    ObservableActorLogic<AuthState, AuthInput, EventObject>
+                  >
+                | ActorRefFromLogic<
+                    PromiseActorLogic<void, LogoutInput, EventObject>
+                  >
+                | undefined;
+            },
+            | {
+                src: "authState";
+                logic: ObservableActorLogic<AuthState, AuthInput, EventObject>;
+                id: string | undefined;
+              }
+            | {
+                src: "logoutActor";
+                logic: PromiseActorLogic<void, LogoutInput, EventObject>;
+                id: string | undefined;
+              },
+            | {
+                type: "setLoggedIn";
+                params: {
+                  token: string;
+                  currentUser: CurrentUser;
+                };
+              }
+            | {
+                type: "clearAuth";
+                params: NonReducibleUnknown;
+              }
+            | {
+                type: "setError";
+                params: {
+                  error: unknown;
+                };
+              },
+            | {
+                type: "isLoggedInComplete";
+                params: {
+                  state: AuthState | undefined;
+                };
+              }
+            | {
+                type: "isAuthState";
+                params: {
+                  state: AuthState | undefined;
+                  type: AuthStateType;
+                };
+              },
+            "authTimeout",
+            "init" | AuthStateType | "logging-out",
+            "error" | "authenticating" | "authenticated",
+            AuthInput,
+            NonReducibleUnknown,
+            EventObject,
+            MetaObject,
+            {
+              id: "auth";
+              states: {
+                readonly init: {};
+                readonly "logging-in": {};
+                readonly "logged-in": {};
+                readonly "logging-out": {};
+                readonly "logged-out": {};
+                readonly error: {};
+              };
+            }
+          >
+        >
+      | undefined;
+    "system-preferences"?:
+      | ActorRefFromLogic<
+          StateMachine<
+            SystemPreferencesContext & {
+              adapter: SystemPreferencesAdapter | undefined;
+            },
+            | {
+                type: "preferredColorScheme.set";
+                preferredColorScheme: ("light" | "dark") | "system";
+              }
+            | {
+                type: "osColorScheme.set";
+                osColorScheme: "light" | "dark";
+              },
+            {
+              [x: string]:
+                | ActorRefFromLogic<
+                    CallbackActorLogic<
+                      {
+                        type: "preferredColorScheme.set";
+                        preferredColorScheme: ("light" | "dark") | "system";
+                      },
+                      SystemPreferencesAdapter | undefined,
+                      SystemPreferencesEvent
+                    >
+                  >
+                | undefined;
+            },
+            {
+              src: "adapterBridge";
+              logic: CallbackActorLogic<
+                {
+                  type: "preferredColorScheme.set";
+                  preferredColorScheme: ("light" | "dark") | "system";
+                },
+                SystemPreferencesAdapter | undefined,
+                SystemPreferencesEvent
+              >;
+              id: string | undefined;
+            },
+            | {
+                type: "setPreferredColorScheme";
+                params: {
+                  preferredColorScheme: ("light" | "dark") | "system";
+                };
+              }
+            | {
+                type: "setOsColorScheme";
+                params: {
+                  osColorScheme: "light" | "dark";
+                };
+              },
+            never,
+            never,
+            "ready",
+            string,
+            {
+              adapter?: SystemPreferencesAdapter;
+            },
+            NonReducibleUnknown,
+            EventObject,
+            MetaObject,
+            {
+              id: "system-preferences";
+              states: {
+                readonly ready: {};
+              };
+            }
+          >
+        >
+      | undefined;
+  },
+  | {
+      src: "telemetry";
+      logic: StateMachine<
+        {
+          instance: SanityInstance;
+          store: TelemetryStore<WorkbenchUserProperties> | null;
+          userProperties: WorkbenchUserProperties;
+        },
+        | {
+            type: "telemetry.start";
+          }
+        | {
+            type: "telemetry.stop";
+          },
+        {
+          [x: string]:
+            | ActorRefFromLogic<
+                PromiseActorLogic<
+                  {
+                    status: ConsentStatus;
+                  },
+                  {
+                    instance: SanityInstance;
+                  },
+                  EventObject
+                >
+              >
+            | undefined;
+        },
+        {
+          src: "checkConsent";
+          logic: PromiseActorLogic<
+            {
+              status: ConsentStatus;
+            },
+            {
+              instance: SanityInstance;
+            },
+            EventObject
+          >;
+          id: string | undefined;
+        },
+        | {
+            type: "createStore";
+            params: NonReducibleUnknown;
+          }
+        | {
+            type: "teardownStore";
+            params: unknown;
+          },
+        {
+          type: "isConsentGranted";
+          params: {
+            status: ConsentStatus;
+          };
+        },
+        never,
+        "active" | "stopped" | "denied" | "idle" | "checkingConsent",
+        string,
+        TelemetryInput,
+        NonReducibleUnknown,
+        EventObject,
+        MetaObject,
+        {
+          id: "telemetry";
+          states: {
+            readonly idle: {};
+            readonly checkingConsent: {};
+            readonly active: {};
+            readonly stopped: {};
+            readonly denied: {};
+          };
+        }
+      >;
+      id: "telemetry";
+    }
+  | {
+      src: "auth";
+      logic: StateMachine<
+        {
+          instance: SanityInstance;
+          token: string | null;
+          currentUser: CurrentUser | null;
+          error: unknown;
+        },
+        {
+          type: "auth.logout";
+        },
+        {
+          [x: string]:
+            | ActorRefFromLogic<
+                ObservableActorLogic<AuthState, AuthInput, EventObject>
+              >
+            | ActorRefFromLogic<
+                PromiseActorLogic<void, LogoutInput, EventObject>
+              >
+            | undefined;
+        },
+        | {
+            src: "authState";
+            logic: ObservableActorLogic<AuthState, AuthInput, EventObject>;
+            id: string | undefined;
+          }
+        | {
+            src: "logoutActor";
+            logic: PromiseActorLogic<void, LogoutInput, EventObject>;
+            id: string | undefined;
+          },
+        | {
+            type: "setLoggedIn";
+            params: {
+              token: string;
+              currentUser: CurrentUser;
+            };
+          }
+        | {
+            type: "clearAuth";
+            params: NonReducibleUnknown;
+          }
+        | {
+            type: "setError";
+            params: {
+              error: unknown;
+            };
+          },
+        | {
+            type: "isLoggedInComplete";
+            params: {
+              state: AuthState | undefined;
+            };
+          }
+        | {
+            type: "isAuthState";
+            params: {
+              state: AuthState | undefined;
+              type: AuthStateType;
+            };
+          },
+        "authTimeout",
+        "init" | AuthStateType | "logging-out",
+        "error" | "authenticating" | "authenticated",
+        AuthInput,
+        NonReducibleUnknown,
+        EventObject,
+        MetaObject,
+        {
+          id: "auth";
+          states: {
+            readonly init: {};
+            readonly "logging-in": {};
+            readonly "logged-in": {};
+            readonly "logging-out": {};
+            readonly "logged-out": {};
+            readonly error: {};
+          };
+        }
+      >;
+      id: "auth";
+    }
+  | {
+      src: "systemPreferences";
+      logic: StateMachine<
+        SystemPreferencesContext & {
+          adapter: SystemPreferencesAdapter | undefined;
+        },
+        | {
+            type: "preferredColorScheme.set";
+            preferredColorScheme: ("light" | "dark") | "system";
+          }
+        | {
+            type: "osColorScheme.set";
+            osColorScheme: "light" | "dark";
+          },
+        {
+          [x: string]:
+            | ActorRefFromLogic<
+                CallbackActorLogic<
+                  {
+                    type: "preferredColorScheme.set";
+                    preferredColorScheme: ("light" | "dark") | "system";
+                  },
+                  SystemPreferencesAdapter | undefined,
+                  SystemPreferencesEvent
+                >
+              >
+            | undefined;
+        },
+        {
+          src: "adapterBridge";
+          logic: CallbackActorLogic<
+            {
+              type: "preferredColorScheme.set";
+              preferredColorScheme: ("light" | "dark") | "system";
+            },
+            SystemPreferencesAdapter | undefined,
+            SystemPreferencesEvent
+          >;
+          id: string | undefined;
+        },
+        | {
+            type: "setPreferredColorScheme";
+            params: {
+              preferredColorScheme: ("light" | "dark") | "system";
+            };
+          }
+        | {
+            type: "setOsColorScheme";
+            params: {
+              osColorScheme: "light" | "dark";
+            };
+          },
+        never,
+        never,
+        "ready",
+        string,
+        {
+          adapter?: SystemPreferencesAdapter;
+        },
+        NonReducibleUnknown,
+        EventObject,
+        MetaObject,
+        {
+          id: "system-preferences";
+          states: {
+            readonly ready: {};
+          };
+        }
+      >;
+      id: "system-preferences";
+    },
+  | {
+      type: "raiseAuthReady";
+      params: NonReducibleUnknown;
+    }
+  | {
+      type: "raiseAuthFailed";
+      params: NonReducibleUnknown;
+    }
+  | {
+      type: "raiseTelemetryReady";
+      params: NonReducibleUnknown;
+    }
+  | {
+      type: "startTelemetry";
+      params: NonReducibleUnknown;
+    },
+  {
+    type: "hasTag";
+    params: {
+      hasTag: boolean;
+    };
+  },
+  never,
+  | "running"
+  | {
+      booting: "error" | "done" | "telemetry" | "auth";
+    },
+  string,
+  OSInput,
+  NonReducibleUnknown,
+  EventObject,
+  MetaObject,
+  {
+    id: "os";
+    states: {
+      readonly booting: {
+        states: {
+          readonly auth: {};
+          readonly telemetry: {};
+          readonly error: {};
+          readonly done: {};
+        };
+      };
+      readonly running: {};
+    };
+  }
+>;
+
+/**
+ * The base inputs for the OS machine.
+ * @internal
+ */
+declare interface OSBaseInput extends Pick<OSContext, "instance"> {}
+
+declare type OSContext = {
+  instance: SanityInstance;
+  userProperties: WorkbenchUserProperties;
+  systemPreferencesAdapter: SystemPreferencesAdapter | undefined;
+};
+
+declare type OSInput = WorkbenchUserProperties & {
+  systemPreferencesAdapter?: SystemPreferencesAdapter;
+};
+
+/**
+ * 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 declare 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;
+};
+
+/**
+ * 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 declare 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;
+};
+
+/**
+ * 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 declare type SystemPreferencesEvent =
+  | {
+      type: "preferredColorScheme.set";
+      preferredColorScheme: ColorSchemePreference;
+    }
+  | {
+      type: "osColorScheme.set";
+      osColorScheme: ColorScheme;
+    };
+
+/**
+ * @internal
+ */
+export declare interface TelemetryInput
+  extends OSBaseInput, WorkbenchUserProperties {}
+
+/**
+ * @public
+ */
+export declare type WorkbenchUserProperties = {
+  version: string;
+  organizationId: string;
+  environment: string;
+  userAgent: string;
+};
+
+export {};