fix(superdoc): tighten Modules.toolbar typedef (SD-2867 phase A) (#3051)

* fix(superdoc): tighten Modules.toolbar typedef (SD-2867 phase A)

Probing checkJs against SuperDoc.js found nine reads on
config.modules.toolbar (selector, excludeItems, groups, icons, texts,
fonts, hideButtons, responsiveToContainer) all collapsing to type
'Object' for consumers. The runtime accepts each field but the public
typedef lists only `[toolbar] {Object}`.

Promotes Modules.toolbar to a structured shape covering the full set
of fields the implementation reads. Each field is the inverse of an
existing top-level Config.toolbar* alias (toolbarGroups, toolbarIcons,
toolbarTexts) so consumers that already pass these via the modules
form get IDE help.

Verified locally: enabling // @ts-check on SuperDoc.js drops 7 of the
24 'type Object' errors. The remaining 17 sit on internal function
signatures inside SuperDoc.js (e.g. private method @param {Object})
and are picked up by SD-2867 phase B.

* fix(superdoc): correct Modules.toolbar shape per review (SD-2867 phase A)

Review pass found three runtime mismatches in the previous commit and
two wording problems:

- selector was typed `string | HTMLElement`, but findElementBySelector
  in super-editor calls `.startsWith()` and `document.querySelector` —
  HTMLElement crashes. The public docs also say "must be a string
  selector, not a DOM element reference." Narrowed to `string`.
- groups was typed `string[]` only, but super-toolbar.js reads
  `Object.keys(this.config.groups)` and `Object.values(...).flatMap(...)`
  — the runtime accepts an object map, used in the canonical
  `examples/features/custom-toolbar` and documented as the supported
  form. Widened to `string[] | Record<string, string[]>`. Also fixed
  the example values: defaults are `'left' | 'center' | 'right'`, not
  `'edit' | 'format' | 'insert'`.
- customButtons was missing entirely. It is documented in
  packages/superdoc/AGENTS.md and demoed in
  examples/features/custom-toolbar; closing the typedef without it
  would TS-reject a documented public field. Added with a structural
  Array<Record<string, unknown>> placeholder; a future ticket can
  promote ToolbarItem to the public surface and tighten this.

Also softened the parent-level alias claim: only selector, groups,
icons, and texts have Config.toolbar* aliases, not all eight fields.

* fix(superdoc): drop string[] from groups union, retype fonts (SD-2867 phase A)

Second review pass found two more runtime mismatches in the previous
commit:

- The string[] arm of `groups: string[] | Record<string, string[]>`
  is not actually supported. SuperDoc.js spreads `...moduleConfig` into
  SuperToolbar's config, and SuperToolbar's #makeToolbarItems calls
  `Object.values(this.config.groups).flatMap(...)` on the array — for
  an array of group ids that flattens to character codes and silently
  hides every toolbar item. Group-id arrays belong on the top-level
  `Config.toolbarGroups` alias, not here. Narrowed to
  `Record<string, string[]>` only and updated the doc to call out the
  alias for the array form.
- `fonts` was typed `Array<{ name, value }>`, but FontConfig (the type
  super-toolbar already documents and consumes) is `{ key, label, ... }`.
  Switched to `import('@superdoc/super-editor').FontConfig[]` so the
  typedef matches the public type that's already exported.

The HTMLElement-selector and customButtons fixes from the previous
commit stand.

Author: caio-pizzol

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

@@ -530,7 +530,16 @@
  * @property {boolean} [pdf.textLayer] Enable text layer rendering (default: false)
  * @property {number} [pdf.outputScale] Canvas render scale (quality)
  * @property {CollaborationConfig} [collaboration] Collaboration module configuration
- * @property {Object} [toolbar] Toolbar module configuration
+ * @property {Object} [toolbar] Toolbar module configuration. The `selector`, `groups`, `icons`, and `texts` fields fall back to the top-level `Config.toolbar`, `Config.toolbarGroups`, `Config.toolbarIcons`, and `Config.toolbarTexts` aliases respectively if not set here.
+ * @property {string} [toolbar.selector] CSS selector (id or class) for the DOM element to render the toolbar into. Must be a string selector, not an `HTMLElement` reference. Falls back to `Config.toolbar` if omitted.
+ * @property {string[]} [toolbar.excludeItems] Toolbar item ids to hide from the default set.
+ * @property {Record<string, string[]>} [toolbar.groups] Object map of group id to item ids (`{ left: [...], center: [...], right: [...] }`) that overrides the default group composition. Default group ids are `'left' | 'center' | 'right'`. To pass an ordered group-id array (`['left', 'center', 'right']`) use the top-level `Config.toolbarGroups` instead — the array form is not accepted here.
+ * @property {Record<string, unknown>} [toolbar.icons] Icon overrides keyed by toolbar item id. Falls back to `Config.toolbarIcons`.
+ * @property {Record<string, string>} [toolbar.texts] Text/label overrides keyed by toolbar item id. Falls back to `Config.toolbarTexts`.
+ * @property {import('@superdoc/super-editor').FontConfig[]} [toolbar.fonts] Custom font list rendered in the font-family dropdown.
+ * @property {boolean} [toolbar.hideButtons] Hide buttons that overflow the available width (default: true).
+ * @property {boolean} [toolbar.responsiveToContainer] Recompute the visible toolbar item set on container resize (default: false).
+ * @property {Array<Record<string, unknown>>} [toolbar.customButtons] Custom toolbar buttons appended to the default item set. Each entry is a `ToolbarItem`-shaped object (see the consumer-facing toolbar docs for the full shape). The internal `ToolbarItem` type is not yet on the public surface; this typedef accepts the structural shape consumers already pass through `modules.toolbar.customButtons`.
  * @property {Object} [links] Link click popover configuration
  * @property {LinkPopoverResolver} [links.popoverResolver] Custom resolver for the link click popover.
  * @property {ContextMenuConfig} [contextMenu] Context menu module configuration