Skip to content

Build your personal knowledge base with Trilium Notes

docs(skills): record the dropdown rewrite's rules and testing traps

Elian Doranb074199bda43
diff --git a/.claude/skills/building-client-ui/SKILL.md b/.claude/skills/building-client-ui/SKILL.md
index 869a6691b5..20fbe951cf 100644
--- a/.claude/skills/building-client-ui/SKILL.md
+++ b/.claude/skills/building-client-ui/SKILL.md
@@ -68,7 +68,7 @@ Form controls:
Buttons and links:
-- `Button` — the general button (also carries the tooltip for a *disabled* control via a wrapper, since a disabled `<button>` emits no pointer events). `ActionButton` — icon button with consistent styling.
+- `Button` — the general button (also carries the tooltip for a *disabled* control via a wrapper, since a disabled `<button>` emits no pointer events). `ActionButton` — icon button with consistent styling. `SplitButton` — a button with its related actions in a `Dropdown` menu on a toggle beside it; its rows are `FormListItem`s.
- `HelpButton`, `HelpTooltipButton`, `HelpDropdown` — open in-app help pages; don't invent a new "?" affordance.
- `KeyboardShortcut` — renders a shortcut as keycaps.
@@ -93,7 +93,7 @@ Display and layout:
- `Alert`, `InfoBar`, `Admonition`, `ContentErrorMessage`, `RenderErrorCard` — inline notices and error surfaces of increasing weight.
- `Card` — a titled group of sections (filter-aware under `FilterProvider`). `Collapsible` — animated, theme-styled expandable section with self-managed `initiallyExpanded`; `ExternallyControlledCollapsible` is the controlled variant (caller owns `expanded`/`setExpanded`).
- `TabStrip` — a row of icon-only tabs named by tooltips, heading a panel divided into groups.
-- `Modal`, `WizardModal` — dialogs; `Popover` — a small surface anchored beside something (portaled to the body, so no scroll container clips it).
+- `Modal`, `WizardModal` — dialogs; `Popover` — a card anchored beside something, with an arrow pointing at it, as the calendar's event card (portaled to the body and placed by `placeFloating()`, so no scroll container clips it).
- `LoadingSpinner`, `LazyComponent`, `Icon`, `MaskedIcon`, `NoteList`, `SiblingNavigator`, `ImageViewer`, `CodeBlock`, `charts/DonutChart`, `charts/Treemap`.
Data grids and calendars (outside `widgets/react/`, but equally generic):
@@ -117,6 +117,21 @@ Both kinds of dropdown share a toggle and open in a `Popup` portaled onto `<body
A wrong pick fails quietly: a form in a `Dropdown` loses Up, Down, Tab and Escape to the menu, and a list of rows in a `DropdownPanel` gets none of the menu's keys. On a phone, pass `mobileBottomSheet` to open either as a sheet from the bottom of the screen over a dimmed page.
+Rules for both:
+
+- **Placement and closing are props of their own**: `placement` takes Floating UI's names (`"top"`, `"bottom-end"`, …) and flips near the viewport's edge; `autoClose` is `true`, `"inside"`, `"outside"` or `false`. There is no Bootstrap or Popper config to pass.
+- **A bottom sheet is only ever `mobileBottomSheet`.** Never put `mobile-bottom-menu` in `dropdownContainerClassName`: the stylesheet then pins the popup to the bottom while Floating UI still places it beside its toggle, and Floating UI's inline `max-height` caps the sheet to the room the toggle had. `mobileBottomSheet` also dims the page, so it needs no `mobileBackdrop`.
+- **`dropdownRef` holds a `DropdownHandle`** (`show`, `hide`, `toggle`), exported from `Dropdown.tsx`. Type the ref with it, never with Bootstrap's `Dropdown`, which compiles but promises methods the handle doesn't have.
+- **Submenus**: `FormDropdownSubmenu` opens a submenu only inside a `Dropdown` menu (elsewhere, its title is rendered as a header above its rows). Which side a submenu opens on, and which way its row's arrow points, is detected from the room around the menu; there is no prop for it.
+- **Style a popup by its own classes.** It lives in `<body>`, inside a `.tn-dropdown-portal` wrapper that carries the dropdown's `className`, so a rule scoped under the toggle's ancestors (`.status-bar .dropdown-menu`) never matches it. Use `dropdownContainerClassName` with top-level rules. Its z-index (1200, over dialogs) is set in `Popup.css`; `--bs-dropdown-zindex` doesn't reach it.
+
+Other floating surfaces:
+
+- **Position with `placeFloating()`** from `Popup.tsx`, under Floating UI's `autoUpdate()`, as `Popup`, submenu layers and `Popover` do. Its `arrow` option places a pointer element. Don't bring back Popper (`createPopper`): the client no longer uses it directly, and it stays installed only as Bootstrap's peer dependency.
+- **A cover or backdrop that disappears with its popup lets the dismissing tap's click through.** The press closes the popup and hides the cover before the browser sends the click, which then lands on whatever was under the cover. `Popup` drops that click (`swallowStrayClick`); a custom surface with a cover needs the same.
+- **Any element with `.dropdown-menu` that isn't a Bootstrap dropdown must capture Up, Down and Escape on `window`.** Bootstrap's handler captures them on `document` for every `.dropdown-menu` and throws when no `data-bs-toggle` is next to it. `Popup`, `Menu` and `FormList` do this; a new surface that reuses the class for its styling needs it too.
+- **`FormList`**, the always-open list in the note type chooser, revisions and font pickers, moves focus with Up and Down through `focusListItem()`, as `DropdownPanel` does, not with the menu's keyboard model.
+
## Controls floating over a note's content
Any control laid **over** a note's own content — a geo map, a mind map, an image, a video, a diagram, a presentation, and whatever comes next — goes on one of two shared components. **Never hand-roll a `<button>` with `tn-overlay-*` classes**: those classes are the components' business, and a site that writes them itself also has to write the ref, the tooltip, the `aria-label` and the `type="button"` that the component already owns.
diff --git a/.claude/skills/writing-unit-tests/client-components.md b/.claude/skills/writing-unit-tests/client-components.md
index 51f847861a..f7887e1d4b 100644
--- a/.claude/skills/writing-unit-tests/client-components.md
+++ b/.claude/skills/writing-unit-tests/client-components.md
@@ -147,6 +147,10 @@ describe("ActionButton", () => {
- **`isMobile()`/`isDesktop()` are cached at module load** (`const cachedIsMobile = isMobile()` in `Button`/`ActionButton`). To exercise both branches, `vi.mock("../../services/utils")` **before** importing the component — a runtime spy is too late.
- **`Modal`** visibility is driven by the bootstrap Modal instance + `openDialog` (jQuery) inside `useEffect`; show/hide won't behave under happy-dom. Treat it as integration-tier; in happy-dom only assert its static structure with `show`.
+- **Preact runs `useEffect` after the next frame**, so a listener registered there is not in place when a spec dispatches an event right after `render`, and `await new Promise(r => setTimeout(r))` is not long enough. Register listeners the first interaction needs in `useLayoutEffect` (as `FormList` and `Popup` do), or `vi.waitFor` the effect's result.
+- **`t()` returns `undefined`** without an initialized i18next, and Preact then drops the attribute. To assert on a translated label, `vi.mock("../../services/i18n", () => ({ t: (key: string) => key }))` and expect the key.
+- **Popups placed by Floating UI** (`Popup`, `Menu`, `Dropdown`, `Popover`) need sizes, since happy-dom lays out nothing: stub `document.documentElement`'s `clientWidth`/`clientHeight` and `HTMLElement.prototype`'s `offsetWidth`/`offsetHeight`, and give the anchor a rect with `vi.spyOn(anchor, "getBoundingClientRect")`. Don't stub `getBoundingClientRect` on the whole prototype: Floating UI also measures `<html>`, and the popup lands somewhere else. Where several elements need rects, stub by selector (`this.matches(".tn-menu, .dropdown-item")`) and fall back to the original. Worked examples: `Popup.spec.tsx`, `Menu.spec.tsx`, `Dropdown.spec.tsx`.
+- **Bootstrap's dropdown key handler is live in specs** (`setup.ts` imports Bootstrap). It captures Up, Down and Escape at `document` for any `.dropdown-menu` and throws when no `data-bs-toggle` is next to it, so a spec that presses those keys in a toggle-less `.dropdown-menu` fails with `reading 'parentNode'` unless the component captures them first.
- Pre-existing stderr noise (KaTeX "quirks mode", the `setup.ts` "vi.mock not at top level" warning) is **not** a failure — ignore it.
## Optional ergonomic upgrade
diff --git a/CLAUDE.md b/CLAUDE.md
index ec9ea55ab3..109494b96f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,6 +33,7 @@ pnpm dev:format-check | dev:format-fix # stylistic formatting
- **The issue-closing keyword goes in the commit/PR subject**, not the body — `fix(markdown): wrap imported tables (closes #10270)`. A bugfix commit **must** carry it.
- **That keyword is the only way an issue is ever closed or annotated.** Never post a comment on a GitHub issue, never `gh issue close`, never change labels — the maintainer speaks to reporters, and the merge closes the issue. Reading issues (`gh issue view`) is fine; writing to them is not.
- **`git rm` is not a neutral delete.** It leaves the deletion staged, so a commit made before the matching reference updates are staged lands a `HEAD` pointing at a module that no longer exists. When removing a file whose references are edited in the same pass, delete it from the filesystem instead, or land the deletion and the reference updates together — never leave the index in a state that is broken on its own.
+- **Commit by explicit path** — `git commit -F <message file> -- <paths>`, not whatever the index holds. The user stages and unstages in this worktree too, so between two commands the index can gain their files or lose yours. Give each commit its own message file: a `Write` onto an existing path that has not been read fails, and the commit then takes the old message.
- **Never run a tree-wide git operation — no `git stash`, `git checkout --`, `git restore`.** The user edits this worktree at the same time, so a stash takes their uncommitted work with it, and their IDE can flush a partial buffer onto the stashed state and block the pop. To decide whether a failure predates your change, argue statically instead — check whether the failing spec even imports the module you touched. If a real A/B is unavoidable, copy the file, edit it in place, and restore it, touching only files you wrote; prefer `git worktree add` on a temp dir over anything that reaches the whole tree.
### Opening a PR