docs: add more details to typedoc support (#691)

* wip: annotated typedocs progress * docs: adjust reference generation * Docs: add emoji example and update import (#630) * docs: add emoji example * docs(fix): fix coreBehaviors import * docs: adjust reference generation * docs: add example to defineBehavior
portabletext · Jan 16, 2025 · cc1e0ee · cc1e0ee
1 parent 8a9666c
commit cc1e0ee
Show file tree

Hide file tree

Showing 12 changed files with 267 additions and 9 deletions.
diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
@@ -3,7 +3,13 @@ import starlight from '@astrojs/starlight'
 import tailwind from '@astrojs/tailwind'
 import {defineConfig} from 'astro/config'
 import starlightLinksValidator from 'starlight-links-validator'
-import starlightTypeDoc, {typeDocSidebarGroup} from 'starlight-typedoc'
+import {createStarlightTypeDocPlugin} from 'starlight-typedoc'
+
+const [editorTypeDoc, editorTypeDocSidebar] = createStarlightTypeDocPlugin()
+const [behaviorTypeDoc, behaviorTypeDocSidebar] = createStarlightTypeDocPlugin()
+const [selectorsTypeDoc, selectorsTypeDocSidebar] =
+  createStarlightTypeDocPlugin()
+const tsconfig = '../../packages/editor/tsconfig.json'
 
 // https://astro.build/config
 export default defineConfig({
@@ -58,9 +64,31 @@ export default defineConfig({
         },
         {
           label: 'Reference',
-          autogenerate: {directory: 'reference'},
+          collapsed: true,
+          items: [
+            {
+              label: 'Editor',
+              items: [
+                {label: 'Overview', slug: 'reference/editor'},
+                {...editorTypeDocSidebar, badge: 'Generated'},
+              ],
+            },
+            {
+              label: 'Behaviors',
+              items: [
+                {label: 'Overview', slug: 'reference/behavior-api'},
+                {...behaviorTypeDocSidebar, badge: 'Generated'},
+              ],
+            },
+            {
+              label: 'Selectors',
+              items: [
+                {label: 'Overview', slug: 'reference/selectors'},
+                {...selectorsTypeDocSidebar, badge: 'Generated'},
+              ],
+            },
+          ],
         },
-        typeDocSidebarGroup,
         {
           label: 'Integrations',
           autogenerate: {directory: 'integrations'},
@@ -71,9 +99,38 @@ export default defineConfig({
         },
       ],
       plugins: [
-        starlightTypeDoc({
+        editorTypeDoc({
           entryPoints: ['../../packages/editor/src/index.ts'],
-          tsconfig: '../../packages/editor/tsconfig.json',
+          output: 'api/editor',
+          typeDoc: {
+            excludeReferences: true,
+          },
+          sidebar: {
+            collapsed: true,
+          },
+          tsconfig,
+        }),
+        behaviorTypeDoc({
+          entryPoints: ['../../packages/editor/src/behaviors/index.ts'],
+          output: 'api/behaviors',
+          typeDoc: {
+            excludeReferences: true,
+          },
+          sidebar: {
+            collapsed: true,
+          },
+          tsconfig,
+        }),
+        selectorsTypeDoc({
+          entryPoints: ['../../packages/editor/src/selectors/index.ts'],
+          output: 'api/selectors',
+          typeDoc: {
+            excludeReferences: true,
+          },
+          sidebar: {
+            collapsed: true,
+          },
+          tsconfig,
         }),
         ...(process.env.CHECK_LINKS ? [starlightLinksValidator()] : []),
       ],

diff --git a/apps/docs/src/content/docs/reference/behavior-api.mdx b/apps/docs/src/content/docs/reference/behavior-api.mdx
@@ -1,5 +1,5 @@
 ---
-title: Behavior API
+title: Behavior API Overview
 description: Reference documentation for the Behavior API.
 ---
 

diff --git a/...docs/src/content/docs/reference/hooks.mdx → ...ocs/src/content/docs/reference/editor.mdx b/...docs/src/content/docs/reference/hooks.mdx → ...ocs/src/content/docs/reference/editor.mdx
@@ -1,8 +1,12 @@
 ---
-title: Hooks
-description: Hooks reference
+title: Editor API Overview
+description: Editor API reference overview
 ---
 
+The editor API provides access to the editor context and selectors for deriving state.
+
+Use the following hooks to access the editor from within your components.
+
 ## `useEditor`
 
 Access the editor context. Commonly used when building toolbars or passing context to selectors.

diff --git a/apps/docs/src/content/docs/reference/selectors.mdx b/apps/docs/src/content/docs/reference/selectors.mdx
@@ -1,5 +1,5 @@
 ---
-title: Selectors
+title: Selectors API Overview
 description: Selectors reference
 prev: false
 next: false

diff --git a/packages/editor/package.config.ts b/packages/editor/package.config.ts
@@ -17,6 +17,16 @@ export default defineConfig({
         allowMultiple: true,
         syntaxKind: 'block',
       },
+      {
+        name: 'group',
+        allowMultiple: true,
+        syntaxKind: 'block',
+      },
+      {
+        name: 'groupDescription',
+        allowMultiple: true,
+        syntaxKind: 'block',
+      },
     ],
     rules: {
       // Disable rules for now

diff --git a/packages/editor/src/behaviors/behavior.markdown.ts b/packages/editor/src/behaviors/behavior.markdown.ts
@@ -25,6 +25,48 @@ export type MarkdownBehaviorsConfig = {
 
 /**
  * @beta
+ * Create markdown behaviors for common markdown actions such as converting ### to headings, --- to HRs, and more.
+ *
+ * @example
+ * Configure the bundled markdown behaviors
+ * ```ts
+ * import {EditorProvider} from '@portabletext/editor'
+ * import {createMarkdownBehaviors, coreBehaviors} from '@portabletext/editor/behaviors'
+ *
+ * function App() {
+ *  return (
+ *   <EditorProvider
+ *    initialConfig={{
+ *    behaviors: [
+ *    ...coreBehaviors,
+ *    ...createMarkdownBehaviors({
+ *        horizontalRuleObject: ({schema}) => {
+ *          const name = schema.blockObjects.find(
+ *            (object) => object.name === 'break',
+ *          )?.name
+ *          return name ? {name} : undefined
+ *        },
+ *        defaultStyle: ({schema}) => schema.styles[0].value,
+ *        headingStyle: ({schema, level}) =>
+ *          schema.styles.find((style) => style.value === `h${level}`)
+ *            ?.value,
+ *        blockquoteStyle: ({schema}) =>
+ *          schema.styles.find((style) => style.value === 'blockquote')
+ *            ?.value,
+ *        unorderedListStyle: ({schema}) =>
+ *          schema.lists.find((list) => list.value === 'bullet')?.value,
+ *        orderedListStyle: ({schema}) =>
+ *          schema.lists.find((list) => list.value === 'number')?.value,
+ *      }),
+ *      ]
+ *    }}
+ *    >
+ *    {...}
+ *    </EditorProvider>
+ *  )
+ * }
+ * ```
+ *
  */
 export function createMarkdownBehaviors(config: MarkdownBehaviorsConfig) {
   const automaticBlockquoteOnSpace = defineBehavior({

diff --git a/packages/editor/src/behaviors/behavior.types.ts b/packages/editor/src/behaviors/behavior.types.ts
@@ -306,6 +306,21 @@ export type BehaviorActionIntendSet<TBehaviorEvent, TGuardResponse> = (
 
 /**
  * @beta
+ *
+ * @example
+ *
+ * ```tsx
+ * const noLowerCaseA = defineBehavior({
+ *   on: 'insert.text',
+ *   guard: ({event, context}) => event.text === 'a',
+ *   actions: [({event, context}) => [{type: 'insert.text', text: 'A'}]],
+ * })
+ * ```
+ *
+ *
+ *
+ *
+ *
  */
 export function defineBehavior<
   TPayload extends Record<string, unknown>,

diff --git a/packages/editor/src/editor/Editable.tsx b/packages/editor/src/editor/Editable.tsx
@@ -113,6 +113,23 @@ export type PortableTextEditableProps = Omit<
 
 /**
  * @public
+ *
+ *
+ * The core component that renders the editor. Must be placed within the {@link EventProvider} component.
+ *
+ * @example
+ * ```tsx
+ * import { PortableTextEditable, EditorProvider } from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  return (
+ *   <EditorProvider>
+ *    <PortableTextEditable />
+ *  </EditorProvider>
+ *  )
+ * }
+ * ```
+ * @group Components
  */
 export const PortableTextEditable = forwardRef<
   Omit<HTMLDivElement, 'as' | 'onPaste' | 'onBeforeInput'>,

diff --git a/packages/editor/src/editor/define-schema.ts b/packages/editor/src/editor/define-schema.ts
@@ -28,6 +28,26 @@ export type SchemaDefinition<
 
 /**
  * @public
+ * A helper wrapper that adds editor support, such as autocomplete and type checking, for a schema definition.
+ * @example
+ * ```ts
+ * import { defineSchema } from '@portabletext/editor'
+ *
+ * const schemaDefinition = defineSchema({
+ *  decorators: [{name: 'strong'}, {name: 'em'}, {name: 'underline'}],
+ *  annotations: [{name: 'link'}],
+ *  styles: [
+ *    {name: 'normal'},
+ *    {name: 'h1'},
+ *    {name: 'h2'},
+ *    {name: 'h3'},
+ *    {name: 'blockquote'},
+ *  ],
+ *  lists: [],
+ *  inlineObjects: [],
+ *  blockObjects: [],
+ * }
+ * ```
  */
 export function defineSchema<const TSchemaDefinition extends SchemaDefinition>(
   definition: TSchemaDefinition,

diff --git a/packages/editor/src/editor/editor-event-listener.tsx b/packages/editor/src/editor/editor-event-listener.tsx
@@ -5,6 +5,51 @@ import {useEditor} from './editor-provider'
 
 /**
  * @public
+ * Listen for events emitted by the editor. Must be used inside `EditorProvider`. Events available include:
+ *  - 'blurred'
+ *  - 'done loading'
+ *  - 'editable'
+ *  - 'error'
+ *  - 'focused'
+ *  - 'invalid value'
+ *  - 'loading'
+ *  - 'mutation'
+ *  - 'patch'
+ *  - 'read only'
+ *  - 'ready'
+ *  - 'selection'
+ *  - 'value changed'
+ *
+ * @example
+ * Listen and log events.
+ * ```tsx
+ * import {EditorEventListener, EditorProvider} from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  return (
+ *  <EditorProvider>
+ *   <EditorEventListener
+ *    on={(event) => {
+ *     console.log(event)
+ *    }
+ *   } />
+ *   { ... }
+ * </EditorProvider>
+ *  )
+ * }
+ * ```
+ * @example
+ * Handle events when there is a mutation.
+ * ```tsx
+ * <EditorEventListener
+ *  on={(event) => {
+ *    if (event.type === 'mutation') {
+ *      console.log('Value changed:', event.snapshot)
+ *    }
+ *  }}
+ * />
+ * ```
+ * @group Components
  */
 export function EditorEventListener(props: {
   on: (event: EditorEmittedEvent) => void

diff --git a/packages/editor/src/editor/editor-provider.tsx b/packages/editor/src/editor/editor-provider.tsx
@@ -23,6 +23,21 @@ export type EditorProviderProps = {
 
 /**
  * @public
+ * The EditorProvider component is used to set up the editor context and configure the Portable Text Editor.
+ * @example
+ * ```tsx
+ * import {EditorProvider} from '@portabletext/editor'
+ *
+ * function App() {
+ *  return (
+ *    <EditorProvider initialConfig={{ ... }} >
+ *      ...
+ *    </EditorProvider>
+ *  )
+ * }
+ *
+ * ```
+ * @group Components
  */
 export function EditorProvider(props: EditorProviderProps) {
   const editor = useCreateEditor(props.initialConfig)
@@ -66,6 +81,18 @@ export function EditorProvider(props: EditorProviderProps) {
 
 /**
  * @public
+ * Get the current editor context from the `EditorProvider`.
+ * Must be used inside the `EditorProvider` component.
+ * @returns The current editor object.
+ * @example
+ * ```tsx
+ * import { useEditor } from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  const editor = useEditor()
+ * }
+ * ```
+ * @group Hooks
  */
 export function useEditor() {
   const editor = React.useContext(EditorContext)

diff --git a/packages/editor/src/editor/editor-selector.ts b/packages/editor/src/editor/editor-selector.ts
@@ -17,6 +17,27 @@ export type EditorSelector<TSelected> = (snapshot: EditorSnapshot) => TSelected
 
 /**
  * @public
+ * Hook to select a value from the editor state.
+ * @example
+ * Pass a selector as the second argument
+ * ```tsx
+ * import { useEditorSelector } from '@portabletext/editor'
+ *
+ * function MyComponent(editor) {
+ *  const value = useEditorSelector(editor, selector)
+ * }
+ * ```
+ * @example
+ * Pass an inline selector as the second argument.
+ * In this case, use the editor context to obtain the schema.
+ * ```tsx
+ * import { useEditorSelector } from '@portabletext/editor'
+ *
+ * function MyComponent(editor) {
+ *  const schema = useEditorSelector(editor, (snapshot) => snapshot.context.schema)
+ * }
+ * ```
+ * @group Hooks
  */
 export function useEditorSelector<TSelected>(
   editor: Editor,