@sanity/workbench 0.1.0-alpha.1 → 0.1.0-alpha.10

package/src/core/canvases.ts

@@ -0,0 +1,91 @@
+import type { CanvasResource as ProtocolCanvasResource } from "@sanity/message-protocol";
+import { z } from "zod";
+
+import { AbstractApplication } from "./applications/application";
+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.${import.meta.env.VITE_SANITY_DOMAIN}/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/index.ts

@@ -0,0 +1,12 @@
+export * from "./applications/application";
+export * from "./applications/application-list";
+export * from "./canvases";
+export * from "./config";
+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,92 @@
+/**
+ * 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;
+}
+
+const LEVELS: readonly LogLevel[] = ["none", "error", "warn", "info", "debug"];
+
+interface LoggerOptions {
+  namespace?: LogNamespace;
+  context?: LogContext;
+  logLevel?: LogLevel;
+}
+
+/**
+ * @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),
+  };
+}
+
+/**
+ * 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,92 @@
+import type { MediaResource as ProtocolMediaResource } from "@sanity/message-protocol";
+import { z } from "zod";
+
+import { AbstractApplication } from "./applications/application";
+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.${import.meta.env.VITE_SANITY_DOMAIN}/${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(),
+});
+
+/**
+ * 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>;
+}

package/src/core/projects.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+
+import { OrganizationId } from "./organizations";
+
+/**
+ * Project ID schema, branded for type safety.
+ * @public
+ */
+export const ProjectId = z.string().nonempty().brand("ProjectId");
+
+/**
+ * Project ID type, branded for type safety.
+ * @public
+ */
+export type ProjectId = z.output<typeof ProjectId>;
+
+/**
+ * Validates and brands a string as a ProjectId.
+ * @public
+ */
+export function brandProjectId(id: string): ProjectId {
+  return ProjectId.parse(id);
+}
+
+const ProjectMember = z.object({
+  id: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  isCurrentUser: z.boolean(),
+  isRobot: z.boolean(),
+  roles: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string(),
+      description: z.string(),
+    }),
+  ),
+});
+
+/**
+ * @public
+ */
+export type ProjectMember = z.output<typeof ProjectMember>;
+
+/**
+ * Project schema — validates and brands API responses
+ * from the `/projects/:id` endpoint.
+ * @public
+ */
+export const Project = z.object({
+  id: ProjectId,
+  displayName: z.string(),
+  studioHost: z.string().nullable(),
+  organizationId: OrganizationId,
+  metadata: z.object({
+    color: z.string().optional(),
+    externalStudioHost: z.string().optional(),
+    initialTemplate: z.string().optional(),
+    cliInitializedAt: z.string().optional(),
+    integration: z.literal(["manage", "cli"]),
+  }),
+  isBlocked: z.boolean(),
+  isDisabled: z.boolean(),
+  isDisabledByUser: z.boolean(),
+  activityFeedEnabled: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Represents a Sanity project with optional members and
+ * features arrays depending on the generic parameters.
+ * By default, neither members nor features are included.
+ * - `Project` — base fields only (default)
+ * - `Project<true>` — includes `members`
+ * - `Project<true, true>` — includes both
+ * @public
+ */
+export type Project<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> = z.output<typeof Project> &
+  (IncludeMembers extends true ? { members: ProjectMember[] } : unknown) &
+  (IncludeFeatures extends true ? { features: string[] } : unknown);
+
+/**
+ * Validates and parses a raw API response into a branded
+ * Project. The options control which schema is used —
+ * matching what the API returns based on query params.
+ * @public
+ */
+export function parseProject<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+>(
+  data: unknown,
+  options?: {
+    includeMembers?: IncludeMembers;
+    includeFeatures?: IncludeFeatures;
+  },
+): Project<IncludeMembers, IncludeFeatures> {
+  const includeMembers = options?.includeMembers ?? true;
+  const includeFeatures = options?.includeFeatures ?? true;
+
+  const extensions = {
+    ...(includeMembers && { members: z.array(ProjectMember) }),
+    ...(includeFeatures && { features: z.array(z.string()) }),
+  };
+
+  const schema =
+    Object.keys(extensions).length > 0 ? Project.extend(extensions) : Project;
+
+  return schema.parse(data) as Project<IncludeMembers, IncludeFeatures>;
+}

package/src/core/shared/urls.ts

@@ -0,0 +1,129 @@
+/**
+ * Joins multiple path segments into a single path string.
+ * Handles null, undefined, and URL objects gracefully.
+ *
+ * @public
+ * @param paths - An array of path segments to join.
+ * @returns A single joined path string.
+ */
+export const joinUrlPaths = (
+  ...paths: Array<string | URL | null | undefined>
+): string => {
+  let nextPath = null;
+
+  const safeJoinSegments = (
+    segment1: string | null | undefined,
+    segment2: string | null | undefined,
+  ): string => {
+    if (!segment1) {
+      if (!segment2) {
+        return "";
+      }
+
+      return segment2;
+    }
+
+    if (!segment2) {
+      return segment1;
+    }
+
+    if (segment1.endsWith("/") && segment2.startsWith("/")) {
+      return segment1 + segment2.slice(1);
+    }
+
+    if (segment1.endsWith("/") || segment2.startsWith("/")) {
+      return segment1 + segment2;
+    }
+
+    return `${segment1}/${segment2}`;
+  };
+
+  const validPaths = paths.filter(
+    (path) => path !== null && path !== undefined,
+  );
+
+  for (const path of validPaths) {
+    nextPath = safeJoinSegments(
+      nextPath,
+      path instanceof URL ? path.pathname : path,
+    );
+  }
+
+  return nextPath ?? "";
+};
+
+/**
+ * Returns a normalized path by ensuring it starts with a single leading slash
+ * and does not end with a trailing slash (unless it's the root path).
+ */
+export function normalizePath(pathname: string): string {
+  if (!pathname.startsWith("/")) {
+    pathname = `/${pathname}`;
+  }
+
+  if (pathname !== "/" && pathname.endsWith("/")) {
+    pathname = pathname.slice(0, -1);
+  }
+
+  return pathname;
+}
+
+/**
+ * The pathname, search, and hash values of a URL.
+ */
+interface Path {
+  /**
+   * A URL pathname, beginning with a /.
+   */
+  pathname: string;
+  /**
+   * A URL search string, beginning with a ?.
+   */
+  search: string;
+  /**
+   * A URL fragment identifier, beginning with a #.
+   */
+  hash: string;
+}
+
+/**
+ * Parses a string URL path into its separate pathname, search, and hash components.
+ */
+export function parsePath(path: string): Partial<Path> {
+  let parsedPath: Partial<Path> = {};
+
+  if (path) {
+    let hashIndex = path.indexOf("#");
+    if (hashIndex >= 0) {
+      parsedPath.hash = path.substring(hashIndex);
+      path = path.substring(0, hashIndex);
+    }
+
+    let searchIndex = path.indexOf("?");
+    if (searchIndex >= 0) {
+      parsedPath.search = path.substring(searchIndex);
+      path = path.substring(0, searchIndex);
+    }
+
+    if (path) {
+      parsedPath.pathname = path;
+    }
+  }
+
+  return parsedPath;
+}
+
+/**
+ * Creates a string URL path from the given pathname, search, and hash components.
+ */
+export function createPath({
+  pathname = "/",
+  search = "",
+  hash = "",
+}: Partial<Path>) {
+  if (search && search !== "?")
+    pathname += search.charAt(0) === "?" ? search : `?${search}`;
+  if (hash && hash !== "#")
+    pathname += hash.charAt(0) === "#" ? hash : `#${hash}`;
+  return pathname;
+}