feat(plugins): render a task menu action as a submenu (#3874)
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
@@ -0,0 +1,89 @@
|
||||
---
|
||||
status: draft
|
||||
system: plugins
|
||||
created: 2026-09-23
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# Plugin task menu submenus Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
A plugin task-menu action has always been exactly one selectable item. A plugin
|
||||
whose natural contribution is a short list of frequent choices therefore has
|
||||
nowhere to put them: the Tags plugin opens a modal picker so the user can add one
|
||||
of the workspace's recent tags to a card, one menu open plus one modal plus one
|
||||
click. Registering five sibling actions instead would flood every card's menu
|
||||
with rows that are mostly noise.
|
||||
|
||||
`registerTaskMenuAction` gains an optional `items(context)` beside its required
|
||||
`run`. Declaring it renders the action as a one-level submenu whose children the
|
||||
plugin supplies at menu-build time; the children reach the card menu, the shared
|
||||
desktop/mobile task-row menu, the command palette and the sidebar's task
|
||||
commands. `run` stays required and stays the flat behavior, which is the whole
|
||||
compatibility story: a host that predates the field ignores it, and a build whose
|
||||
`items()` yields nothing usable falls back to the same flat item, so an action
|
||||
can ship both a quick child list and its existing behavior.
|
||||
|
||||
Plugin bundles are plain JavaScript, so the registration types are a promise
|
||||
rather than a guarantee. Everything here is shaped by that: the host reads plugin
|
||||
values defensively at one boundary, degrades to the flat item or drops a single
|
||||
child instead of failing a render, and reports what it dropped.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-PLUGINS-TASK-MENU-SUBMENUS-001: A task menu action can declare a one-level submenu
|
||||
|
||||
**Intent:** A plugin with a short list of frequent, per-card choices needs to
|
||||
offer them in one click each without adding sibling rows to every card's menu.
|
||||
The host renders the action as a submenu when, and only when, the plugin supplies
|
||||
children it can actually render.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-001.1:** `TaskMenuActionRegistration.items` SHALL be optional and synchronous, returning `readonly TaskMenuSubItemRegistration[]`; `run` SHALL remain required. A host that predates `items` SHALL ignore the unknown field and render the flat item it has always rendered, reading only `label`, `icon` and `run`.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-001.2:** When `items()` returns at least one usable child, the action SHALL render as a submenu: `label` becomes an unselectable trigger, each child becomes a selectable entry in the returned order, each child's `run` is invoked with the same `PluginTaskMenuContext` as the action, and a child is unselectable when either the child's own `disabled` or the host's entry-level `disabled` is set. Nesting SHALL stop at one level: a child is never itself a submenu.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-001.3:** A result with nothing usable SHALL fall back to the action's flat `run` item rather than producing a trigger nothing can open. Nothing usable means: `items` absent, `null`/`undefined`, a non-array, an empty array, a thrown exception, a thenable (the contract is synchronous), or an array whose every element is unusable. A thrown `items()` SHALL be caught and reported.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-001.4:** A child the host cannot render SHALL be dropped, and the drop SHALL be reported once per action and defect kind rather than once per menu build. Unusable means: `id` or `label` absent, not a string, or blank after trimming; `run` not callable; `disabled` present and neither boolean nor `null`; `icon` present and neither a curated name, a component (including React's `memo` and `forwardRef`, which are objects at run time), a ready-made element, nor `null`. A child may be read only inside a guard, so a throwing getter or a Proxy fails that child instead of the card's render.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-001.5:** A repeated child `id` SHALL keep its first occurrence and report the repeat, so the host never builds two children with one key. `icon: null` and `disabled: null` SHALL both mean "absent", matching how a JavaScript bundle spells an omitted field.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-001.6:** `items()` SHALL be evaluated while the host builds that card's or row's menu entries, which happens on every render and for both the dropdown and the context variant whether or not a menu is open. The API documentation SHALL say so and SHALL tell authors to read cached state and memoize anything expensive.
|
||||
|
||||
### REQ-PLUGINS-TASK-MENU-SUBMENUS-002: An unrenderable registration never fails a host render
|
||||
|
||||
**Intent:** One plugin's malformed registration must not take down a card, a
|
||||
board, or a command surface. The host's own contract says unusable input degrades;
|
||||
these criteria make that true for the values a real bundle can produce, including
|
||||
values whose own accessors throw.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-002.1:** A registration whose own `label` or `id` is not a usable string SHALL contribute no entry at all, and SHALL be reported once, instead of rendering an unselectable or unkeyable entry.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-002.2:** The host's defect report SHALL NOT throw while reporting: a `Symbol` id, an object without a string form, or a throwing accessor on the registration SHALL still be reported or skipped without an exception escaping the builder.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-002.3:** A group `edit` registration the host cannot render SHALL leave the card's native `Edit` item flat, exactly as if no plugin action were registered, rather than wrapping it in a submenu with no plugin child under it.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-002.4:** An entry key SHALL be unique for any plugin-authored `pluginId`, action `id` and child `id`, without throwing for any string a bundle can produce, including a lone surrogate (the shape `slice` and `[0]` produce from an astral character). Because the key is also a palette row's React key and cmdk value, two entries SHALL never share one.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-002.5:** A plugin-provided value that is not a usable icon SHALL resolve to the surface's fallback glyph rather than reaching `createElement` as an element type. Context menus SHALL additionally render a ready-made element unchanged, which is the shape plugins registered before icon resolution existed still send; that tolerance SHALL be documented as menu-only.
|
||||
|
||||
### REQ-PLUGINS-TASK-MENU-SUBMENUS-003: Submenu children are reachable from the command surfaces
|
||||
|
||||
**Intent:** A card's plugin contribution should be usable from the same
|
||||
task-action surfaces that already list card actions, rather than only inside the
|
||||
card's own menu.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-003.1:** A `primary`-group submenu SHALL contribute one command per child to the command palette and the sidebar's task commands, each carrying the trigger's label as its `context` so a bare child label stays identifiable; the sidebar SHALL keep the task title as the default `context` for commands that do not set their own.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-003.2:** Group `edit` SHALL remain card-only: its submenu children SHALL NOT appear in the command palette or the sidebar's task commands.
|
||||
- **AC-PLUGINS-TASK-MENU-SUBMENUS-003.3:** A surface that reuses already-built plugin entries SHALL produce them from the same inputs it renders with, and a caller that forces the flat `Edit` form SHALL NOT receive a prebuilt set that could contain the nested `Edit` submenu.
|
||||
|
||||
## Exclusions
|
||||
|
||||
- No nested plugin submenus: a child is a selectable item, never another submenu.
|
||||
- No asynchronous `items()`: a menu entry cannot await, so a thenable is treated as a contract violation and falls back.
|
||||
- The palette lists submenu children as flat commands; it does not render a nested palette submenu.
|
||||
- Group `edit` gains no palette or sidebar placement.
|
||||
- The host does not validate or repair a plugin's ids, labels or icons at registration time; malformed input is handled where it is used.
|
||||
|
||||
## System design
|
||||
|
||||
The technical source for these requirements is
|
||||
[plugin-task-menu-submenus](../system-design/plugin-task-menu-submenus.md).
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
status: draft
|
||||
system: plugins
|
||||
requirements:
|
||||
- REQ-PLUGINS-TASK-MENU-SUBMENUS-001
|
||||
- REQ-PLUGINS-TASK-MENU-SUBMENUS-002
|
||||
- REQ-PLUGINS-TASK-MENU-SUBMENUS-003
|
||||
created: 2026-09-23
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# Plugin task menu submenus System Design
|
||||
|
||||
## Purpose and boundaries
|
||||
|
||||
This design covers the host half of plugin task-menu submenus: the registration
|
||||
contract, the one boundary that reads plugin values, the entry builder every card
|
||||
and row surface uses, and the flattening that makes submenu children reachable
|
||||
from the command palette and the sidebar's task commands.
|
||||
|
||||
It does not cover the plugin-facing authoring guide itself, the plugin-side
|
||||
implementation that consumes the contract, or host-owned menu entries other than
|
||||
plugin actions. Rendering changed no component: `KanbanCardMenuEntry` already
|
||||
models `kind: "submenu"` for the built-in Move to / Priority / Link menus and both
|
||||
renderers recurse, so cards, the shared desktop/mobile task-row menu, the
|
||||
preview/detail menus and the palette inherit submenus from one entry model.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-PLUGINS-TASK-MENU-SUBMENUS-001` | [Registration contract](#registration-contract), [Entry building](#entry-building), [The reading boundary](#the-reading-boundary) |
|
||||
| `REQ-PLUGINS-TASK-MENU-SUBMENUS-002` | [The reading boundary](#the-reading-boundary), [Keys and identity](#keys-and-identity), [Icon resolution](#icon-resolution) |
|
||||
| `REQ-PLUGINS-TASK-MENU-SUBMENUS-003` | [Command surfaces](#command-surfaces), [Shared entry reuse](#shared-entry-reuse) |
|
||||
|
||||
## Registration contract
|
||||
|
||||
`TaskMenuActionRegistration` gains optional `items?(context)`. `run` stays
|
||||
required, so there is one contract for two host generations: a host predating the
|
||||
field reads only `label`, `icon` and `run` and renders the flat item, and a build
|
||||
whose `items()` yields nothing usable does the same. The host never awaits a menu
|
||||
item, so `items()` is synchronous by contract.
|
||||
|
||||
`TaskMenuSubItemRegistration` is deliberately smaller than the parent: `id`,
|
||||
`label`, optional `icon` and `disabled`, and `run`. It has no `group` and no
|
||||
`visible`, because a child exists only inside its parent's submenu, and its own
|
||||
nesting is not supported.
|
||||
|
||||
## Entry building
|
||||
|
||||
`pluginMenuEntry` produces exactly one `KanbanCardMenuEntry | null` per
|
||||
registration: a `submenu` when `pluginSubItems` returns usable children, otherwise
|
||||
a flat `item`, otherwise `null` for a registration the host cannot render. Both
|
||||
callers — `buildPrimaryPluginEntries` (group `primary`) and `buildEditMenuEntry`
|
||||
(group `edit`, nested inside the native `Edit` item) — filter that `null`.
|
||||
|
||||
`buildEditMenuEntry` builds and filters the plugin entries **before** choosing
|
||||
between the submenu and the flat item, so a registration list that yields nothing
|
||||
still leaves the native `Edit` item exactly as it was rather than wrapping it in a
|
||||
submenu with no plugin child (AC-PLUGINS-TASK-MENU-SUBMENUS-002.3).
|
||||
|
||||
`buildCardPluginEntries` builds the two plugin-derived pieces of a card menu once
|
||||
per render from the card's own inputs, and `useKanbanCardMenus` passes that result
|
||||
to both the dropdown and the context variant, so a plugin's `items()` runs once per
|
||||
card per render rather than twice.
|
||||
|
||||
## The reading boundary
|
||||
|
||||
`pluginSubItems` is the single place where host code reads a plugin's `items()`
|
||||
result, and its whole body is one `try`. A plugin object may throw from any
|
||||
property access — including the array methods a naive implementation would call
|
||||
and the `then` lookup a naive thenable check would perform — so:
|
||||
|
||||
- the result is copied with `Array.from`, which never calls a method on the
|
||||
plugin's own object;
|
||||
- every child is read once, inside the guard, into a snapshot of plain values, so
|
||||
a throwing getter or a Proxy fails that child and nothing is read twice;
|
||||
- `id` and `label` must be non-blank strings after trimming, `run` must be
|
||||
callable, `disabled` must be a boolean or `null`, and `icon` must be a curated
|
||||
name, a component, a ready-made element or `null`;
|
||||
- duplicate ids keep their first occurrence and the repeat is reported;
|
||||
- a throw, a thenable, a non-array, an empty list or an all-unusable list return
|
||||
`null`, which is AC-PLUGINS-TASK-MENU-SUBMENUS-001.3's flat fallback.
|
||||
|
||||
Defects are reported through one helper keyed by action identity **and kind**, so
|
||||
a registration that fails every render is reported once while a later, different
|
||||
defect on the same action still reports. The helper never interpolates a raw
|
||||
plugin value into a message: template interpolation calls `ToString`, which throws
|
||||
for a `Symbol` id or a null-prototype object, and the omission paths are exactly
|
||||
where such a value arrives (AC-PLUGINS-TASK-MENU-SUBMENUS-002.2). The read of the
|
||||
registration's own `label`, `id` and `icon` is guarded for the same reason, and a
|
||||
registration missing any of them contributes no entry.
|
||||
|
||||
The registry also reads each action inside a guard when it filters by group and
|
||||
copies the registration. It skips an action whose getter or Proxy throws, reports
|
||||
that registration once, and keeps other actions available. It does not validate
|
||||
the registration when the plugin registers it.
|
||||
|
||||
The set of already-reported defects is module state that is never cleared. A
|
||||
defect of the *same* kind that recurs on the same action after a plugin generation
|
||||
swap therefore stays silent for the life of the page; that is a deliberate
|
||||
tradeoff for a diagnostic line, and it is documented at the helper rather than
|
||||
implied.
|
||||
|
||||
## Keys and identity
|
||||
|
||||
A plugin entry key is `"<prefix>-<encoded pluginId>%<encoded action id>"`, and a
|
||||
child's key is `"<parent key>#<encoded child id>"`. Both ids are plugin-authored
|
||||
strings and the palette flattens every plugin entry into one list where a key is
|
||||
both a React key and cmdk's value, so the encoding has to be injective for any
|
||||
string a bundle can produce.
|
||||
|
||||
`encodeKeyPart` percent-encodes per UTF-16 code unit, escaping everything
|
||||
`encodeURIComponent` would not leave alone. Two properties matter:
|
||||
|
||||
- it cannot throw. `encodeURIComponent` raises `URIError` on a lone surrogate,
|
||||
which `slice` or `[0]` produce from an astral character, and that exception
|
||||
leaves the builder a card calls during render with no error boundary above it.
|
||||
- it is injective. `%` is itself escaped, and every escape is exactly four hex
|
||||
digits, which makes each token self-delimiting so no escaped unit can run into
|
||||
the literal characters that follow it — `"%0"` and `"\u0250"` must not share a
|
||||
key, and neither may two different `(pluginId, actionId)` pairs whose ids
|
||||
differ only in how a dash join would spell them.
|
||||
|
||||
A child key always contains the `#` separator and a flat key never does, because
|
||||
encoded ids contain neither `#` nor a bare `%`, so a child key can never equal a
|
||||
flat action's key.
|
||||
|
||||
## Icon resolution
|
||||
|
||||
`lookupPluginIcon` resolves a curated name for strings only, and passes through a
|
||||
component — including React's exotic components. `memo` and `forwardRef` return
|
||||
objects that are callable per their types but not at run time, and
|
||||
`@tabler/icons-react`, the set the curated map itself is built from, produces
|
||||
exactly that shape, so a plain `typeof` check would reject the host's own icons.
|
||||
`lazy` is excluded deliberately: it cannot resolve synchronously in a menu and
|
||||
would suspend the menu's content. Elements are excluded here too, because this
|
||||
function's result is passed to `createElement` by every non-menu surface; the
|
||||
menu's own path returns an element unchanged before reaching it, which is the
|
||||
documented, menu-only element tolerance (AC-PLUGINS-TASK-MENU-SUBMENUS-002.5).
|
||||
The lookup resolves own keys only, so `PLUGIN_ICONS["__proto__"]` or
|
||||
`["constructor"]` cannot resolve through the prototype chain to a non-icon.
|
||||
|
||||
## Command surfaces
|
||||
|
||||
`pluginCommandChoices` walks a built entry and turns a submenu into one command
|
||||
per selectable child, carrying the trigger's label as the command's `context`;
|
||||
`buildSidebarTaskCommands` preserves a command's own `context` and keeps the task
|
||||
title as the default for everything else. The palette feeds it group `primary`
|
||||
entries only, so `edit` stays card-only
|
||||
(AC-PLUGINS-TASK-MENU-SUBMENUS-003.1, AC-PLUGINS-TASK-MENU-SUBMENUS-003.2). A
|
||||
command's id is the entry key, which is what makes the two properties above matter
|
||||
to the palette as well.
|
||||
|
||||
## Shared entry reuse
|
||||
|
||||
`BuildKanbanCardMenuEntriesArgs` accepts prebuilt plugin entries so one card
|
||||
render can share them between its variants. Because those entries carry a disabled
|
||||
state, an edit handler and a menu context, `forceFlatEdit` outranks a prebuilt set
|
||||
inside `buildKanbanCardMenuEntries`, and the non-card menu tiers additionally drop
|
||||
any set they are handed: a surface that forces the flat `Edit` form must never
|
||||
render the nested `Edit` submenu those entries could contain
|
||||
(AC-PLUGINS-TASK-MENU-SUBMENUS-003.3). The field is documented as valid only for a
|
||||
call whose inputs match the ones the entries were built from; it is not
|
||||
runtime-guarded, because no caller passes a mismatch today and the guard would
|
||||
need the inputs carried alongside for a hazard that does not exist yet.
|
||||
|
||||
## Compatibility and failure behavior
|
||||
|
||||
- A host predating `items` ignores it: the field is additive and `run` is
|
||||
unchanged, so every existing plugin keeps its exact behavior.
|
||||
- A registration the host cannot render contributes nothing and is reported,
|
||||
rather than rendering a broken row.
|
||||
- A child the host cannot render is dropped, reported once, and the remaining
|
||||
children still render; if none remain the action falls back to its flat item.
|
||||
- An exception anywhere in the plugin's `items()`, or in reading a registration's
|
||||
own fields, degrades at the boundary instead of propagating out of a render.
|
||||
|
||||
## Amendment log
|
||||
|
||||
**Amendment 1 (2026-09-23), from the adversarial review loop on PR #3874.** The
|
||||
first implementation of this design used `encodeURIComponent` for the key parts
|
||||
and a variable-width escape for the fallback encoder, and reported defects with a
|
||||
raw template interpolation of the action's identity. Three defects came out of
|
||||
review, each with a reproduction: an id containing a lone surrogate threw
|
||||
`URIError` out of the card's render; `"%0"` and `"\u0250"` collided because a
|
||||
two-digit escape is not self-delimiting; and a `Symbol` or null-prototype id made
|
||||
the defect report itself throw. The contract is unchanged; the implementation now
|
||||
escapes per code unit at a fixed width, reads plugin values defensively on every
|
||||
path that reports them, admits `memo`/`forwardRef` component objects while
|
||||
excluding `lazy` and elements, treats `null` as absent for both `icon` and
|
||||
`disabled`, and keeps the native `Edit` item flat when no plugin entry wraps it.
|
||||
Reference in New Issue
Block a user