staffa 0.4.1 → 0.4.3

package/README.md

@@ -52,8 +52,9 @@ All components get their options in a typed object. The object may be an Aberdee
 ```ts
 const $btn = A.proxy({ content: "Save", disabled: false });
 S.button($btn);
-// ...later:
-$btn.disabled = true;  // button updates instantly
+setTimeout(() => // Later..
+  $btn.disabled = true;  // button updates instantly
+}, 3000);
 ```
 
 ### Rich text slots
@@ -175,13 +176,10 @@ Components share naming conventions for options: `attrs` (outermost element), `c
 
 Staffa ships the full [Lucide icon set](https://lucide.dev/icons/) as named exports. Import only the ones you use, so a bundler tree-shakes the rest (the whole set is ~82 kB gzipped):
 
-```ts
-import { sparkles, bell } from "staffa/icons.js";
-```
-
 Each icon is a draw function usable anywhere a slot is accepted (e.g. a button `icon`), or called directly. Customize per call, or globally via `setDefaults()`:
 
 ```ts
+import { sparkles, bell } from "staffa/icons.js";
 S.button({ content: "Save", icon: bell });
 sparkles({ size: "1.5em", color: "var(--s-primary)", strokeWidth: 1.5 });
 ```
@@ -190,7 +188,7 @@ Options: `size`, `color` (defaults to `currentColor`), `strokeWidth`, `cap`, `jo
 
 ### Other
 
-- **`S.menuButton(opts)` / `S.showFloatingMenu(opts)`**: menu actions and floating menus, with keyboard navigation and submenus.
+- **`S.menuButton(opts)` / `S.addContextMenu(opts)` / `S.showFloatingMenu(opts)`**: dropdown menus from a button, right-click/long-press context menus, and the underlying floating menu primitive — with keyboard navigation.
 - **`S.toast(opts)`**: transient notification at the bottom of the viewport.
 - **`S.addTooltip(el, opts)`**: tooltip on hover, attached to an existing element.
 

package/dist/components/autocomplete.d.ts

@@ -34,11 +34,18 @@ export interface AutocompleteOptions extends FieldOptions {
  * @example
  * ```ts
  * // Single select from a fixed list
+ * const $sel = A.proxy("Netherlands");
  * S.autocomplete({ label: "Country", options: ["Belgium", "Netherlands"], bind: $sel });
  *
  * // Multi-select, disallowing custom items
- * S.autocomplete({ label: "Tags", multi: true, allowCustom: false,
- *   options: knownTags, bind: A.ref($post, "tags") });
+ * const $tags = A.proxy([] as string[]);
+ * S.autocomplete({
+ *   label: "Tags",
+ *   multi: true,
+ *   allowCustom: true,
+ *   options: ["Rust", "JS", "C++", "Klingon", "Go"],
+ *   bind: A.ref($tags)
+ * });
  * ```
  */
 export declare function autocomplete(opts: AutocompleteOptions): void;

package/dist/components/autocomplete.js

@@ -31,11 +31,18 @@ function normOption(o) {
  * @example
  * ```ts
  * // Single select from a fixed list
+ * const $sel = A.proxy("Netherlands");
  * S.autocomplete({ label: "Country", options: ["Belgium", "Netherlands"], bind: $sel });
  *
  * // Multi-select, disallowing custom items
- * S.autocomplete({ label: "Tags", multi: true, allowCustom: false,
- *   options: knownTags, bind: A.ref($post, "tags") });
+ * const $tags = A.proxy([] as string[]);
+ * S.autocomplete({
+ *   label: "Tags",
+ *   multi: true,
+ *   allowCustom: true,
+ *   options: ["Rust", "JS", "C++", "Klingon", "Go"],
+ *   bind: A.ref($tags)
+ * });
  * ```
  */
 export function autocomplete(opts) {

package/dist/components/box.d.ts

@@ -24,6 +24,7 @@ export interface BoxOptions extends ContentOptions {
  *
  * @example
  * ```ts
+ * const $user = A.proxy({name: "Kvothe"});
  * S.box({ header: "Profile", contentAttrs: "display:flex flex-direction:column", content: () => {
  *   S.textline({ label: "Name", bind: A.ref($user, "name") });
  * }});

package/dist/components/box.js

@@ -25,6 +25,7 @@ A.insertGlobalCss({
  *
  * @example
  * ```ts
+ * const $user = A.proxy({name: "Kvothe"});
  * S.box({ header: "Profile", contentAttrs: "display:flex flex-direction:column", content: () => {
  *   S.textline({ label: "Name", bind: A.ref($user, "name") });
  * }});

package/dist/components/button.d.ts

@@ -36,6 +36,7 @@ export interface ButtonOptions {
  * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
  * startup) for SPA-style navigation without manual click handlers:
  * ```ts
+ * import {interceptLinks} from from "aberdeen/route";
  * interceptLinks(); // once at root
  * S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
  * ```

package/dist/components/button.js

@@ -11,10 +11,9 @@ A.insertGlobalCss({
             "transition: background 0.15s, border-color 0.15s, color 0.15s, filter 0.15s, box-shadow 0.15s, transform 0.08s;",
         "&:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus;",
         "&:disabled, &[aria-disabled=true]": "opacity:0.45 cursor:not-allowed pointer-events:none filter:saturate(0.6)",
-        // Every button lifts a little toward the cursor on hover (the transform is in
-        // the transition list above). The filled `.gradient` CTA below layers a deeper
-        // shadow on top of the same lift, so it still reads as the signature action.
-        "&:hover": "filter: brightness(1.08); transform: translateY(-1px)",
+        // Hover feedback is colour-only (no movement). The filled `.gradient` CTA
+        // below layers a deeper shadow on top, so it still reads as the signature action.
+        "&:hover": "filter: brightness(1.08)",
         "&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-b 26%, transparent);",
         // A filled `.gradient` button (the default) is the app's signature call to
         // action: a borderless gradient with a hairline top highlight (a hint of
@@ -25,7 +24,7 @@ A.insertGlobalCss({
         // artifact where a gradient clipped to a transparent rounded border fringes
         // the edge with the gradient's far colour.
         "&.gradient:not(.tonal):not(.outlined)": "border:0 box-shadow: inset 0 1px 0 color-mix(in srgb, white 25%, transparent), $s-glow;",
-        "&.gradient:not(.tonal):not(.outlined):hover": "filter: brightness(1.05); box-shadow: inset 0 1px 0 color-mix(in srgb, white 25%, transparent), 0 7px 18px color-mix(in srgb, $s-primary 34%, transparent); transform: translateY(-1px);",
+        "&.gradient:not(.tonal):not(.outlined):hover": "filter: brightness(1.05); box-shadow: inset 0 1px 0 color-mix(in srgb, white 25%, transparent), 0 7px 18px color-mix(in srgb, $s-primary 34%, transparent);",
         // Subtle press feedback.
         "&:active:not(:disabled):not([aria-disabled=true])": "transform: translateY(1px)",
         // Size: set on the button itself, or inherited from a `.small`/`.large`
@@ -47,6 +46,7 @@ const ROLE_CLASS = /\.(gradient|primary|secondary|neutral|danger|success|warning
  * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
  * startup) for SPA-style navigation without manual click handlers:
  * ```ts
+ * import {interceptLinks} from from "aberdeen/route";
  * interceptLinks(); // once at root
  * S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
  * ```

package/dist/components/buttonGroup.d.ts

@@ -19,6 +19,8 @@ export interface ButtonGroupOptions extends ContentOptions {
  * Groups related buttons, either as a joined segmented control (`attached`) or
  * spaced out. A `role=group` is applied for assistive tech.
  *
+ * If you want a single button to be *selected*, use {@link buttonChooser}.
+ *
  * @example
  * ```ts
  * S.buttonGroup({ buttons: [

package/dist/components/buttonGroup.js

@@ -22,6 +22,8 @@ A.insertGlobalCss({
  * Groups related buttons, either as a joined segmented control (`attached`) or
  * spaced out. A `role=group` is applied for assistive tech.
  *
+ * If you want a single button to be *selected*, use {@link buttonChooser}.
+ *
  * @example
  * ```ts
  * S.buttonGroup({ buttons: [

package/dist/components/checkbox.d.ts

@@ -18,6 +18,7 @@ export interface CheckboxOptions extends Omit<FieldOptions, "label"> {
  *
  * @example
  * ```ts
+ * const $prefs = A.proxy({newsletter: true});
  * S.checkbox({ label: "Subscribe to newsletter", bind: A.ref($prefs, "newsletter") });
  * ```
  */

package/dist/components/checkbox.js

@@ -16,6 +16,7 @@ A.insertGlobalCss({
  *
  * @example
  * ```ts
+ * const $prefs = A.proxy({newsletter: true});
  * S.checkbox({ label: "Subscribe to newsletter", bind: A.ref($prefs, "newsletter") });
  * ```
  */

package/dist/components/dialog.d.ts

@@ -52,7 +52,7 @@ export interface DialogOptions {
  *   header: "Confirm",
  *   content: (close) => {
  *     A("p #Are you sure?");
- *     S.button({ content: "Yes", click: () => { doIt(); close(); } });
+ *     S.button({ content: "Yes", click: () => { S.alert("Nice!"); close(); } });
  *     S.button({ content: "Cancel", attrs: ".neutral .outlined", click: close });
  *   },
  * });
@@ -75,7 +75,7 @@ export declare function alert(message: string, opts?: Partial<DialogOptions>): P
  *
  * @example
  * ```ts
- * if (await S.confirm("Delete this item?")) deleteItem();
+ * if (await S.confirm("Delete this item?")) S.alert("Gone!");
  * ```
  */
 export declare function confirm(message: string, opts?: Partial<DialogOptions>): Promise<boolean>;
@@ -86,7 +86,7 @@ export declare function confirm(message: string, opts?: Partial<DialogOptions>):
  * @example
  * ```ts
  * const name = await S.prompt("Enter your name:", "Alice");
- * if (name !== null) greet(name);
+ * if (name !== null) S.alert(`Hi ${name}!`);
  * ```
  */
 export declare function prompt(message: string, defaultValue?: string, opts?: Partial<DialogOptions>): Promise<string | null>;

package/dist/components/dialog.js

@@ -78,7 +78,7 @@ mountPortal(() => {
  *   header: "Confirm",
  *   content: (close) => {
  *     A("p #Are you sure?");
- *     S.button({ content: "Yes", click: () => { doIt(); close(); } });
+ *     S.button({ content: "Yes", click: () => { S.alert("Nice!"); close(); } });
  *     S.button({ content: "Cancel", attrs: ".neutral .outlined", click: close });
  *   },
  * });
@@ -138,7 +138,7 @@ export function alert(message, opts = {}) {
  *
  * @example
  * ```ts
- * if (await S.confirm("Delete this item?")) deleteItem();
+ * if (await S.confirm("Delete this item?")) S.alert("Gone!");
  * ```
  */
 export function confirm(message, opts = {}) {
@@ -169,7 +169,7 @@ export function confirm(message, opts = {}) {
  * @example
  * ```ts
  * const name = await S.prompt("Enter your name:", "Alice");
- * if (name !== null) greet(name);
+ * if (name !== null) S.alert(`Hi ${name}!`);
  * ```
  */
 export function prompt(message, defaultValue = "", opts = {}) {

package/dist/components/form.d.ts

@@ -29,11 +29,12 @@ export interface FormOptions extends ContentOptions {
  *
  * @example
  * ```ts
+ * const $user = A.proxy({name: "Darth", email: "d.vader@example.com"});
  * S.form({
  *   submit: () => save(),
  *   content: () => {
- *     S.textline({ label: "Name", required: true, bind: A.ref($u, "name") });
- *     S.textline({ label: "Email", type: "email", bind: A.ref($u, "email") });
+ *     S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
+ *     S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
  *   },
  *   actions: () => S.button({ content: "Save", type: "submit" }),
  * });

package/dist/components/form.js

@@ -19,11 +19,12 @@ A.insertGlobalCss({
  *
  * @example
  * ```ts
+ * const $user = A.proxy({name: "Darth", email: "d.vader@example.com"});
  * S.form({
  *   submit: () => save(),
  *   content: () => {
- *     S.textline({ label: "Name", required: true, bind: A.ref($u, "name") });
- *     S.textline({ label: "Email", type: "email", bind: A.ref($u, "email") });
+ *     S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
+ *     S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
  *   },
  *   actions: () => S.button({ content: "Save", type: "submit" }),
  * });

package/dist/components/main.d.ts

@@ -66,9 +66,13 @@ export interface MainOptions {
  *   },
  *   navPosition: "left",
  *   menu: () => S.button({ content: "New", attrs: ".small" }),
- *   content: () => drawPage(),
+ *   content: drawPage,
  *   footer: "© 2026",
  * });
+ *
+ * function drawPage() {
+ *   S.box({title: "Hello world", content: "Here's you app.."});
+ * }
  * ```
  */
 export declare function main(opts?: MainOptions): void;

package/dist/components/main.js

@@ -89,9 +89,13 @@ A.insertGlobalCss({
  *   },
  *   navPosition: "left",
  *   menu: () => S.button({ content: "New", attrs: ".small" }),
- *   content: () => drawPage(),
+ *   content: drawPage,
  *   footer: "© 2026",
  * });
+ *
+ * function drawPage() {
+ *   S.box({title: "Hello world", content: "Here's you app.."});
+ * }
  * ```
  */
 export function main(opts = {}) {

package/dist/components/menu.d.ts

@@ -64,6 +64,9 @@ export interface FloatingMenuOptions {
     /** Aberdeen attr/style string on the floating panel. */
     dropdownAttrs?: Attributes;
 }
+/** Options for {@link addContextMenu} — like {@link FloatingMenuOptions}, but
+ * the anchor is the element the handler is attached to. */
+export type ContextMenuOptions = Omit<FloatingMenuOptions, "anchor">;
 /**
  * Draw a list of {@link MenuEntry} items into the *current* element, with
  * arrow-key / Home / End navigation between the focusable items. The single
@@ -85,16 +88,47 @@ export declare function drawMenu(items: MenuEntry[], onActivate?: () => void): v
  * no room below), and closes on Escape, Tab, item selection, or any click
  * outside the panel and anchor. Returns a `close()` function.
  *
+ * Menus are usually opened through {@link menuButton} or
+ * {@link addContextMenu}; reach for this primitive when you need to trigger a
+ * menu from some other event, anchored to an arbitrary element.
+ *
  * @example
  * ```ts
- * // Custom context menu:
- * el.addEventListener("contextmenu", (e) => {
- *   e.preventDefault();
- *   S.showFloatingMenu({ items, anchor: el });
+ * // An @-mention picker: typing "@" in the input pops up a user menu.
+ * A("input placeholder=Comment…", () => {
+ *   A("keydown=", (e: KeyboardEvent) => {
+ *     if (e.key !== "@") return;
+ *     S.showFloatingMenu({
+ *       anchor: e.currentTarget as HTMLElement,
+ *       items: users.map((u) => ({ label: u.name, click: () => mention(u) })),
+ *     });
+ *   });
  * });
  * ```
  */
 export declare function showFloatingMenu(opts: FloatingMenuOptions): () => void;
+/**
+ * Attaches a context menu to the current element: adds a `contextmenu` handler
+ * via {@link A} so a {@link showFloatingMenu | floating menu} opens (instead of
+ * the browser's own menu) on right-click or long-press. The menu is anchored to
+ * the element and closes on Escape, Tab, item selection, or any click outside.
+ *
+ * @example
+ * ```ts
+ * import * as icons from "staffa/icons";
+ *
+ * S.box(() => {
+ *   A("#Right-click / long-tap me!");
+ *   S.addContextMenu({
+ *     items: [
+ *       { label: "AI something", icon: icons.sparkles, click: () => ai() },
+ *       { label: "Launch missiles", icon: icons.rocket, click: () => launch() },
+ *     ],
+ *   });
+ * });
+ * ```
+ */
+export declare function addContextMenu(opts: ContextMenuOptions): void;
 /**
  * A button that opens a {@link showFloatingMenu | floating dropdown menu} on
  * click. Keyboard navigation: Arrow Up/Down, Home, End; Escape/Tab to close;

package/dist/components/menu.js

@@ -163,12 +163,21 @@ mountPortal(() => {
  * no room below), and closes on Escape, Tab, item selection, or any click
  * outside the panel and anchor. Returns a `close()` function.
  *
+ * Menus are usually opened through {@link menuButton} or
+ * {@link addContextMenu}; reach for this primitive when you need to trigger a
+ * menu from some other event, anchored to an arbitrary element.
+ *
  * @example
  * ```ts
- * // Custom context menu:
- * el.addEventListener("contextmenu", (e) => {
- *   e.preventDefault();
- *   S.showFloatingMenu({ items, anchor: el });
+ * // An @-mention picker: typing "@" in the input pops up a user menu.
+ * A("input placeholder=Comment…", () => {
+ *   A("keydown=", (e: KeyboardEvent) => {
+ *     if (e.key !== "@") return;
+ *     S.showFloatingMenu({
+ *       anchor: e.currentTarget as HTMLElement,
+ *       items: users.map((u) => ({ label: u.name, click: () => mention(u) })),
+ *     });
+ *   });
  * });
  * ```
  */
@@ -176,6 +185,37 @@ export function showFloatingMenu(opts) {
     $floating.opts = opts;
     return closeFloating;
 }
+/**
+ * Attaches a context menu to the current element: adds a `contextmenu` handler
+ * via {@link A} so a {@link showFloatingMenu | floating menu} opens (instead of
+ * the browser's own menu) on right-click or long-press. The menu is anchored to
+ * the element and closes on Escape, Tab, item selection, or any click outside.
+ *
+ * @example
+ * ```ts
+ * import * as icons from "staffa/icons";
+ *
+ * S.box(() => {
+ *   A("#Right-click / long-tap me!");
+ *   S.addContextMenu({
+ *     items: [
+ *       { label: "AI something", icon: icons.sparkles, click: () => ai() },
+ *       { label: "Launch missiles", icon: icons.rocket, click: () => launch() },
+ *     ],
+ *   });
+ * });
+ * ```
+ */
+export function addContextMenu(opts) {
+    let myEl = null;
+    A.clean(() => { if ($floating.opts?.anchor === myEl)
+        closeFloating(); });
+    A("contextmenu=", (e) => {
+        e.preventDefault();
+        myEl = e.currentTarget;
+        showFloatingMenu({ items: opts.items, anchor: myEl, dropdownAttrs: opts.dropdownAttrs });
+    });
+}
 /**
  * A button that opens a {@link showFloatingMenu | floating dropdown menu} on
  * click. Keyboard navigation: Arrow Up/Down, Home, End; Escape/Tab to close;

package/dist/components/tabs.d.ts

@@ -33,8 +33,8 @@ export interface TabsOptions {
  * @example
  * ```ts
  * S.tabs({ tabs: [
- *   { label: "Overview", content: () => A("p#...") },
- *   { label: "Settings", content: () => drawSettings() },
+ *   { label: "Overview", content: () => A("p#Let me give you an overview..") },
+ *   { label: "Settings", content: () => S.checkbox({label: "I agree to anything", checked: true}) },
  * ]});
  * ```
  */

package/dist/components/tabs.js

@@ -23,8 +23,8 @@ A.insertGlobalCss({
  * @example
  * ```ts
  * S.tabs({ tabs: [
- *   { label: "Overview", content: () => A("p#...") },
- *   { label: "Settings", content: () => drawSettings() },
+ *   { label: "Overview", content: () => A("p#Let me give you an overview..") },
+ *   { label: "Settings", content: () => S.checkbox({label: "I agree to anything", checked: true}) },
  * ]});
  * ```
  */

package/dist/components/textarea.d.ts

@@ -21,11 +21,12 @@ export interface TextareaOptions extends FieldOptions {
 }
 /**
  * A multi-line text input. Shares the field chrome and styling of
- * {@link textline}, adding `rows` and `resize` controls.
+ * {@link textline}.
  *
  * @example
  * ```ts
- * S.textarea({ label: "Bio", rows: 6, bind: A.ref($user, "bio") });
+ * const $user = A.proxy({bio: ""});
+ * S.textarea({ label: "Bio", bind: A.ref($user, "bio") });
  * ```
  */
 export declare function textarea(opts?: TextareaOptions): void;

package/dist/components/textarea.js

@@ -6,11 +6,12 @@ A.insertGlobalCss({
 });
 /**
  * A multi-line text input. Shares the field chrome and styling of
- * {@link textline}, adding `rows` and `resize` controls.
+ * {@link textline}.
  *
  * @example
  * ```ts
- * S.textarea({ label: "Bio", rows: 6, bind: A.ref($user, "bio") });
+ * const $user = A.proxy({bio: ""});
+ * S.textarea({ label: "Bio", bind: A.ref($user, "bio") });
  * ```
  */
 export function textarea(opts = {}) {

package/dist/components/textline.d.ts

@@ -32,6 +32,7 @@ export interface TextlineOptions extends FieldOptions {
  *
  * @example
  * ```ts
+ * const $user = A.proxy({email: "test@example.com"});
  * S.textline({ label: "Email", type: "email", required: true, bind: A.ref($user, "email") });
  * ```
  */

package/dist/components/textline.js

@@ -9,6 +9,7 @@ import { applyControlAttrs, drawField } from "./field.js";
  *
  * @example
  * ```ts
+ * const $user = A.proxy({email: "test@example.com"});
  * S.textline({ label: "Email", type: "email", required: true, bind: A.ref($user, "email") });
  * ```
  */

package/dist/components/toast.d.ts

@@ -28,8 +28,7 @@ export interface ToastOptions {
  * S.toast({ message: "Saved!", type: "success" });
  * S.toast({ title: "Error", message: "Upload failed.", type: "danger", duration: 0 });
  * const off = S.toast({ message: "Uploading…", duration: 0, dismissible: false });
- * // later:
- * off();
+ * setTimeout(off, 3000); // Later..
  * ```
  */
 export declare function toast(opts: ToastOptions): () => void;

package/dist/components/toast.js

@@ -22,6 +22,9 @@ let toastCount = 0;
 // Keyed by stable ID so A.onEach scopes are per-toast — removing one never re-renders others.
 const toasts = A.proxy({});
 mountPortal(() => {
+    // Only redraws when emptiness flips, keeping the DOM clean while no toasts show.
+    if (A.isEmpty(toasts))
+        return;
     A("div.s-toasts aria-live=polite aria-atomic=false", () => {
         A.onEach(toasts, (entry) => {
             const { opts } = entry;
@@ -59,8 +62,7 @@ function dismiss(id) {
  * S.toast({ message: "Saved!", type: "success" });
  * S.toast({ title: "Error", message: "Upload failed.", type: "danger", duration: 0 });
  * const off = S.toast({ message: "Uploading…", duration: 0, dismissible: false });
- * // later:
- * off();
+ * setTimeout(off, 3000); // Later..
  * ```
  */
 export function toast(opts) {

package/dist/components/tooltip.d.ts

@@ -20,11 +20,13 @@ export interface TooltipOptions {
  *
  * @example
  * ```ts
- * A("button #Save", () => {
+ * S.button(() => {
+ *   A("#Save");
  *   S.addTooltip({ tip: "Saves your work to the cloud" });
  * });
  *
- * A("button #Delete", () => {
+ * S.button(() => {
+ * 	 A(".danger#Delete");
  *   S.addTooltip({ tip: "Dangerous — cannot be undone", placement: "bottom" });
  * });
  * ```

package/dist/components/tooltip.js

@@ -102,11 +102,13 @@ mountPortal(() => {
  *
  * @example
  * ```ts
- * A("button #Save", () => {
+ * S.button(() => {
+ *   A("#Save");
  *   S.addTooltip({ tip: "Saves your work to the cloud" });
  * });
  *
- * A("button #Delete", () => {
+ * S.button(() => {
+ * 	 A(".danger#Delete");
  *   S.addTooltip({ tip: "Dangerous — cannot be undone", placement: "bottom" });
  * });
  * ```

package/dist/core.d.ts

@@ -57,10 +57,15 @@ export declare function uniqueId(prefix?: string): string;
  */
 export declare function drawSlot<Args extends unknown[] = []>(slot: Slot<Args> | undefined, ...args: Args): void;
 /**
- * Mount a portal (tooltip, toast, menu, dialog, …) in its own dedicated
- * container under `<body>`. Each portal gets a private parent element because
- * two `A.mount`s sharing one parent can't tell their nodes apart: a redraw of
- * one (e.g. a tooltip hiding) may sweep up nodes another portal inserted
- * earlier in the same parent (e.g. an open menu).
+ * Mount a portal (tooltip, toast, menu, dialog, …) directly into `<body>`.
+ * Must be called at module top level, where Aberdeen's root scope (whose
+ * element is `document.body`) is current. Separate `A.mount`s sharing a parent
+ * can't tell their nodes apart, but sibling scopes within the root scope track
+ * their positions, so portals coexist without wrapper elements and add nothing
+ * to the DOM while they draw nothing.
+ *
+ * Scope creation is deferred a microtask so that an app drawing into `<body>`
+ * at module top level gets its content *before* the portals, keeping overlays
+ * at the end of the document.
  */
 export declare function mountPortal(draw: () => void): void;

package/dist/core.js

@@ -18,15 +18,17 @@ export function drawSlot(slot, ...args) {
         A("rich=", slot);
 }
 /**
- * Mount a portal (tooltip, toast, menu, dialog, …) in its own dedicated
- * container under `<body>`. Each portal gets a private parent element because
- * two `A.mount`s sharing one parent can't tell their nodes apart: a redraw of
- * one (e.g. a tooltip hiding) may sweep up nodes another portal inserted
- * earlier in the same parent (e.g. an open menu).
+ * Mount a portal (tooltip, toast, menu, dialog, …) directly into `<body>`.
+ * Must be called at module top level, where Aberdeen's root scope (whose
+ * element is `document.body`) is current. Separate `A.mount`s sharing a parent
+ * can't tell their nodes apart, but sibling scopes within the root scope track
+ * their positions, so portals coexist without wrapper elements and add nothing
+ * to the DOM while they draw nothing.
+ *
+ * Scope creation is deferred a microtask so that an app drawing into `<body>`
+ * at module top level gets its content *before* the portals, keeping overlays
+ * at the end of the document.
  */
 export function mountPortal(draw) {
-    const container = document.createElement("div");
-    container.style.display = "contents";
-    document.body.appendChild(container);
-    A.mount(container, draw);
+    queueMicrotask(() => A(draw));
 }

package/dist/index.d.ts

@@ -38,7 +38,7 @@ export { buttonGroup, type ButtonGroupOptions } from "./components/buttonGroup.j
 export { checkbox, type CheckboxOptions } from "./components/checkbox.js";
 export { form, type FormOptions } from "./components/form.js";
 export { main, type MainOptions } from "./components/main.js";
-export { menuButton, showFloatingMenu, type MenuOptions, type MenuEntry, type MenuItem, type MenuSeparator, type FloatingMenuOptions } from "./components/menu.js";
+export { menuButton, showFloatingMenu, addContextMenu, type MenuOptions, type MenuEntry, type MenuItem, type MenuSeparator, type FloatingMenuOptions, type ContextMenuOptions } from "./components/menu.js";
 export { dialog, alert, confirm, prompt, type DialogOptions } from "./components/dialog.js";
 export { select, type SelectOptions, type SelectOptionInput } from "./components/select.js";
 export { tabs, type Tab, type TabsOptions } from "./components/tabs.js";

package/dist/index.js

@@ -41,7 +41,7 @@ export { buttonGroup } from "./components/buttonGroup.js";
 export { checkbox } from "./components/checkbox.js";
 export { form } from "./components/form.js";
 export { main } from "./components/main.js";
-export { menuButton, showFloatingMenu } from "./components/menu.js";
+export { menuButton, showFloatingMenu, addContextMenu } from "./components/menu.js";
 export { dialog, alert, confirm, prompt } from "./components/dialog.js";
 export { select } from "./components/select.js";
 export { tabs } from "./components/tabs.js";