fix(types): type contextMenu.customItems as ContextMenuSection[] (SD-2514) (#2777)

* fix(types): type contextMenu.customItems as ContextMenuSection[] (SD-2514)

contextMenu.customItems was typed as bare {Array} which resolved to any[]
in TypeScript. Define ContextMenuItem, ContextMenuSection, and
ContextMenuConfig typedefs with proper shapes derived from runtime usage
in the context menu component. Also types menuProvider callback signature.

* fix(types): widen context menu callback types to match runtime (SD-2514)

action receives (editor, context), not just (editor). Extract
ContextMenuContext typedef with the full runtime shape (isInTable,
documentMode, activeMarks, etc.) and use it across showWhen, render,
action, and menuProvider. Also simplify AugmentedChainedCommands to
reuse Chainified<KnownCommandRecord> instead of restating the mapped type.

* fix(types): allow menuProvider to return null/undefined (SD-2514)

Runtime falls back to original sections when menuProvider returns falsy
(menuProvider(...) || allSections), so the type should allow it.

Author: caio-pizzol

packages/super-editor/src/editors/v1/core/types/ChainedCommands.ts

@@ -78,14 +78,10 @@ type Chainified<T> = {
  * but consumers who augment ExtensionCommandMap get their custom commands
  * on chain() for free.
  */
-type AugmentedChainedCommands = {
-  [K in keyof RegisteredCommands]: (...args: CommandArgs<K>) => ChainableCommandObject;
-};
+type AugmentedChainedCommands = Chainified<KnownCommandRecord>;
 
-/** Same as AugmentedChainedCommands but with original return types for can(). */
-type AugmentedCanCommands = {
-  [K in keyof RegisteredCommands]: (...args: CommandArgs<K>) => CommandResult<K>;
-};
+/** Same but with original return types for can(). */
+type AugmentedCanCommands = KnownCommandRecord;
 
 /**
  * A chainable version of an editor command keyed by command name.

packages/superdoc/src/core/types/index.js

@@ -86,6 +86,63 @@
  * @typedef {(ctx: LinkPopoverContext) => LinkPopoverResolution | null | undefined} LinkPopoverResolver
  */
 
+// ---------------------------------------------------------------------------
+// Context menu types
+// ---------------------------------------------------------------------------
+
+/**
+ * Context object passed to context menu callbacks (showWhen, render, action, menuProvider).
+ * @typedef {Object} ContextMenuContext
+ * @property {Editor} editor The editor instance
+ * @property {string} selectedText Currently selected text (empty string if no selection)
+ * @property {boolean} hasSelection Whether there is an expanded selection
+ * @property {number} selectionStart ProseMirror start position of the selection
+ * @property {number} selectionEnd ProseMirror end position of the selection
+ * @property {'click' | 'slash'} trigger How the menu was opened
+ * @property {boolean} isInTable Whether the cursor is inside a table
+ * @property {boolean} isInList Whether the cursor is inside a list
+ * @property {boolean} isInSectionNode Whether the cursor is inside a document section
+ * @property {boolean} isCellSelection Whether a table cell selection is active
+ * @property {string | null} tableSelectionKind Kind of table selection (row, column, etc.)
+ * @property {string | null} currentNodeType ProseMirror node type name at the cursor
+ * @property {string[]} activeMarks Names of marks active at the cursor
+ * @property {boolean} isTrackedChange Whether the cursor is on a tracked change
+ * @property {string | null} trackedChangeId ID of the tracked change at the cursor
+ * @property {string} documentMode Current document mode (editing, viewing, suggesting)
+ * @property {boolean} canUndo Whether undo is available
+ * @property {boolean} canRedo Whether redo is available
+ * @property {boolean} isEditable Whether the editor is editable
+ * @property {{ x: number, y: number } | null} cursorPosition Screen coordinates of the cursor
+ */
+
+/**
+ * A single item inside a context menu section.
+ * @typedef {Object} ContextMenuItem
+ * @property {string} id Unique identifier for the menu item
+ * @property {string} label Display text
+ * @property {string} [icon] Icon identifier
+ * @property {unknown} [component] Custom Vue component to render this item
+ * @property {(editor: Editor, context: ContextMenuContext) => void} [action] Callback invoked when the item is clicked
+ * @property {(context: ContextMenuContext) => boolean} [showWhen] Predicate controlling visibility
+ * @property {(context: ContextMenuContext) => HTMLElement} [render] Custom renderer returning an HTML element
+ * @property {string} [shortcut] Keyboard shortcut label displayed beside the item
+ */
+
+/**
+ * A section (group) of items in the context menu.
+ * @typedef {Object} ContextMenuSection
+ * @property {string} id Unique identifier for the section
+ * @property {ContextMenuItem[]} items Menu items in this section
+ */
+
+/**
+ * Configuration for the context menu module.
+ * @typedef {Object} ContextMenuConfig
+ * @property {ContextMenuSection[]} [customItems] Custom menu sections appended (or merged by id) to the default menu
+ * @property {(context: ContextMenuContext, sections: ContextMenuSection[]) => ContextMenuSection[] | null | undefined} [menuProvider] Advanced: transform the final section list before render. Return null/undefined to keep the original sections.
+ * @property {boolean} [includeDefaultItems] Whether to include default menu items (default: true)
+ */
+
 // ---------------------------------------------------------------------------
 // Surface system types
 // ---------------------------------------------------------------------------
@@ -469,10 +526,7 @@
  * @property {Object} [toolbar] Toolbar module configuration
  * @property {Object} [links] Link click popover configuration
  * @property {LinkPopoverResolver} [links.popoverResolver] Custom resolver for the link click popover.
- * @property {Object} [contextMenu] Context menu module configuration
- * @property {Array} [contextMenu.customItems] Array of custom menu sections with items
- * @property {Function} [contextMenu.menuProvider] Function to customize menu items
- * @property {boolean} [contextMenu.includeDefaultItems] Whether to include default menu items
+ * @property {ContextMenuConfig} [contextMenu] Context menu module configuration
  * @property {Object} [slashMenu] @deprecated Use contextMenu instead
  * @property {SurfacesModuleConfig} [surfaces] Surface system configuration
  */

packages/superdoc/src/index.js

@@ -162,6 +162,11 @@ import { getSchemaIntrospection } from './helpers/schema-introspection.js';
  * @typedef {import('@superdoc/super-editor').ProofingStatus} ProofingStatus
  * @typedef {import('@superdoc/super-editor').ProofingError} ProofingError
  * @typedef {import('@superdoc/super-editor').PageStyles} PageStyles
+ *
+ * @typedef {import('./core/types/index.js').ContextMenuContext} ContextMenuContext
+ * @typedef {import('./core/types/index.js').ContextMenuItem} ContextMenuItem
+ * @typedef {import('./core/types/index.js').ContextMenuSection} ContextMenuSection
+ * @typedef {import('./core/types/index.js').ContextMenuConfig} ContextMenuConfig
  */
 
 // Public exports

tests/consumer-typecheck/src/customer-scenario.ts

@@ -132,6 +132,12 @@ import type {
   ProofingStatus,
   ProofingError,
 
+  // Context menu
+  ContextMenuContext,
+  ContextMenuItem,
+  ContextMenuSection,
+  ContextMenuConfig,
+
   // Other
   UnsupportedContentItem,
   PageStyles,
@@ -583,6 +589,41 @@ function testEditorContentMethods(editor: Editor) {
   editor.destroy();
 }
 
+// ============================================
+// SECTION 12b: Context menu types (SD-2514)
+// ============================================
+
+function testContextMenuTypes() {
+  // action receives (editor, context) — both args
+  const item: ContextMenuItem = {
+    id: 'copy-text',
+    label: 'Copy',
+    icon: 'copy',
+    action: (editor, context) => {
+      editor.commands.selectAll();
+      const text: string = context.selectedText;
+    },
+    showWhen: (ctx) => ctx.hasSelection && !ctx.isInTable,
+  };
+
+  const section: ContextMenuSection = {
+    id: 'custom-actions',
+    items: [item],
+  };
+
+  const config: ContextMenuConfig = {
+    customItems: [section],
+    includeDefaultItems: true,
+    menuProvider: (ctx, sections) => sections.filter((s) => s.id !== 'clipboard'),
+  };
+
+  // ContextMenuContext has the full runtime shape
+  const ctx: ContextMenuContext = {} as ContextMenuContext;
+  const _trigger: 'click' | 'slash' = ctx.trigger;
+  const _mode: string = ctx.documentMode;
+  const _marks: string[] = ctx.activeMarks;
+}
+
 // ============================================
 // SECTION 13: Extensions, SuperDoc, and utilities
 // ============================================
@@ -679,6 +720,7 @@ export {
   testProofingProvider,
   testEditorStaticMethods,
   testEditorContentMethods,
+  testContextMenuTypes,
   testExtensions,
   testSuperDoc,
   testUtilities,