@sanity/workbench 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/core/applications/application.ts

@@ -0,0 +1,177 @@
+import type { Resource as ProtocolResource } from "@sanity/message-protocol";
+
+import {
+  type App,
+  type DockGroup,
+  type Interface,
+  InterfaceSchema,
+  type LocalApp,
+  type LocalInterface,
+  LocalInterfaceSchema,
+  type LocalPanel,
+  type LocalService,
+  type Panel,
+  type PanelComponent,
+  type Service,
+} from "./interface";
+
+// The consumer/wire half of the interface model lives in `./interface`. The
+// authoring half (`unstable_defineView` / `unstable_defineService`) lives with
+// the CLI build helpers. Re-export the wire model so it stays part of the
+// workbench app-model surface. `Panel`/`LocalPanel`, `Service`/`LocalService`,
+// and `App`/`LocalApp` are the panel-, worker-, and app-typed subsets.
+export {
+  type App,
+  type DockGroup,
+  type Interface,
+  InterfaceSchema,
+  type LocalApp,
+  type LocalInterface,
+  LocalInterfaceSchema,
+  type LocalPanel,
+  type LocalService,
+  type Panel,
+  type PanelComponent,
+  type Service,
+};
+
+/**
+ * @public
+ */
+export type AbstractApplicationType =
+  | "studio"
+  | "coreApp"
+  | "canvas"
+  | "media-library"
+  | "workspace";
+
+/**
+ * @public
+ */
+export abstract class AbstractApplication<
+  TType extends AbstractApplicationType,
+  TProtocolResource extends ProtocolResource = Extract<
+    ProtocolResource,
+    { type: TType }
+  >,
+> {
+  readonly type: TType;
+
+  constructor(type: TType) {
+    this.type = type;
+  }
+
+  /**
+   * The in-app route this application navigates to, or `null` when it isn't
+   * navigable as a full-page app (US5, spec 002-workbench-extension-api — e.g. an SDK app with no `app` view).
+   * The dock renders a navigable item only for a non-null `href`; the app
+   * routes 404 a `null`-href app on direct visit.
+   */
+  abstract get href(): string | null;
+
+  abstract get title(): string;
+
+  abstract get id(): string;
+
+  /**
+   * Whether the application is federated or not. This is used to determine
+   * if the application should be rendered in an iframe or not.
+   */
+  abstract get isFederated(): boolean;
+
+  /**
+   * Whether the application is served by a local CLI dev server rather than a
+   * deployed remote. Defaults to `false`; user applications flip this when
+   * constructed from a `LocalUserApplication` payload.
+   */
+  get isLocal(): boolean {
+    return false;
+  }
+
+  abstract get url(): URL;
+
+  /**
+   * Interfaces the application exposes (e.g. dock panels). Defaults to none;
+   * user applications surface what they declared via `unstable_defineApp`.
+   */
+  get interfaces(): readonly LocalInterface[] {
+    return [];
+  }
+
+  /**
+   * Whether the application has a navigable full-page `app` view (US5, spec 002-workbench-extension-api). Defaults
+   * to `true` — studios, Canvas, and Media Library are always navigable. An SDK
+   * app overrides this to derive it from whether it declares an `app` interface.
+   */
+  get hasAppView(): boolean {
+    return true;
+  }
+
+  /**
+   * Federation module id of the app's full-page view (`${id}/App`), or `null`
+   * when it can't be federation-loaded: the app isn't federated (Canvas, Media
+   * Library, deployed apps shown in an iframe) or has no app view. Only a
+   * non-null `moduleId` is fetched and rendered by the remotes machine.
+   */
+  get moduleId(): string | null {
+    return this.isFederated && this.hasAppView ? `${this.id}/App` : null;
+  }
+
+  /**
+   * Federation module id of one of this app's panel view components, or `null`
+   * when the app isn't federated (a non-federated app's panels can't be loaded
+   * as remotes).
+   */
+  resolveViewModuleId(
+    view: LocalPanel,
+    component: PanelComponent,
+  ): string | null {
+    return this.isFederated
+      ? `${this.id}/views/${view.name}/${component}`
+      : null;
+  }
+
+  get initials(): string {
+    const SYMBOLS = /[^\p{Alpha}\p{N}\p{White_Space}]/gu;
+    const WHITESPACE = /\p{White_Space}+/u;
+    const ALPHANUMERIC_SEGMENTS = /(\p{N}+|\p{Alpha}+)/gu;
+    const IS_NUMERIC = /^\p{N}+$/u;
+
+    if (!this.title) return "";
+
+    const namesArray = this.title
+      .replace(SYMBOLS, "")
+      .split(WHITESPACE)
+      .filter(Boolean);
+
+    if (namesArray.length === 0) return "";
+
+    if (namesArray.length === 1) {
+      const word = namesArray[0];
+      const segments = word.match(ALPHANUMERIC_SEGMENTS) || [];
+
+      if (segments.length === 0) return "";
+      if (segments.length === 1) {
+        if (word.length === 1) {
+          return word.toUpperCase();
+        }
+
+        if (IS_NUMERIC.test(word)) {
+          return `${word.charAt(0)}${word.charAt(1)}`.toUpperCase();
+        }
+
+        return word.charAt(0).toUpperCase();
+      }
+
+      return `${segments[0]!.charAt(0)}${segments[1].charAt(0)}`.toUpperCase();
+    }
+
+    return `${namesArray[0].charAt(0)}${namesArray[namesArray.length - 1].charAt(0)}`.toUpperCase();
+  }
+
+  /**
+   * Converts the resource to a protocol resource that comlink expects
+   * for backwards compatibility with the old API format.
+   */
+  abstract toProtocolResource(): TProtocolResource;
+}

package/src/core/applications/interface.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+
+/**
+ * The consumer/wire half of the workbench extension interface model — the
+ * records the application service returns and the workbench renders from.
+ *
+ * The authoring half (`unstable_defineView` / `unstable_defineService` and the
+ * `*DeclarationSchema`s) lives with the CLI build helpers, not here: this module
+ * only models the wire shape the workbench consumes. Field names are snake_case
+ * to match the application service's JSON.
+ */
+
+/**
+ * Fields every interface record carries. Per-type schemas add their
+ * `interface_type` discriminator on top.
+ */
+const interfaceBaseFields = {
+  id: z.string(),
+  deployment_id: z.string(),
+  name: z.string(),
+  entry_point: z.string(),
+};
+
+/**
+ * The `panel` interface record — a view that renders in the dock.
+ */
+const PanelInterfaceSchema = z.object({
+  ...interfaceBaseFields,
+  interface_type: z.literal("panel"),
+});
+
+/**
+ * The `worker` interface record — a background service the workbench runs.
+ */
+const WorkerInterfaceSchema = z.object({
+  ...interfaceBaseFields,
+  interface_type: z.literal("worker"),
+});
+
+/**
+ * The `app` interface record — an application's navigable full-page view. Its
+ * presence is the sole signal a branded app is navigable (US5, spec
+ * 002-workbench-extension-api).
+ */
+const AppInterfaceSchema = z.object({
+  ...interfaceBaseFields,
+  interface_type: z.literal("app"),
+});
+
+/**
+ * An interface record discriminated on `interface_type` — a `panel` renders in
+ * the dock, a `worker` runs a background service, an `app` is the navigable
+ * full-page view.
+ * @public
+ */
+export const InterfaceSchema = z.discriminatedUnion("interface_type", [
+  PanelInterfaceSchema,
+  WorkerInterfaceSchema,
+  AppInterfaceSchema,
+]);
+
+/** @public */
+export type Interface = z.output<typeof InterfaceSchema>;
+
+/**
+ * An {@link Interface} without the service-assigned `id`/`deployment_id` a local
+ * dev server can't provide — the shape the workbench renders from.
+ * @public
+ */
+export const LocalInterfaceSchema = z.discriminatedUnion("interface_type", [
+  PanelInterfaceSchema.omit({ id: true, deployment_id: true }),
+  WorkerInterfaceSchema.omit({ id: true, deployment_id: true }),
+  AppInterfaceSchema.omit({ id: true, deployment_id: true }),
+]);
+
+/** @public */
+export type LocalInterface = z.output<typeof LocalInterfaceSchema>;
+
+/** The interface record for a given `interface_type`. @public */
+export type InterfaceOfType<T extends Interface["interface_type"]> = Extract<
+  Interface,
+  { interface_type: T }
+>;
+
+/** The {@link InterfaceOfType} counterpart without `id`/`deployment_id`. @public */
+export type LocalInterfaceOfType<T extends LocalInterface["interface_type"]> =
+  Extract<LocalInterface, { interface_type: T }>;
+
+/** @public */
+export type Panel = InterfaceOfType<"panel">;
+/** @public */
+export type LocalPanel = LocalInterfaceOfType<"panel">;
+
+/**
+ * A service an application runs — the worker-typed interface record. `Service`/
+ * `LocalService` are the worker-typed subset of the interface model.
+ * @public
+ */
+export type Service = InterfaceOfType<"worker">;
+/** @public */
+export type LocalService = LocalInterfaceOfType<"worker">;
+
+/**
+ * The navigable full-page view — its presence is the sole signal a branded app
+ * is navigable (US5, spec 002-workbench-extension-api).
+ * @public
+ */
+export type App = InterfaceOfType<"app">;
+/** @public */
+export type LocalApp = LocalInterfaceOfType<"app">;
+
+/**
+ * A panel's view-component slots, in render order — each its own federation
+ * island (`${id}/views/${name}/${component}`). The authoring counterpart that
+ * drives the build's per-slot codegen lives with the CLI define helpers.
+ * @public
+ */
+export type PanelComponent = "title" | "panel";
+
+/**
+ * Where an application docks. The manifest's `group` value the workbench reads
+ * to place an app in the dock; the authoring counterpart that validates it on
+ * `unstable_defineApp` lives with the CLI define helpers.
+ * @public
+ */
+export type DockGroup = "dock.system" | "dock.applications" | "dock.user";

package/src/core/canvases.ts

@@ -0,0 +1,92 @@
+import type { CanvasResource as ProtocolCanvasResource } from "@sanity/message-protocol";
+import { z } from "zod";
+
+import { AbstractApplication } from "./applications/application";
+import { getSanityDomain } from "./env";
+import { OrganizationId } from "./organizations";
+
+/**
+ * Canvas ID schema, branded for type safety.
+ * @public
+ */
+const CanvasId = z.string().nonempty().brand("CanvasId");
+
+/**
+ * Canvas ID type, branded for type safety.
+ * @public
+ */
+export type CanvasId = z.output<typeof CanvasId>;
+
+/**
+ * Validates and brands a string as a CanvasId.
+ * @public
+ */
+export function brandCanvasId(id: string): CanvasId {
+  return CanvasId.parse(id);
+}
+
+const Canvas = z.object({
+  id: CanvasId,
+  organizationId: OrganizationId,
+  status: z.enum(["active", "provisioning"]),
+});
+
+/**
+ * Represents a Canvas resource as returned from the API.
+ * @public
+ */
+export type Canvas = z.output<typeof Canvas>;
+
+/**
+ * Validates and parses a raw API response into a branded
+ * Canvas.
+ * @public
+ */
+export function parseCanvas(data: unknown): Canvas {
+  return Canvas.parse(data);
+}
+
+/**
+ * Whilst the constructor takes an organization's canvas resource the existance
+ * therefore implies the organization has access to the canvas application which
+ * is what workbench most importantly wants to know.
+ * @public
+ */
+export class CanvasApplication extends AbstractApplication<"canvas"> {
+  readonly canvas: Canvas;
+
+  constructor(canvas: Canvas) {
+    super("canvas");
+
+    this.canvas = canvas;
+  }
+
+  get id(): CanvasId {
+    return this.canvas.id;
+  }
+
+  get href(): string {
+    return "canvas";
+  }
+
+  get title(): string {
+    return "Canvas";
+  }
+
+  get url(): URL {
+    return new URL(
+      `https://canvas.${getSanityDomain()}/o/${this.canvas.organizationId}`,
+    );
+  }
+
+  get isFederated(): boolean {
+    return false;
+  }
+
+  toProtocolResource(): ProtocolCanvasResource {
+    return {
+      type: "canvas",
+      id: this.id,
+    } satisfies ProtocolCanvasResource;
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,34 @@
+import type { OrganizationId } from "./organizations";
+
+/**
+ * Workbench configuration.
+ *
+ * @public
+ */
+interface Config {
+  /**
+   * The organization ID to use when rendering the workbench.
+   */
+  organizationId?: string;
+}
+
+/**
+ * The resolved configuration after processing
+ * and validating the provided config.
+ *
+ * @public
+ */
+type ResolvedConfig = Omit<Config, "organizationId"> & {
+  organizationId: OrganizationId;
+};
+
+/**
+ * Options for rendering a remote module, such as a user application.
+ *
+ * @public
+ */
+interface RemoteModuleRenderOptions {
+  reactStrictMode?: boolean;
+}
+
+export type { Config, ResolvedConfig, RemoteModuleRenderOptions };

package/src/core/env.ts

@@ -0,0 +1,43 @@
+declare const __SANITY_STAGING__: boolean | undefined;
+
+/**
+ * Returns the Sanity domain based on the `__SANITY_STAGING__` runtime-time flag.
+ * If the flag is set to `true`, the staging domain is returned.
+ * Otherwise, the production domain is returned.
+ *
+ * @public
+ */
+export function getSanityDomain(): string {
+  if (getSanityEnv() === "staging") {
+    return "sanity.work";
+  }
+  return "sanity.io";
+}
+
+/**
+ * Returns the API host based on the `__SANITY_STAGING__` runtime-time flag.
+ * If the flag is set to `true`, the staging API host is returned.
+ * Otherwise, the production API host is returned.
+ *
+ * @public
+ */
+export function getApiHost(): string | undefined {
+  return `https://api.${getSanityDomain()}`;
+}
+
+/**
+ * Returns the current Sanity environment based on the `__SANITY_STAGING__` runtime-time flag.
+ * If the flag is set to `true`, "staging" is returned.
+ * Otherwise, "production" is returned.
+ *
+ * @public
+ */
+export function getSanityEnv(): "staging" | "production" {
+  if (
+    typeof __SANITY_STAGING__ !== "undefined" &&
+    __SANITY_STAGING__ === true
+  ) {
+    return "staging";
+  }
+  return "production";
+}

package/src/core/index.ts

@@ -0,0 +1,13 @@
+export * from "./applications/application";
+export * from "./applications/application-list";
+export * from "./canvases";
+export * from "./config";
+export * from "./env";
+export * from "./log";
+export * from "./media-libraries";
+export * from "./organizations";
+export * from "./projects";
+export { joinUrlPaths } from "./shared/urls";
+export * from "./user-applications/core-app";
+export * from "./user-applications/studios";
+export * from "./user-applications/user-application";

package/src/core/log/index.ts

@@ -0,0 +1,125 @@
+/**
+ * Log levels in order of verbosity (least to most)
+ * - none: Silent
+ * - error: Critical failures that prevent operation
+ * - warn: Issues that may cause problems but don't stop execution
+ * - info: High-level informational messages (default)
+ * - debug: Detailed debugging information (maintainer level)
+ * - trace: Very detailed tracing — sets `internal: true` on context
+ * @public
+ */
+export type LogLevel = "none" | "error" | "warn" | "info" | "debug";
+
+/**
+ * Namespaces organize logs by functional domain.
+ * @internal
+ */
+export type LogNamespace = string;
+
+type LogContext = { [key: string]: unknown };
+
+/**
+ * @public
+ */
+export interface Logger {
+  error: (message: string, context?: LogContext) => void;
+  warn: (message: string, context?: LogContext) => void;
+  info: (message: string, context?: LogContext) => void;
+  debug: (message: string, context?: LogContext) => void;
+  child: (domain: string, context?: LogContext) => Logger;
+}
+
+const LEVELS: readonly LogLevel[] = ["none", "error", "warn", "info", "debug"];
+
+interface LoggerOptions {
+  namespace?: LogNamespace;
+  context?: LogContext;
+  logLevel?: LogLevel;
+}
+
+/**
+ * Creates a leveled logger with an optional namespace prefix and bound
+ * context. Calls below the configured `logLevel` are suppressed; `"none"`
+ * silences the logger entirely.
+ *
+ * Use {@link Logger.child} to derive a sub-logger with an extended namespace
+ * (e.g. `parent:domain`) that inherits the parent's level and merges its
+ * bound context.
+ *
+ * @param options - Logger configuration.
+ * @param options.namespace - Prepended to every message in `[brackets]`.
+ * @param options.context - Bound context merged with per-call context.
+ *   Per-call keys win on conflict.
+ * @param options.logLevel - Maximum verbosity to emit. Default `"info"`.
+ *
+ * @example
+ * ```ts
+ * const log = createLogger({ namespace: "checkout", logLevel: "debug" });
+ * log.info("placed", { orderId: "abc" });
+ * // → [checkout] placed { orderId: "abc" }
+ *
+ * const auth = log.child("auth", { tenant: "acme" });
+ * auth.warn("token expiring");
+ * // → [checkout:auth] token expiring { tenant: "acme" }
+ * ```
+ *
+ * @public
+ */
+export function createLogger({
+  namespace,
+  context: baseContext,
+  logLevel = "info",
+}: LoggerOptions = {}): Logger {
+  function isLevelEnabled(level: LogLevel): boolean {
+    return LEVELS.indexOf(level) <= LEVELS.indexOf(logLevel);
+  }
+
+  function logAtLevel(
+    level: LogLevel,
+    message: string,
+    context?: LogContext,
+  ): void {
+    if (!isLevelEnabled(level)) return;
+
+    const merged =
+      (baseContext ?? context) ? { ...baseContext, ...context } : undefined;
+    const args: unknown[] = [
+      ...(namespace ? [`[${namespace}]`] : []),
+      message,
+      ...(merged ? [merged] : []),
+    ];
+
+    if (level === "error") console.error(...args);
+    else if (level === "warn") console.warn(...args);
+    // oxlint-disable-next-line no-console
+    else if (level === "info") console.info(...args);
+    // oxlint-disable-next-line no-console
+    else console.debug(...args);
+  }
+
+  return {
+    error: (message, context) => logAtLevel("error", message, context),
+    warn: (message, context) => logAtLevel("warn", message, context),
+    info: (message, context) => logAtLevel("info", message, context),
+    debug: (message, context) => logAtLevel("debug", message, context),
+    child: (domain, context) =>
+      createLogger({
+        logLevel,
+        namespace: namespace ? `${namespace}:${domain}` : domain,
+        context:
+          baseContext || context ? { ...baseContext, ...context } : undefined,
+      }),
+  };
+}
+
+/**
+ * Shared workbench logger instance. Use this from both the workbench host
+ * and its remotes so lifecycle and diagnostic logs appear under a single
+ * namespace.
+ *
+ * @public
+ */
+export const logger: Logger = createLogger({
+  namespace: "sanity-workbench",
+  logLevel: "debug",
+});

package/src/core/media-libraries.ts

@@ -0,0 +1,93 @@
+import type { MediaResource as ProtocolMediaResource } from "@sanity/message-protocol";
+import { z } from "zod";
+
+import { AbstractApplication } from "./applications/application";
+import { getSanityDomain } from "./env";
+import { OrganizationId } from "./organizations";
+
+/**
+ * Canvas ID schema, branded for type safety.
+ * @public
+ */
+const MediaLibraryId = z.string().nonempty().brand("MediaLibraryId");
+
+/**
+ * MediaLibrary ID type, branded for type safety.
+ * @public
+ */
+export type MediaLibraryId = z.output<typeof MediaLibraryId>;
+
+/**
+ * Validates and brands a string as a MediaLibraryId.
+ * @public
+ */
+export function brandMediaLibraryId(id: string): MediaLibraryId {
+  return MediaLibraryId.parse(id);
+}
+
+const MediaLibrary = z.object({
+  id: MediaLibraryId,
+  organizationId: OrganizationId,
+  status: z.enum(["active", "provisioning"]),
+  aclMode: z.enum(["private", "public"]),
+});
+
+/**
+ * Represents a MediaLibrary resource as returned from the API.
+ * @public
+ */
+export type MediaLibrary = z.output<typeof MediaLibrary>;
+
+/**
+ * Validates and parses a raw API response into a branded
+ * MediaLibrary.
+ * @public
+ */
+export function parseMediaLibrary(data: unknown): MediaLibrary {
+  return MediaLibrary.parse(data);
+}
+
+/**
+ * Whilst the constructor takes an organization's media library resource the existance
+ * therefore implies the organization has access to the media library application which
+ * is what workbench most importantly wants to know.
+ * @public
+ */
+export class MediaLibraryApplication extends AbstractApplication<"media-library"> {
+  readonly library: MediaLibrary;
+
+  constructor(library: MediaLibrary) {
+    super("media-library");
+
+    this.library = library;
+  }
+
+  get id(): string {
+    return this.library.id;
+  }
+
+  get href(): string {
+    return "media";
+  }
+
+  get title(): string {
+    return "Media Library";
+  }
+
+  get isFederated(): boolean {
+    return false;
+  }
+
+  get url(): URL {
+    return new URL(
+      `https://media.${getSanityDomain()}/${this.library.organizationId}`,
+    );
+  }
+
+  toProtocolResource(): ProtocolMediaResource {
+    return {
+      type: "media-library",
+      id: this.id,
+    } satisfies ProtocolMediaResource;
+  }
+}