wip: annotated typedocs progress

apps/docs/astro.config.mjs

@@ -55,7 +55,20 @@ export default defineConfig({
       ],
       plugins: [
         starlightTypeDoc({
-          entryPoints: ['../../packages/editor/src/index.ts'],
+          entryPoints: [
+            '../../packages/editor/src/index.ts',
+            '../../packages/editor/src/behaviors/index.ts',
+            '../../packages/editor/src/selectors/index.ts',
+          ],
+          typeDoc: {
+            navigation: {
+              includeGroups: true,
+            },
+            categorizeByGroup: true,
+            excludeReferences: true,
+            groupOrder: ['Components', '*'],
+          },
+
           tsconfig: '../../packages/editor/tsconfig.json',
         }),
         ...(process.env.CHECK_LINKS ? [starlightLinksValidator()] : []),

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

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({

packages/editor/src/editor/Editable.tsx

@@ -113,11 +113,28 @@
 
 /**
  * @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'>,
   PortableTextEditableProps
 >(function PortableTextEditable(props, forwardedRef) {
   const {
     hotkeys,
     onBlur,

packages/editor/src/editor/define-schema.ts

@@ -34,6 +34,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,

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

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)

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,