prosemirror-menu 1.3.0-beta.1 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+## 1.3.1 (2026-04-15)
+
+### Bug fixes
+
+Move focus to button before closing a submenu, to avoid focus moving back to the document root.
+
+## 1.3.0 (2026-02-17)
+
+### New features
+
+The menu elements and menu bar now support keyboard navigation and use ARIA attributes for improved accessibility.
+
+## 1.2.5 (2025-04-22)
+
+### Bug fixes
+
+Make sure the menu is re-rendered when the editor's root changes, so that it doesn't reference icons whose SVG lives in another root.
+
+## 1.2.4 (2023-08-20)
+
+### Bug fixes
+
+Fix a bug where icon creation crashed because it couldn't find a Document value.
+
+## 1.2.3 (2023-08-16)
+
+### Bug fixes
+
+Don't directly use the global `window`/`document`, to fix use in a different frame or shadow root.
+
+## 1.2.2 (2023-05-17)
+
+### Bug fixes
+
+Include CommonJS type declarations in the package to please new TypeScript resolution settings.
+
+## 1.2.1 (2022-06-22)
+
+### Bug fixes
+
+Export CSS file from package.json.
+
+## 1.2.0 (2022-05-30)
+
+### New features
+
+Include TypeScript type declarations.
+
 ## 1.1.4 (2020-03-12)
 
 ### Bug fixes

package/CONTRIBUTING.md

@@ -12,7 +12,7 @@ Community discussion, questions, and informal bug reporting is done on the
 ## Submitting bug reports
 
 Report bugs on the
-[GitHub issue tracker](http://github.com/prosemirror/prosemirror/issues).
+[issue tracker](https://code.haverbeke.berlin/prosemirror/prosemirror/issues).
 Before reporting a bug, please read these pointers.
 
 - The issue tracker is for *bugs*, not requests for help. Questions
@@ -34,21 +34,28 @@ Before reporting a bug, please read these pointers.
 
 ## Contributing code
 
-- Make sure you have a [GitHub Account](https://github.com/signup/free)
+Code generated by a language model is not welcome in this project.
+Please don't waste my time with it.
 
-- Fork the relevant repository
-  ([how to fork a repo](https://help.github.com/articles/fork-a-repo))
+If you want to make a change that involves a significant overhaul of
+the code or introduces a user-visible new feature, create an
+[issue](https://code.haverbeke.berlin/prosemirror/prosemirror/issues/)
+first with your proposal.
+
+- Make sure you have a [Codeberg](https://codeberg.org/user/sign_up)
+  or [GitHub](https://github.com/signup/free) account.
+  
+- Use that to create a [code.haverbeke.berlin
+  account](https://code.haverbeke.berlin/user/login).
+
+- Fork the relevant repository.
 
 - Create a local checkout of the code. You can use the
-  [main repository](https://github.com/prosemirror/prosemirror) to
+  [main repository](https://code.haverbeke.berlin/prosemirror/prosemirror) to
   easily check out all core modules.
 
 - Make your changes, and commit them
 
-- Follow the code style of the rest of the project (see below). Run
-  `npm run lint` (in the main repository checkout) to make sure that
-  the linter is happy.
-
 - If your changes are easy to test or likely to regress, add tests in
   the relevant `test/` directory. Either put them in an existing
   `test-*.js` file, if they fit there, or add a new file.
@@ -56,13 +63,13 @@ Before reporting a bug, please read these pointers.
 - Make sure all tests pass. Run `npm run test` to verify tests pass
   (you will need Node.js v6+).
 
-- Submit a pull request ([how to create a pull request](https://help.github.com/articles/fork-a-repo)).
-  Don't put more than one feature/fix in a single pull request.
+- Submit a pull request. Don't put more than one feature/fix in a
+  single pull request.
 
 By contributing code to ProseMirror you
 
  - Agree to license the contributed code under the project's [MIT
-   license](https://github.com/ProseMirror/prosemirror/blob/master/LICENSE).
+   license](https://code.haverbeke.berlin/prosemirror/prosemirror/blob/main/LICENSE).
 
  - Confirm that you have the right to contribute and license the code
    in question. (Either you hold all rights on the code, or the rights
@@ -82,19 +89,16 @@ By contributing code to ProseMirror you
 - Follow the surrounding code when it comes to spacing, brace
   placement, etc.
 
-- Brace-less single-statement bodies are encouraged (whenever they
-  don't impact readability).
+- Brace-less single-statement bodies are encouraged whenever they
+  don't impact readability.
 
-- [getdocs](https://github.com/marijnh/getdocs)-style doc comments
+- [getdocs-ts](https://code.haverbeke.berlin/marijn/getdocs-ts)-style doc comments
   above items that are part of the public API.
 
 - When documenting non-public items, you can put the type after a
   single colon, so that getdocs doesn't pick it up and add it to the
   API reference.
 
-- The linter (`npm run lint`) complains about unused variables and
-  functions. Prefix their names with an underscore to muffle it.
-
 - ProseMirror does *not* follow JSHint or JSLint prescribed style.
   Patches that try to 'fix' code to pass one of these linters will not
   be accepted.

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2015-2017 by Marijn Haverbeke <marijnh@gmail.com> and others
+Copyright (C) 2015-2017 by Marijn Haverbeke <marijn@haverbeke.berlin> and others
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # prosemirror-menu
 
-[ [**WEBSITE**](https://prosemirror.net) | [**ISSUES**](https://github.com/prosemirror/prosemirror-menu/issues) | [**FORUM**](https://discuss.prosemirror.net) | [**GITTER**](https://gitter.im/ProseMirror/prosemirror) ]
+[ [**WEBSITE**](https://prosemirror.net) | [**ISSUES**](https://code.haverbeke.berlin/prosemirror/prosemirror-menu/issues) | [**FORUM**](https://discuss.prosemirror.net) | [**GITTER**](https://gitter.im/ProseMirror/prosemirror) ]
 
 This is a non-core example module for [ProseMirror](https://prosemirror.net).
 ProseMirror is a well-behaved rich semantic content editor based on
@@ -19,10 +19,10 @@ ProseMirror, publish your fork, and if it works for me, I'll gladly
 deprecate this in favor of your module.
 
 This code is released under an
-[MIT license](https://github.com/prosemirror/prosemirror/tree/master/LICENSE).
+[MIT license](https://code.haverbeke.berlin/prosemirror/prosemirror/src/branch/main/LICENSE).
 There's a [forum](http://discuss.prosemirror.net) for general
 discussion and support requests, and the
-[Github bug tracker](https://github.com/prosemirror/prosemirror-menu/issues)
+[bug tracker](https://code.haverbeke.berlin/prosemirror/prosemirror-menu/issues)
 is the place to report issues.
 
 ## Documentation
@@ -31,7 +31,7 @@ This module defines a number of building blocks for ProseMirror menus,
 along with a [menu bar](#menu.menuBar) implementation.
 
 When using this module, you should make sure its
-[`style/menu.css`](https://github.com/ProseMirror/prosemirror-menu/blob/master/style/menu.css)
+[`style/menu.css`](https://code.haverbeke.berlin/prosemirror/prosemirror-menu/src/branch/main/style/menu.css)
 file is loaded into your page.
 
 ### interface MenuElement
@@ -40,13 +40,15 @@ The types defined in this module aren't the only thing you can
 display in your menu. Anything that conforms to this interface can
 be put into a menu structure.
 
- * **`render`**`(pm: EditorView) → {dom: HTMLElement, update: fn(state: EditorState) → boolean}`\
+ * **`render`**`(pm: EditorView) → {dom: HTMLElement, update: fn(state: EditorState) → boolean, focusable?: HTMLElement}`\
    Render the element for display in the menu. Must return a DOM
    element and a function that can be used to update the element to
    a new state. The `update` function must return false if the
-   update hid the entire element.
+   update hid the entire element. May also return a `focusable`
+   DOM node, which is the node that should receive focus when this
+   element is focused. If not provided, the `dom` element will be used.
 
-### class MenuItem
+### class MenuItem`<E extends HTMLElement = HTMLButtonElement>`
 
  implements `MenuElement`An icon or label that, when clicked, executes a command.
 
@@ -56,56 +58,56 @@ be put into a menu structure.
  * **`spec`**`: MenuItemSpec`\
    The spec used to create this item.
 
- * **`render`**`(view: EditorView) → {dom: HTMLElement, update: fn(state: EditorState) → boolean}`\
+ * **`render`**`(view: EditorView) → {dom: E | HTMLButtonElement, update: fn(state: EditorState) → boolean}`\
    Renders the icon according to its [display
    spec](#menu.MenuItemSpec.display), and adds an event handler which
    executes the command when the representation is clicked.
 
-### interface MenuItemSpec
+### interface MenuItemSpec`<E extends HTMLElement = HTMLButtonElement>`
 
 The configuration object passed to the `MenuItem` constructor.
 
  * **`run`**`(state: EditorState, dispatch: fn(tr: Transaction), view: EditorView, event: Event)`\
    The function to execute when the menu item is activated.
 
- * **`select`**`: ?fn(state: EditorState) → boolean`\
+ * **`select`**`?: fn(state: EditorState) → boolean`\
    Optional function that is used to determine whether the item is
    appropriate at the moment. Deselected items will be hidden.
 
- * **`enable`**`: ?fn(state: EditorState) → boolean`\
+ * **`enable`**`?: fn(state: EditorState) → boolean`\
    Function that is used to determine if the item is enabled. If
    given and returning false, the item will be given a disabled
    styling.
 
- * **`active`**`: ?fn(state: EditorState) → boolean`\
+ * **`active`**`?: fn(state: EditorState) → boolean`\
    A predicate function to determine whether the item is 'active' (for
    example, the item for toggling the strong mark might be active then
    the cursor is in strong text).
 
- * **`render`**`: ?fn(view: EditorView) → HTMLElement`\
+ * **`render`**`?: fn(view: EditorView) → E`\
    A function that renders the item. You must provide either this,
    [`icon`](#menu.MenuItemSpec.icon), or [`label`](#MenuItemSpec.label).
 
- * **`icon`**`: ?IconSpec`\
+ * **`icon`**`?: IconSpec`\
    Describes an icon to show for this item.
 
- * **`label`**`: ?string`\
+ * **`label`**`?: string`\
    Makes the item show up as a text label. Mostly useful for items
    wrapped in a [drop-down](#menu.Dropdown) or similar menu. The object
    should have a `label` property providing the text to display.
 
- * **`title`**`: ?string | fn(state: EditorState) → string`\
+ * **`title`**`?: string | fn(state: EditorState) → string`\
    Defines DOM title (mouseover) text for the item.
 
- * **`class`**`: ?string`\
+ * **`class`**`?: string`\
    Optionally adds a CSS class to the item's DOM representation.
 
- * **`css`**`: ?string`\
+ * **`css`**`?: string`\
    Optionally adds a string of inline CSS to the item's DOM
    representation.
 
  * type **`IconSpec`**
-   ` = {path: string, width: number, height: number} | {text: string, css?: ?string} | {dom: Node}`\
+   ` = {path: string, width: number, height: number} | {text: string, css?: string} | {dom: Node}`\
    Specifies an icon. May be either an SVG icon, in which case its
    `path` property should be an [SVG path
    spec](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d),
@@ -120,28 +122,68 @@ The configuration object passed to the `MenuItem` constructor.
  implements `MenuElement`A drop-down menu, displayed as a label with a downwards-pointing
 triangle to the right of it.
 
- * `new `**`Dropdown`**`(content: readonly MenuElement[] | MenuElement, options: ?Object = {})`\
+ * `new `**`Dropdown`**`(content: readonly MenuElement[] | MenuElement, options?: Object = {})`\
    Create a dropdown wrapping the elements.
 
- * **`render`**`(view: EditorView) → {dom: HTMLElement, update: fn(state: EditorState) → boolean}`\
+    * **`options`**`?: Object`
+
+       * **`label`**`?: string`\
+         The label to show on the drop-down control.
+
+       * **`title`**`?: string`\
+         Sets the
+         [`title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title)
+         attribute given to the menu control.
+
+       * **`class`**`?: string`\
+         When given, adds an extra CSS class to the menu control.
+
+       * **`css`**`?: string`\
+         When given, adds an extra set of CSS styles to the menu control.
+
+ * **`render`**`(view: EditorView) → {dom: HTMLElement, update: fn(state: EditorState) → boolean, focusable: HTMLElement}`\
    Render the dropdown menu and sub-items.
 
+ * **`setFocusIndex`**`(index: number)`
+
 ### class DropdownSubmenu
 
  implements `MenuElement`Represents a submenu wrapping a group of elements that start
 hidden and expand to the right when hovered over or tapped.
 
- * `new `**`DropdownSubmenu`**`(content: readonly MenuElement[] | MenuElement, options: ?Object = {})`\
+ * `new `**`DropdownSubmenu`**`(content: readonly MenuElement[] | MenuElement, options?: Object = {})`\
    Creates a submenu for the given group of menu elements. The
    following options are recognized:
 
- * **`render`**`(view: EditorView) → {dom: HTMLElement, update: fn(state: EditorState) → boolean}`\
+    * **`options`**`?: Object`
+
+       * **`label`**`?: string`\
+         The label to show on the submenu.
+
+ * **`render`**`(view: EditorView) → {dom: HTMLElement, update: fn(state: EditorState) → boolean, focusable: HTMLElement}`\
    Renders the submenu.
 
+ * **`setFocusIndex`**`(index: number)`
+
  * **`menuBar`**`(options: Object) → Plugin`\
    A plugin that will place a menu bar above the editor. Note that
    this involves wrapping the editor in an additional `<div>`.
 
+    * **`options`**`: Object`
+
+       * **`content`**`: readonly readonly MenuElement[][]`\
+         Provides the content of the menu, as a nested array to be
+         passed to `renderGrouped`.
+
+       * **`position`**`?: "before" | "after"`\
+         Determines whether the menu is placed before or after the editor in the DOM.
+         The default is "before".
+
+       * **`floating`**`?: boolean`\
+         Determines whether the menu floats, i.e. whether it sticks to
+         the top of the viewport when the editor is partially scrolled
+         out of view.
+
 
 This module exports the following pre-built items or item
 constructors:
@@ -161,13 +203,13 @@ constructors:
  * **`redoItem`**`: MenuItem`\
    Menu item for the `redo` command.
 
- * **`wrapItem`**`(nodeType: NodeType, options: Partial & {attrs?: ?Attrs}) → MenuItem`\
+ * **`wrapItem`**`(nodeType: NodeType, options: Partial & {attrs?: Attrs}) → MenuItem`\
    Build a menu item for wrapping the selection in a given node type.
    Adds `run` and `select` properties to the ones present in
    `options`. `options.attrs` may be an object that provides
    attributes for the wrapping node.
 
- * **`blockTypeItem`**`(nodeType: NodeType, options: Partial & {attrs?: ?Attrs}) → MenuItem`\
+ * **`blockTypeItem`**`(nodeType: NodeType, options: Partial & {attrs?: Attrs}) → MenuItem`\
    Build a menu item for changing the type of the textblock around the
    selection to the given type. Provides `run`, `active`, and `select`
    properties. Others must be given in `options`. `options.attrs` may
@@ -184,12 +226,10 @@ To construct your own items, these icons may be useful:
    `MenuItem`.
 
 
- * **`renderGrouped`**`(view: EditorView, content: readonly readonly MenuElement[][]) → {`\
-   `  dom: DocumentFragment,`\
-   `  update: fn(state: EditorState) → boolean`\
-   `}`\
+ * **`renderGrouped`**`(view: EditorView, content: readonly readonly MenuElement[][]) → {dom: DocumentFragment, update: fn(state: EditorState) → boolean, focusables: HTMLElement[]}`\
    Render the given, possibly nested, array of menu elements into a
    document fragment, placing separators between them (and ensuring no
    superfluous separators appear when some of the groups turn out to
    be empty).
 
+