256 lines
16 KiB
Markdown
256 lines
16 KiB
Markdown
---
|
|
status: draft
|
|
system: plugins
|
|
requirements:
|
|
- REQ-PLUGINS-PLUGIN-NAV-SIDEBAR-FOOTER-001
|
|
created: 2026-08-12
|
|
owners:
|
|
- nova28
|
|
---
|
|
# Plugin nav items in the sidebar footer icon row System Design Part 1
|
|
|
|
## Purpose and boundaries
|
|
|
|
This design preserves the technical source detail for `REQ-PLUGINS-PLUGIN-NAV-SIDEBAR-FOOTER-001` during migration.
|
|
|
|
## Requirement mapping
|
|
|
|
| Requirement | Design section |
|
|
| --- | --- |
|
|
| `REQ-PLUGINS-PLUGIN-NAV-SIDEBAR-FOOTER-001` | [Migrated source detail](#migrated-source-detail) |
|
|
|
|
## Migrated source detail
|
|
|
|
## Amendment log
|
|
|
|
**Amendment 1 (2026-08-12), from PR #2562 review.** The first version of this spec
|
|
exposed the host's internal `NavSection` value `"insights"` as the plugin-facing
|
|
`NavItem.section` value, and decided against any capacity policy on the footer row.
|
|
A maintainer review on the open PR raised both as contract defects. Both are accepted;
|
|
this document is the amended contract, and the two decisions are recorded in
|
|
**Plugin-facing section vocabulary** and **Capacity and overflow** with the reasoning
|
|
that replaces the original.
|
|
|
|
Status returns to `draft` because the amended contract is not implemented. The
|
|
already-merged-into-the-branch first version is implemented; the amendment is not. The
|
|
status returns to `shipped` when PR #2562 merges carrying this contract, and
|
|
`docs/specs/INDEX.md` tracks the same value.
|
|
|
|
**Amendment 1, spec-review round 1 corrections (2026-08-12).** The amended contract went
|
|
through an adversarial spec review (cross-vendor and cross-model legs) and came back
|
|
FIX FIRST. No acceptance criterion changed meaning; the review found document defects,
|
|
not contract defects. Corrections applied, listed so a later reader can tell them apart
|
|
from the contract itself:
|
|
|
|
- **Missing/`null` `label` is now stated.** `Rendered identity` claimed the accessible
|
|
name is `NavItem.label` verbatim, which is false when a bundle omits `label` —
|
|
`destinationLabel()` substitutes the destination id. Qualified there, and given its own
|
|
bullet under **Failure modes**. Existing behaviour; nothing to build.
|
|
- **The inline budget's test obligation is now stated.** `MAX_INLINE_PLUGIN_FOOTER_ITEMS`
|
|
is normatively `3` while **Why 3** says the number may move freely; those could not both
|
|
hold for a test hard-coding `3`. Resolved by exporting the constant and requiring
|
|
conformance tests to derive from it.
|
|
- **A `Type surface` scenario group was added** so the `PluginNavSection` named export —
|
|
half of what this amendment delivers — is observed by something. Every other scenario
|
|
tests runtime placement and would pass against an inline, un-exported union.
|
|
- **The edit inventory now marks each entry EDIT or VERIFY-NOT-EDIT.** Its preamble
|
|
claimed every named file carries contradicting prose; entries 2, 3 and 6 were already
|
|
corrected by the first implementation on this branch.
|
|
- **The overflow trigger's test id changed** from `sidebar-insights-overflow-button` to
|
|
`sidebar-plugin-overflow-button`. Adopted from a reviewer's noted question rather than a
|
|
finding: the first spelling minted the host's internal section name `insights` into a
|
|
contract-ish identifier in the same document that removes that name from the plugin API.
|
|
Host test ids are host-owned, so this was not a defect, but nothing implements the
|
|
trigger yet, so the rename is free now and never again.
|
|
- **Stray tool-call markup** (`</content>`, `</invoke>`) committed at the end of this file
|
|
was deleted.
|
|
|
|
**Amendment 1, spec-review round 2 corrections (2026-08-12).** A second adversarial review
|
|
(both legs again: cross-vendor codex, cross-model `scope-analyst`) re-verified roughly
|
|
thirty existence citations by grep and found **zero dangling references and zero false
|
|
claims** — the contract itself was not disputed. It returned FIX FIRST on four coverage and
|
|
document-accuracy defects, all closed here without changing what any acceptance criterion
|
|
means:
|
|
|
|
- **The `Type surface` "by name" scenario was unobservable by its own runner.** Both legs
|
|
found this independently. TypeScript is structural, so `pnpm run typecheck` cannot tell a
|
|
named alias from an identical inline union, and the scenario as written asked for a check
|
|
no typecheck can perform. Rewritten so the observable is a **type-equality assertion**
|
|
between `NavItem["section"]` and `PluginNavSection | undefined`, with a new paragraph
|
|
saying plainly that spelling is not observable, that a builder must not invent an AST or
|
|
source-text assertion, and that the declared-by-name requirement belongs to **API
|
|
surface** and is settled in review.
|
|
- **The overflow trigger's label was normative but unobserved.** `sidebar:morePluginItems`
|
|
was specified in **Capacity and overflow** while every capacity scenario selected the
|
|
trigger by `data-testid` alone, so wiring it to a different existing key would have passed
|
|
the whole suite. A scenario now pins the key.
|
|
- **Edit-inventory entry 6 pointed capacity coverage at the wrong file.** Its parenthetical
|
|
sent the capacity scenarios to `plugin-destinations.test.ts`, a pure mapping unit test
|
|
that cannot see a partition living in `app-sidebar-footer.tsx`. Corrected to name the
|
|
footer component's own test file, with an explicit "do not import the footer component
|
|
into this file" instruction.
|
|
- **The `P = 0` baseline scenario had no determinate expected set.** "Shows exactly the
|
|
buttons it shows today" reads as a claim about every footer control, five of which render
|
|
conditionally. The scenario now states three assertable clauses, and **Ordering**'s
|
|
manifest-rows-only rule was widened from ordering statements to **presence and count
|
|
statements** as well, so this class of false failure is ruled out once rather than per
|
|
scenario.
|
|
|
|
Two outside-voice findings were refuted rather than adopted, for the second time and on the
|
|
same grounds: missing/`null`/empty `NavItem.id` and `NavItem.path` are pre-existing,
|
|
section-independent pass-throughs on which this change adds no branch and the builder writes
|
|
no code. Only the `label` case earned a **Failure modes** bullet, because only it needed a
|
|
*negative* instruction (do not add a fallback).
|
|
|
|
**Renamed from `plugin-nav-insights-section` to `plugin-nav-sidebar-footer` (2026-08-12),
|
|
at the owner's request.** The old slug named the host's *internal* nav section, `insights`
|
|
— the very coupling this amendment removes from the plugin API — and it read as though the
|
|
feature were specific to one (private, unreleased) Insights plugin rather than a placement
|
|
any plugin can request. The new slug matches the plugin-facing value `"sidebar-footer"`
|
|
exactly, so the spec slug, the public token and the authoring docs all use one word. Moved
|
|
with it: `docs/plans/plugin-nav-insights-section/` → `docs/plans/plugin-nav-sidebar-footer/`
|
|
(plan plus three task files) and the `docs/specs/INDEX.md` row. The internal section is
|
|
still named `insights` in `apps/web/lib/navigation/types.ts` and this document still calls
|
|
it that; only the plugin-facing and document-facing names changed.
|
|
|
|
## Why
|
|
|
|
A plugin whose page is a compact, glanceable dashboard has nowhere good to put its
|
|
entry point. `registerNavItem` can place a row in the sidebar's labelled plugin rail
|
|
or in the Integrations section, but not in the sidebar footer's unlabelled icon strip
|
|
(the gear / Stats / doctor / Office row) where Kandev's own at-a-glance destination,
|
|
Stats, lives. Plugin authors either accept a full-width labelled row that visually
|
|
outranks what they are contributing, or they get no placement that matches the shape
|
|
of their page.
|
|
|
|
## What
|
|
|
|
- `NavItem.section` SHALL accept a fourth value, `"sidebar-footer"`, in addition to the
|
|
existing `"main"`, `"integrations"`, and `"settings"`. The four values SHALL be
|
|
declared as a named exported type, `PluginNavSection`. See **Plugin-facing section
|
|
vocabulary** for why the value is `"sidebar-footer"` and not the host's internal
|
|
section name.
|
|
- A plugin nav item with `section: "sidebar-footer"` SHALL render as an icon button in
|
|
the desktop sidebar footer's icon row, styled and behaving exactly like the
|
|
first-party Stats button: icon only, tooltip and accessible name from
|
|
`NavItem.label`, click navigates to `NavItem.path` — subject to the inline budget in
|
|
**Capacity and overflow**, past which the item is reached through the footer's
|
|
overflow menu instead of an inline button.
|
|
- The same item SHALL also appear as a labelled row in the phone menu's Utilities
|
|
group, which is where the first-party Stats destination already appears below the
|
|
`md` breakpoint. The sidebar is hidden on phones, so a footer-only placement would
|
|
make the item unreachable there. The phone group is **not** subject to the inline
|
|
budget; see **Capacity and overflow**.
|
|
- A `"sidebar-footer"` item SHALL NOT also appear in the sidebar's plugin rail or the
|
|
phone menu's Plugins group. Choosing `sidebar-footer` moves the item; it does not
|
|
add a second placement.
|
|
- `"integrations"` and `"settings"` behaviour SHALL be unchanged: `"integrations"`
|
|
items still render alongside the first-party integration links on both surfaces,
|
|
and `"settings"` items are still skipped entirely by navigation, which means they
|
|
render on no surface at all. A `section: "settings"` nav item is **not** what fills
|
|
the settings tree's `PluginSlot`: that slot (`<PluginSlot name="settings-nav" />` in
|
|
`settings-tree.tsx`) is fed only by `registerComponent("settings-nav", …)`, and a
|
|
plugin that wants a settings page uses `registerSettingsRoute` / `registerComponent`.
|
|
`section: "settings"` on a nav item is accepted and then dropped.
|
|
- Any other `section` value, including omitted/`undefined` and a string outside the
|
|
documented set, SHALL continue to render in the plugin rail / Plugins group exactly
|
|
as `"main"` does. Plugin bundles are untyped JavaScript at runtime, so an unknown
|
|
value must degrade to the default placement rather than being dropped. **The literal
|
|
string `"insights"` is one such unknown value and SHALL degrade to the plugin rail**
|
|
— it is deliberately not an accepted alias; see **Plugin-facing section vocabulary**.
|
|
- Plugin footer items SHALL NOT appear in the command palette, unchanged from
|
|
every other plugin section. This follows structurally, not from a rule this spec
|
|
adds: `pluginDestinations()` stamps every plugin entry with `surfaces:
|
|
SIDEBAR_AND_MENU`, and the palette's Navigation group is
|
|
`useStaticDestinations("palette")` (`components/global-commands.tsx`), which filters
|
|
on that surface. **Plugins have no route into the command palette at all today, by
|
|
any API.** `registerKeybinding(id, handler)` is not one: it binds a handler to an id
|
|
declared in the plugin's manifest `ui.keybindings[]`, which the host dispatches from
|
|
a global capture-phase keydown listener (`hooks/use-plugin-shortcuts.ts`) — a
|
|
keyboard binding, not a palette row. Adding a plugin→palette route is a separate
|
|
feature (see **Out of scope**).
|
|
- The desktop footer SHALL render at most `MAX_INLINE_PLUGIN_FOOTER_ITEMS` plugin
|
|
buttons inline and reach any remainder through a single overflow menu. No item is
|
|
dropped. See **Capacity and overflow** for the value, the derivation, and the exact
|
|
rule.
|
|
- The public authoring documentation SHALL list `sidebar-footer` as an accepted
|
|
`section` value and describe where it renders. The site is named, not left to be
|
|
found: the `registerNavItem` row of the Frontend hook/API matrix in
|
|
[`docs/public/plugins-authoring.md`](../../../public/plugins-authoring.md). It is
|
|
the fifth entry in **Stale prose at the edit sites** below.
|
|
|
|
## Plugin-facing section vocabulary
|
|
|
|
### Decision
|
|
|
|
`NavItem.section` is typed by a named, exported union that is the plugin's vocabulary,
|
|
not the host's:
|
|
|
|
```ts
|
|
export type PluginNavSection = "main" | "settings" | "integrations" | "sidebar-footer";
|
|
```
|
|
|
|
The host's internal `NavSection` (`"primary" | "plugins" | "integrations" | "insights"
|
|
| "utilities"`, `apps/web/lib/navigation/types.ts`) stays internal. `pluginDestinations()`
|
|
translates between the two, and remains the only place that translation happens.
|
|
|
|
### Why this, and why not `"insights"`
|
|
|
|
The indirection this amendment names **already existed**; it was only unnamed and
|
|
leaking in one place. `sectionFor()` in `plugin-destinations.ts` has always been the
|
|
translation layer, and `"main"` has always mapped to the internal section `plugins` —
|
|
so three of the four plugin-facing values already differed from, or were independent
|
|
of, the internal taxonomy. `"insights"` was the single member that was spelled with the
|
|
host's internal name, which is what makes the coupling look like contract. Renaming
|
|
that one member and naming the union closes the leak without changing any of the three
|
|
shipped values.
|
|
|
|
The value is spelled after the **placement a plugin author is asking for**, not after
|
|
the host's grouping. The host can rename, split, or merge `NavSection` members without
|
|
a plugin-visible break, which is exactly the freedom the reviewer asked for and which
|
|
the previous version did not provide.
|
|
|
|
One objection was considered and rejected: `"sidebar-footer"` names a desktop surface,
|
|
while the item also renders in the phone menu's Utilities group, where there is no
|
|
sidebar. That asymmetry is real but does not win. The phone placement is a host
|
|
**reachability guarantee** — the sidebar does not exist below `md`, so the host puts the
|
|
item where its first-party peer (`Stats`) already goes — and not a second thing the
|
|
plugin declared. A plugin author asking for the footer strip gets the footer strip, plus
|
|
whatever the host must do to keep it reachable on a phone. A deliberately neutral token
|
|
(`"quick-access"`, `"glance"`) would be surface-independent but would tell an author
|
|
nothing about where their icon lands without reading the docs, and would be a novel
|
|
coined term where `"sidebar-footer"` is self-describing. The doc comment on the field
|
|
states both placements, so nothing is hidden.
|
|
|
|
### `"insights"` is not accepted, and not an alias
|
|
|
|
Passing `section: "insights"` from a plugin bundle SHALL be treated as an unrecognised
|
|
value and degrade to the plugin rail / Plugins group, exactly like `"footer"` or
|
|
`"banana"`. It is not accepted, not aliased, and produces no warning beyond the
|
|
existing (absent) validation.
|
|
|
|
This is safe and deliberate. Nothing has shipped: PR #2562 is open and unmerged, and
|
|
the one motivating consumer, `kandev-plugin-rill`, has not switched its `section` yet
|
|
(it is still `"main"`). There is no plugin in the wild passing `"insights"`, so there
|
|
is no compatibility burden to carry. Accepting both would make the internal name a
|
|
permanent de-facto public alias, re-creating the coupling this amendment removes on the
|
|
same day it removes it.
|
|
|
|
The consequence to be explicit about: the in-tree e2e fixture bundle
|
|
(`apps/backend/cmd/plugin-fixture/fixture-package/ui/bundle.js`) currently registers
|
|
`{ id: "e2e-insights-tools", …, section: "insights" }`. Under this contract that item
|
|
would silently move back to the plugin rail, so the fixture SHALL be updated to
|
|
`section: "sidebar-footer"` in the same change. It is entry 7 in **Stale prose at the
|
|
edit sites**.
|
|
|
|
### No runtime validation is added
|
|
|
|
There is still no runtime validation of `section` anywhere in the stack: the web
|
|
registry's `registerNavItem` pushes the item verbatim, and the backend plugin manifest
|
|
does not describe nav-item sections at all.
|
|
`apps/backend/internal/plugins/manifest/validate.go` validates a different, unrelated
|
|
enum (`ui.pages[].surface`, one of `settings | task-panel | main-nav`), which is not
|
|
this field and is not in scope. Introducing a validator, a console warning, or a
|
|
developer-mode diagnostic for an unrecognised `section` is **out of scope** — the
|
|
degrade rule is the whole error behaviour.
|