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

package/src/core/applications/application.ts

@@ -0,0 +1,174 @@
+import {
+  type App,
+  type Interface,
+  InterfaceSchema,
+  type LocalApp,
+  type LocalInterface,
+  LocalInterfaceSchema,
+  type LocalPanel,
+  type LocalService,
+  type Panel,
+  type PanelComponent,
+  type Service,
+} from "@sanity/federation";
+import type { Resource as ProtocolResource } from "@sanity/message-protocol";
+
+// The interface model lives in @sanity/federation, which owns the
+// `unstable_defineView` / `unstable_defineService` contracts. Re-export it 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 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 — 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). 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/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;
+  }
+}

package/src/core/organizations.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+
+/**
+ * Organization ID schema, branded for type safety.
+ * @public
+ */
+export const OrganizationId = z.string().nonempty().brand("OrganizationId");
+
+/**
+ * Organization ID type, branded for type safety.
+ * @public
+ */
+export type OrganizationId = z.output<typeof OrganizationId>;
+
+/**
+ * Validates and brands a string as an OrganizationId.
+ * @public
+ */
+export function brandOrganizationId(id: string): OrganizationId {
+  return OrganizationId.parse(id);
+}
+
+const OrganizationMember = z.object({
+  sanityUserId: z.string(),
+  isCurrentUser: z.boolean(),
+  user: z.object({
+    id: z.string(),
+    displayName: z.string(),
+    familyName: z.string(),
+    givenName: z.string(),
+    middleName: z.string().nullable(),
+    imageUrl: z.string().nullable(),
+    email: z.string(),
+    loginProvider: z.string(),
+  }),
+  roles: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string(),
+      description: z.string().optional(),
+    }),
+  ),
+});
+
+/**
+ * @public
+ */
+export type OrganizationMember = z.output<typeof OrganizationMember>;
+
+/**
+ * Organization schema — validates and brands API responses
+ * from the `/organizations/:id` endpoint.
+ * @public
+ */
+export const Organization = z.object({
+  id: OrganizationId,
+  name: z.string(),
+  slug: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  dashboardStatus: z.enum(["enabled", "disabled"]),
+  aiFeaturesStatus: z.enum(["enabled", "disabled"]),
+  defaultRoleName: z.string().nullable(),
+});
+
+/**
+ * Represents an organization with optional members and
+ * features arrays depending on the generic parameters.
+ * - `Organization` — base fields only (default)
+ * - `Organization<true>` — includes `members`
+ * - `Organization<true, true>` — includes both
+ * @public
+ */
+export type Organization<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> = z.output<typeof Organization> &
+  (IncludeMembers extends true ? { members: OrganizationMember[] } : unknown) &
+  (IncludeFeatures extends true ? { features: string[] } : unknown);
+
+/**
+ * Validates and parses a raw API response into a branded
+ * Organization. The options control which schema is used —
+ * matching what the API returns based on query params.
+ * @public
+ */
+export function parseOrganization<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+>(
+  data: unknown,
+  options?: {
+    includeMembers?: IncludeMembers;
+    includeFeatures?: IncludeFeatures;
+  },
+): Organization<IncludeMembers, IncludeFeatures> {
+  const includeMembers = options?.includeMembers ?? true;
+  const includeFeatures = options?.includeFeatures ?? true;
+
+  const extensions = {
+    ...(includeMembers && {
+      members: z.array(OrganizationMember),
+    }),
+    ...(includeFeatures && {
+      features: z.array(z.string()),
+    }),
+  };
+
+  const schema =
+    Object.keys(extensions).length > 0
+      ? Organization.extend(extensions)
+      : Organization;
+
+  return schema.parse(data) as Organization<IncludeMembers, IncludeFeatures>;
+}