docs(sanity): update sanity package tsdocs (#4608)

* docs: add docs to StudioLayout

* chore(sanity): add docs for interfaces

* docs(sanity): add or update docs for sanity package

* chore: upgrade @sanity/ui and @sanity/tsdoc

* docs(core): hide BaseFormNode from tsdoc

* docs(core): update docs based on feedback

---------

Co-authored-by: Binoy Patel <[email protected]>

dev/design-studio/package.json

@@ -33,7 +33,7 @@
     "@sanity/color": "^2.1.20",
     "@sanity/icons": "^2.4.0",
     "@sanity/logos": "^2.0.2",
-    "@sanity/ui": "^1.6.0",
+    "@sanity/ui": "^1.7.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "sanity": "3.14.2",

dev/test-studio/package.json

@@ -24,9 +24,9 @@
     "@sanity/icons": "^2.4.0",
     "@sanity/image-url": "^1.0.2",
     "@sanity/portable-text-editor": "3.14.2",
-    "@sanity/tsdoc": "1.0.0-alpha.34",
+    "@sanity/tsdoc": "1.0.0-alpha.38",
     "@sanity/types": "3.14.2",
-    "@sanity/ui": "^1.6.0",
+    "@sanity/ui": "^1.7.2",
     "@sanity/ui-workshop": "^1.0.0",
     "@sanity/util": "3.14.2",
     "@sanity/uuid": "^3.0.1",

examples/ecommerce-studio/package.json

@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@sanity/cli": "3.14.2",
-    "@sanity/ui": "^1.6.0",
+    "@sanity/ui": "^1.7.2",
     "react": "^18.2.0",
     "react-barcode": "^1.4.1",
     "react-dom": "^18.2.0",

package.json

@@ -87,7 +87,7 @@
     "@playwright/test": "^1.31.2",
     "@sanity/client": "^6.1.5",
     "@sanity/pkg-utils": "^2.3.1",
-    "@sanity/tsdoc": "1.0.0-alpha.34",
+    "@sanity/tsdoc": "1.0.0-alpha.38",
     "@sanity/uuid": "^3.0.1",
     "@types/jest": "^27.0.3",
     "@types/mkdirp": "^1.0.2",

packages/@sanity/portable-text-editor/package.json

@@ -75,7 +75,7 @@
     "slate": "0.81.1"
   },
   "devDependencies": {
-    "@sanity/ui": "^1.6.0",
+    "@sanity/ui": "^1.7.2",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^13.4.0",
     "@types/debug": "^4.1.5",

packages/@sanity/vision/package.json

@@ -67,7 +67,7 @@
     "@rexxars/react-split-pane": "^0.1.93",
     "@sanity/color": "^2.1.20",
     "@sanity/icons": "^2.4.0",
-    "@sanity/ui": "^1.6.0",
+    "@sanity/ui": "^1.7.2",
     "@uiw/react-codemirror": "^4.11.4",
     "hashlru": "^2.3.0",
     "is-hotkey": "^0.1.6",

packages/sanity/package.json

@@ -149,7 +149,7 @@
     "@sanity/portable-text-editor": "3.14.2",
     "@sanity/schema": "3.14.2",
     "@sanity/types": "3.14.2",
-    "@sanity/ui": "^1.6.0",
+    "@sanity/ui": "^1.7.2",
     "@sanity/util": "3.14.2",
     "@sanity/uuid": "^3.0.1",
     "@sanity/validation": "3.14.2",
@@ -229,7 +229,7 @@
     "yargs": "^17.3.0"
   },
   "devDependencies": {
-    "@sanity/tsdoc": "1.0.0-alpha.34",
+    "@sanity/tsdoc": "1.0.0-alpha.38",
     "@sanity/ui-workshop": "^1.0.0",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^13.4.0",

packages/sanity/src/core/config/document/inspector.ts

@@ -2,7 +2,6 @@ import {ButtonTone} from '@sanity/ui'
 import {ComponentType} from 'react'
 
 /** @hidden @beta */
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface DocumentInspectorProps {
   documentId: string
   documentType: string

packages/sanity/src/core/config/types.ts

@@ -110,21 +110,73 @@ export interface FormBuilderComponentResolverContext extends ConfigContext {
 }
 
 /**
+ * A tool can be thought of as a top-level "view" or "app".
+ * They are available through the global menu bar, and has a URL route associated with them.
+ *
+ * In essence, a tool is a React component that is rendered when the tool is active,
+ * along with a title, name (URL segment) and icon.
+ *
+ * Tools can handle {@link desk.Intent | intents} such as "edit" or "create" by defining a
+ * function for the `canHandleIntent` property, as well as the `getIntentState` property,
+ * which defines what an intent will be mapped to in terms of the tool's URL state.
+ *
  * @public
  */
 export interface Tool<Options = any> {
+  /**
+   * The React component that renders the tool.
+   */
   component: ComponentType<{tool: Tool<Options>}>
+
+  /**
+   * React component for the icon representing the tool.
+   */
   icon?: ComponentType
+
+  /**
+   * The name of the tool, used as part of the URL.
+   */
   name: string
+
+  /**
+   * Options are passed through from the configuration to the component defined by the `component`
+   */
   options?: Options
+
+  /**
+   * The router for the tool. See {@link router.Router}
+   */
   router?: Router
+
+  /**
+   * Title of the tool - used for the navigation menu item, along with the icon.
+   */
   title: string
+
+  /**
+   * Gets the state for the given intent.
+   *
+   * @param intent - The intent to get the state for.
+   * @param params - The parameters for the intent.
+   * @param routerState - The current router state. See {@link router.RouterState}
+   * @param payload - The payload for the intent.
+   * @returns The state for the intent.
+   */
   getIntentState?: (
     intent: string,
     params: Record<string, string>,
     routerState: RouterState | undefined,
     payload: unknown
   ) => unknown
+
+  /**
+   * Determines whether the tool can handle the given intent.
+   *
+   * @param intent - The intent to check.
+   * @param params - The parameters for the intent.
+   * @param payload - The payload for the intent.
+   * @returns `true` if the tool can handle the intent, `false` otherwise.
+   */
   canHandleIntent?: (intent: string, params: Record<string, unknown>, payload: unknown) => boolean
 }
 
@@ -141,10 +193,25 @@ export type AsyncComposableOption<TValue, TContext> = (
 
 /** @public */
 export interface ConfigContext {
+  /**
+   * The ID of the project.
+   */
   projectId: string
+  /**
+   * The name of the dataset.
+   */
   dataset: string
+  /**
+   * The schema for this source.
+   */
   schema: Schema
+  /**
+   * The current user or `null` if not authenticated.
+   */
   currentUser: CurrentUser | null
+  /**
+   * A function that returns a Sanity client with the {@link SourceClientOptions | specified options}.
+   */
   getClient: (options: SourceClientOptions) => SanityClient
 }
 
@@ -388,35 +455,62 @@ export type PartialContext<TContext extends ConfigContext> = Pick<
 
 /** @public */
 export interface SourceClientOptions {
+  /**
+   * API version to use. See {@link https://www.sanity.io/docs/api-versioning | api-versioning}
+   */
   apiVersion: string
 }
 
-/** @public */
+/**
+ * Represents a source.
+ * @public
+ */
 export interface Source {
+  /** The type of the source. */
   type: 'source'
+  /** The name of the source. */
   name: string
+  /** The title of the source. */
   title: string
+  /** The ID of the project. */
   projectId: string
+  /** The name of the dataset. */
   dataset: string
+  /** The schema of the source. */
   schema: Schema
+  /** The templates of the source. */
   templates: Template[]
+  /** The tools of the source. */
   tools: Tool[]
+  /** The current user of the source. */
   currentUser: CurrentUser | null
+  /** Whether the user is authenticated. */
   authenticated: boolean
 
   /** @internal */
   auth: AuthStore
 
+  /**
+   * Returns a client instance.
+   * @param clientOptions - Options to pass to the client. See {@link SourceClientOptions}
+   */
   getClient: (clientOptions: SourceClientOptions) => SanityClient
 
+  /**
+   * Document-related functionality.
+   * @hidden
+   * @beta
+   */
   document: {
     /**
+     * Returns an array of actions for the document.
      * @hidden
      * @beta
      */
     actions: (props: PartialContext<DocumentActionsContext>) => DocumentActionComponent[]
 
     /**
+     * Returns an array of badges for the document.
      * @hidden
      * @beta
      */
@@ -428,6 +522,7 @@ export interface Source {
     ) => DocumentFieldAction[]
 
     /**
+     * Resolves the production URL for the document.
      * @hidden
      * @beta
      */
@@ -436,6 +531,7 @@ export interface Source {
     ) => Promise<string | undefined>
 
     /**
+     * Resolves the new document options.
      * @hidden
      * @beta
      */
@@ -452,26 +548,41 @@ export interface Source {
      */
     inspectors: (props: PartialContext<DocumentInspectorContext>) => DocumentInspector[]
   }
+
+  /**
+   * Form-related functionality.
+   * @hidden
+   * @beta
+   */
   form: {
     /**
+     * File-related functionality.
      * @hidden
      * @beta
      */
     file: {
+      /** The asset sources. */
       assetSources: AssetSource[]
+
+      /** Whether direct uploads are enabled. */
       directUploads: boolean
     }
 
     /**
+     * Image-related functionality.
      * @hidden
      * @beta
      */
     image: {
+      /** The asset sources. */
       assetSources: AssetSource[]
+
+      /** Whether direct uploads are enabled. */
       directUploads: boolean
     }
 
     /**
+     * Components for the form.
      * @hidden
      * @beta
      */
@@ -485,7 +596,6 @@ export interface Source {
     /**
      * these have not been migrated over and are not merged by the form builder
      *
-     *
      * @hidden
      * @beta
      */
@@ -495,6 +605,10 @@ export interface Source {
     }
   }
 
+  /**
+   * @hidden
+   * @beta
+   */
   studio?: {
     /**
      * @hidden
@@ -516,7 +630,6 @@ export interface Source {
     options: SourceOptions
   }
 }
-
 /** @internal */
 export interface WorkspaceSummary {
   type: 'workspace-summary'
@@ -547,11 +660,23 @@ export interface WorkspaceSummary {
   }
 }
 
-/** @public */
+/**
+ * Definition for Workspace
+ *
+ * @public
+ */
 export interface Workspace extends Omit<Source, 'type'> {
   type: 'workspace'
+  /**
+   * URL base path to use, for instance `/myWorkspace`
+   * Note that this will be prepended with any _studio_ base path, eg `/studio/myWorkspace`,
+   * and is a client-side routing feature. If you're looking to serve your studio from a subpath,
+   * you're probably looking for the `basePath` property in `sanity.cli.ts`/`sanity.cli.js`.
+   */
   basePath: string
+  /** Subtitle to show under the name of the workspace */
   subtitle?: string
+  /** React component to use as icon for this workspace */
   icon: ReactNode
   /**
    *