@lumiose/ui 0.1.1 → 0.1.3

package/README.md

@@ -5,8 +5,8 @@ elements first (`<dialog>`, popover, invoker commands, CSS anchor positioning),
 elements (`lu-*`) only where the platform falls short, server-rendered without hydration. Parts
 follow [Base UI](https://base-ui.com)'s anatomy; the approach is [Timeless](https://timeless.build)'s.
 
-**In development**: not on npm yet. It keeps its own 0.x versions, apart from the version the other
-Lumiose packages share.
+**In development**, on npm: `pnpm add @lumiose/ui` in a Lumiose app (`lumiose` is its peer
+dependency). It keeps its own 0.x versions, apart from the version the other Lumiose packages share.
 
 ```tsx
 import { Dialog } from "@lumiose/ui";

package/dist/accordion/accordion.tsx

@@ -17,6 +17,8 @@ import {
 } from "lumiose";
 import defineAccordion from "./accordion.script.ts?client";
 import type { LuAccordion } from "./accordion.script.ts";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 declare module "lumiose/jsx-runtime" {
   namespace JSX {
@@ -118,13 +120,13 @@ const HeaderContext = createContext<AccordionHeaderProps>();
 
 function useAccordion(): AccordionContextValue {
   const context = useContext(AccordionContext);
-  if (!context) throw new Error("Accordion parts must be inside <Accordion.Root>.");
+  if (!context) throw notInside("Accordion parts", "<Accordion.Root>");
   return context;
 }
 
 function useItem(): ItemContextValue {
   const context = useContext(ItemContext);
-  if (!context) throw new Error("Accordion parts must be inside an <Accordion.Item>.");
+  if (!context) throw notInside("Accordion parts", "an <Accordion.Item>");
   return context;
 }
 
@@ -223,13 +225,13 @@ function Item({
         }}
         name={accordion.multiple ? undefined : accordion.id}
         open={shown}
-        on:toggle={(event: ToggleEvent) => {
+        on:toggle={batched((event: ToggleEvent) => {
           const now = event.newState === "open";
           accordion.onToggle(key, now);
           if (now === shown) return;
           shown = now;
           onOpenChange?.(now);
-        }}
+        })}
       >
         {children}
       </details>

package/dist/autocomplete/autocomplete.tsx

@@ -24,6 +24,7 @@ import comboboxScript from "../combobox/combobox.script.ts?client";
 import { ComboboxContext, type ComboboxContextValue } from "../combobox/context.ts";
 import { controlId, useField, useFormValues } from "../field/context.ts";
 import { onFormReset } from "../form/reset.ts";
+import { batched } from "../batched.ts";
 
 /**
  * How the suggestions complete the text, as in Base UI: `"list"` filters them by the text,
@@ -193,13 +194,13 @@ function Root({
         submit-on-item-click={submitOnItemClick}
         limit={limit}
         disabled={context.disabled()}
-        on:input={(event: Event) => {
+        on:input={batched((event: Event) => {
           const input = host()?.input;
           if (input && event.target === input) onValueChange?.(input.value);
-        }}
-        on:openchange={(event: CustomEvent<ComboboxOpenChangeDetail>) =>
-          onOpenChange?.(event.detail.open)
-        }
+        })}
+        on:openchange={batched((event: CustomEvent<ComboboxOpenChangeDetail>) =>
+          onOpenChange?.(event.detail.open),
+        )}
       >
         {children}
       </lu-combobox>

package/dist/avatar/avatar.tsx

@@ -12,6 +12,7 @@ import type {
   AvatarLoadingStatus,
   AvatarLoadingStatusChangeDetail,
 } from "./avatar.script.ts";
+import { batched } from "../batched.ts";
 
 export type { AvatarLoadingStatus } from "./avatar.script.ts";
 
@@ -75,9 +76,9 @@ function Image({ onLoadingStatusChange, ...rest }: AvatarImageProps) {
       {...rest}
       ref={image}
       data-loading
-      on:loadingstatuschange={(event: CustomEvent<AvatarLoadingStatusChangeDetail>) =>
-        report(event.detail.status)
-      }
+      on:loadingstatuschange={batched((event: CustomEvent<AvatarLoadingStatusChangeDetail>) =>
+        report(event.detail.status),
+      )}
     />
   );
 }

package/dist/batched.ts

@@ -0,0 +1,11 @@
+// The components' native listeners (`on:`) run inside `batch()`, as Lumiose's delegated event
+// handlers do (TASK-540): the signal writes of a listener and of the callbacks it calls
+// (`onValueChange`, `onOpenChange`, …) render together, before the event's dispatch returns, so
+// the DOM is current right after it instead of a microtask later.
+import { batch } from "lumiose";
+
+/** `listener`, run inside `batch()`. */
+export const batched =
+  <E>(listener: (event: E) => void) =>
+  (event: E): void =>
+    batch(() => listener(event));

package/dist/checkbox/checkbox.tsx

@@ -9,6 +9,7 @@ import { fieldProps, useField, useFormValues } from "../field/context.ts";
 import checkboxScript from "./checkbox.script.ts?client";
 import { CheckboxGroupContext, optionId, type CheckboxGroupContextValue } from "./context.ts";
 import { afterFormReset, onFormReset } from "../form/reset.ts";
+import { batched } from "../batched.ts";
 
 /**
  * The native checkbox props Root passes through (`name`, `required`, `disabled`, `form`, `id`,
@@ -137,9 +138,9 @@ function Root({
       data-parent={parent ? "" : undefined}
       aria-readonly={readOnly ? "true" : undefined}
       data-unchecked-value={uncheckedValue}
-      on:change={(event: Event) =>
-        onCheckedChange?.((event.currentTarget as HTMLInputElement).checked)
-      }
+      on:change={batched((event: Event) =>
+        onCheckedChange?.((event.currentTarget as HTMLInputElement).checked),
+      )}
     />
   );
 }

package/dist/checkbox-group/checkbox-group.tsx

@@ -7,6 +7,7 @@ import checkboxScript from "../checkbox/checkbox.script.ts?client";
 import { CheckboxGroupContext } from "../checkbox/context.ts";
 import { describedBy, labelledBy, useField, useFormValues } from "../field/context.ts";
 import { onFormReset } from "../form/reset.ts";
+import { batched } from "../batched.ts";
 
 /** The fieldset props CheckboxGroup passes through, without the brand of intrinsic elements' props. */
 type FieldsetProps = Omit<JSX.IntrinsicElements["fieldset"], symbol>;
@@ -98,11 +99,11 @@ export function CheckboxGroup({
         }
         aria-describedby={rest["aria-describedby"] ?? (field ? describedBy(field) : undefined)}
         aria-invalid={rest["aria-invalid"] ?? (field?.invalid() ? "true" : undefined)}
-        on:change={(event: Event) => {
+        on:change={batched((event: Event) => {
           if (!(event.target as Element).matches("input[type=checkbox]")) return;
           // checkbox.script.ts ran first, for a parent's toggle.
           report(checked(event.currentTarget as HTMLFieldSetElement));
-        }}
+        })}
       >
         {children}
       </fieldset>

package/dist/collapsible/collapsible.tsx

@@ -6,6 +6,8 @@
 // trigger. Ported from Timeless's approach (https://timeless.build).
 import { createContext, effect, ref, untrack, useContext, useId } from "lumiose";
 import collapsibleScript from "./collapsible.script.ts?client";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 /**
  * The `<details>` props Root passes on (`class`, `style`, `name`, `data-*`, `aria-*`, events),
@@ -53,7 +55,7 @@ const CollapsibleContext = createContext<CollapsibleContextValue>();
 
 function useCollapsible(): CollapsibleContextValue {
   const context = useContext(CollapsibleContext);
-  if (!context) throw new Error("Collapsible parts must be inside <Collapsible.Root>.");
+  if (!context) throw notInside("Collapsible parts", "<Collapsible.Root>");
   return context;
 }
 
@@ -96,12 +98,12 @@ function Root({
           forwarded?.(element);
         }}
         open={shown}
-        on:toggle={(event: ToggleEvent) => {
+        on:toggle={batched((event: ToggleEvent) => {
           const now = event.newState === "open";
           if (now === shown) return;
           shown = now;
           onOpenChange?.(now);
-        }}
+        })}
       >
         {children}
       </details>

package/dist/collapsible/panel.ts

@@ -34,7 +34,9 @@ function panelOf(details: HTMLDetailsElement): HTMLElement | undefined {
 
 /** The variables' prefix: an accordion item is a `<details>` right inside `<lu-accordion>`. */
 const prefix = (details: HTMLDetailsElement) =>
-  details.parentElement?.localName === "lu-accordion" ? "--lu-accordion-panel" : "--lu-collapsible-panel";
+  details.parentElement?.localName === "lu-accordion"
+    ? "--lu-accordion-panel"
+    : "--lu-collapsible-panel";
 
 function measure(panel: HTMLElement, name: string) {
   panel.style.setProperty(`${name}-height`, `${panel.scrollHeight}px`);

package/dist/combobox/combobox.tsx

@@ -27,6 +27,8 @@ import { controlId, describedBy, labelledBy, useField, useFormValues } from "../
 import { onFormReset } from "../form/reset.ts";
 import { anchorName, placement, withStyle, type PlacementProps } from "../placement/placement.ts";
 import { ComboboxContext, register, useCombobox, type ComboboxContextValue } from "./context.ts";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 declare module "lumiose/jsx-runtime" {
   namespace JSX {
@@ -266,14 +268,14 @@ function Root<Multiple extends boolean | undefined = false>({
         disabled={context.disabled()}
         multiple={multiple}
         filter={filter}
-        on:change={() => {
+        on:change={batched(() => {
           const next = host()!.value;
           selected.set(list(next));
           onValueChange?.(next as ComboboxValue<Multiple>);
-        }}
-        on:openchange={(event: CustomEvent<ComboboxOpenChangeDetail>) =>
-          onOpenChange?.(event.detail.open)
-        }
+        })}
+        on:openchange={batched((event: CustomEvent<ComboboxOpenChangeDetail>) =>
+          onOpenChange?.(event.detail.open),
+        )}
       >
         {children}
       </lu-combobox>
@@ -488,7 +490,7 @@ function GroupElement({
 
 function GroupLabel({ children, ...rest }: ComboboxGroupLabelProps) {
   const group = useContext(GroupContext);
-  if (!group) throw new Error("Combobox.GroupLabel must be inside <Combobox.Group>.");
+  if (!group) throw notInside("Combobox.GroupLabel", "<Combobox.Group>");
   register(group.labels);
   return (
     <div role="presentation" {...rest} id={group.labelId}>

package/dist/combobox/context.ts

@@ -1,6 +1,7 @@
 // The context the Combobox parts share, with Autocomplete's Root (TASK-377): the same parts work
 // under either Root, which says how the input behaves.
 import { createContext, onCleanup, useContext, type Signal } from "lumiose";
+import { notInside } from "../not-inside.ts";
 
 export interface ComboboxContextValue {
   /** The element's id; the parts' ids and the anchor name derive from it. */
@@ -35,7 +36,7 @@ export const ComboboxContext = createContext<ComboboxContextValue>();
 
 export function useCombobox(): ComboboxContextValue {
   const context = useContext(ComboboxContext);
-  if (!context) throw new Error("Combobox parts must be inside <Combobox.Root>.");
+  if (!context) throw notInside("Combobox parts", "<Combobox.Root>");
   return context;
 }
 

package/dist/context-menu/context-menu.tsx

@@ -19,6 +19,8 @@ import type { MenuElement, MenuOpenChangeDetail } from "../menu/menu.script.ts";
 import { anchorName } from "../placement/placement.ts";
 import contextMenuScript from "./context-menu.script.ts?client";
 import type { ContextMenuElement } from "./context-menu.script.ts";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 declare module "lumiose/jsx-runtime" {
   namespace JSX {
@@ -71,7 +73,7 @@ const ContextMenuContext = createContext<ContextMenuContextValue>();
 
 function useContextMenu(): ContextMenuContextValue {
   const context = useContext(ContextMenuContext);
-  if (!context) throw new Error("ContextMenu parts must be inside <ContextMenu.Root>.");
+  if (!context) throw notInside("ContextMenu parts", "<ContextMenu.Root>");
   return context;
 }
 
@@ -126,9 +128,9 @@ function Popup(props: ContextMenuPopupProps) {
   return (
     <lu-menu
       ref={context.host}
-      on:openchange={(event: CustomEvent<MenuOpenChangeDetail>) =>
-        context.onOpenChange(event.detail.open)
-      }
+      on:openchange={batched((event: CustomEvent<MenuOpenChangeDetail>) =>
+        context.onOpenChange(event.detail.open),
+      )}
     >
       {/* The point the popup is anchored to: the script moves it to the pointer. */}
       <span

package/dist/dialog/dialog.tsx

@@ -16,6 +16,8 @@ import {
   type Signal,
 } from "lumiose";
 import dialogScript from "./dialog.script.ts?client";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 /**
  * `Dialog.Root` renders no element: it holds the dialog's state and the ids its parts share.
@@ -68,7 +70,7 @@ const DialogContext = createContext<DialogContextValue>();
 
 function useDialog(): DialogContextValue {
   const context = useContext(DialogContext);
-  if (!context) throw new Error("Dialog parts must be inside <Dialog.Root>.");
+  if (!context) throw notInside("Dialog parts", "<Dialog.Root>");
   return context;
 }
 
@@ -148,7 +150,7 @@ function Popup({ children, ref: forwarded, ...rest }: DialogPopupProps) {
         forwarded?.(element);
       }}
       id={dialog.popupId}
-      on:toggle={(event: ToggleEvent) => dialog.onToggle(event.newState === "open")}
+      on:toggle={batched((event: ToggleEvent) => dialog.onToggle(event.newState === "open"))}
     >
       {isServer ? content : children}
     </dialog>

package/dist/drawer/drawer.tsx

@@ -13,6 +13,7 @@ import {
   type DialogTriggerProps,
 } from "../dialog/dialog.tsx";
 import drawerScript from "./drawer.script.ts?client";
+import { notInside } from "../not-inside.ts";
 
 /** The direction a swipe closes the drawer in, and the edge of the window it sits against. */
 export type DrawerSwipeDirection = "up" | "down" | "left" | "right";
@@ -68,7 +69,7 @@ function Root(props: DrawerRootProps) {
 
 function Popup({ children, ...rest }: DrawerPopupProps) {
   const drawer = useContext(DrawerContext);
-  if (!drawer) throw new Error("Drawer parts must be inside <Drawer.Root>.");
+  if (!drawer) throw notInside("Drawer parts", "<Drawer.Root>");
   return (
     <Dialog.Popup {...rest} data-swipe-direction={drawer.direction()}>
       {children}

package/dist/field/field.tsx

@@ -31,6 +31,8 @@ import {
 import fieldScript from "./field.script.ts?client";
 import { listenToForm, reportValidity } from "../form/native.ts";
 import { Input, type InputProps } from "../input/input.tsx";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 declare module "lumiose/jsx-runtime" {
   namespace JSX {
@@ -288,7 +290,7 @@ function Root({
    * (cleared while it waits): its check runs now, and a synchronous one that fails stops the
    * submission, which the form then reports. An async check still waits for the server.
    */
-  const onSubmit = (event: Event) => {
+  const onSubmit = batched((event: Event) => {
     if (!due) return;
     clearTimeout(timer);
     due();
@@ -297,7 +299,7 @@ function Root({
     event.preventDefault();
     event.stopImmediatePropagation();
     reportValidity(event.currentTarget as HTMLFormElement);
-  };
+  });
   effect(() => {
     if (!validate) return;
     const element = document.getElementById(controlId(field));
@@ -314,13 +316,13 @@ function Root({
     }
   });
   // A submit attempt checks every control (`invalid` does not bubble); a reset clears the checks.
-  const onInvalid = (event: Event) => snapshot(event.target);
-  const onReset = () => {
+  const onInvalid = batched((event: Event) => snapshot(event.target));
+  const onReset = batched(() => {
     checked.set(undefined);
     checking = undefined;
     // The controls take their default values after the event.
     setTimeout(() => run(document.getElementById(controlId(field)), 0, true));
-  };
+  });
   onMount(() => {
     const element = host();
     if (!element) return;
@@ -349,15 +351,15 @@ function Root({
         }}
         id={id}
         validation-mode={validationMode ?? form?.validationMode()}
-        on:input={(event: Event) => {
+        on:input={batched((event: Event) => {
           run(event.target, validationDebounceTime);
           snapshot(event.target);
-        }}
-        on:change={(event: Event) => {
+        })}
+        on:change={batched((event: Event) => {
           run(event.target);
           snapshot(event.target);
-        }}
-        on:focusout={(event: Event) => snapshot(event.target)}
+        })}
+        on:focusout={batched((event: Event) => snapshot(event.target))}
       >
         {children}
       </lu-field>
@@ -372,7 +374,7 @@ function Validity({ children }: FieldValidityProps) {
 
 function useFieldPart(part: string): FieldContextValue {
   const field = useContext(FieldContext);
-  if (!field) throw new Error(`Field.${part} must be inside <Field.Root>.`);
+  if (!field) throw notInside(`Field.${part}`, "<Field.Root>");
   return field;
 }
 

package/dist/form/reset.ts

@@ -4,7 +4,7 @@
 // value when its form resets and again a task later, once the controls (and the elements'
 // scripts, which follow the reset the same way) hold their defaults, and reports the new value
 // when it differs.
-import { onCleanup, onMount } from "lumiose";
+import { batch, onCleanup, onMount } from "lumiose";
 import { listenToForm } from "./native.ts";
 
 const same = (a: unknown, b: unknown) =>
@@ -20,10 +20,12 @@ function listen(element: () => Element | undefined, atReset: () => () => void):
       (host as { form?: HTMLFormElement | null } | undefined)?.form ?? host?.closest("form");
     if (!form) return;
     let timer: ReturnType<typeof setTimeout> | undefined;
+    // In `batch()`, as the components' listeners (../batched.ts): the callbacks' writes render
+    // together.
     const listener = () => {
       const later = atReset();
       clearTimeout(timer);
-      timer = setTimeout(later);
+      timer = setTimeout(() => batch(later));
     };
     const stop = listenToForm(form, "reset", listener);
     onCleanup(() => {

package/dist/input/input.tsx

@@ -4,6 +4,7 @@
 import { ref, untrack } from "lumiose";
 import { fieldProps, useField, useFormValues } from "../field/context.ts";
 import { onFormReset } from "../form/reset.ts";
+import { batched } from "../batched.ts";
 
 /**
  * An element's props without the brand of intrinsic elements' props, so that the component's
@@ -61,7 +62,9 @@ export function Input({ value, defaultValue, onValueChange, ...rest }: InputProp
         rest.ref?.(element);
       }}
       value={value !== undefined ? value : untrack(() => sent?.[0] ?? defaultValue)}
-      on:input={(event: Event) => onValueChange?.((event.currentTarget as HTMLInputElement).value)}
+      on:input={batched((event: Event) =>
+        onValueChange?.((event.currentTarget as HTMLInputElement).value),
+      )}
     />
   );
 }

package/dist/menu/menu.tsx

@@ -21,6 +21,8 @@ import type { MenuCheckedChangeDetail, MenuElement, MenuOpenChangeDetail } from
 import menuScript from "./menu.script.ts?client";
 import { anchorName, placement, withStyle, type Align, type Side } from "../placement/placement.ts";
 import { OUTSIDE_TOOLBAR, ToolbarContext } from "../toolbar/context.ts";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 declare module "lumiose/jsx-runtime" {
   namespace JSX {
@@ -189,7 +191,7 @@ const RadioContext = createContext<{ value: () => string | undefined }>();
 
 function useMenu(): MenuContextValue {
   const context = useContext(MenuContext);
-  if (!context) throw new Error("Menu parts must be inside <Menu.Root>.");
+  if (!context) throw notInside("Menu parts", "<Menu.Root>");
   return context;
 }
 
@@ -244,9 +246,9 @@ function menuRoot(props: MenuRootProps, submenu: boolean) {
       <lu-menu
         ref={host}
         role={context.menubar ? "none" : undefined}
-        on:openchange={(event: CustomEvent<MenuOpenChangeDetail>) =>
-          props.onOpenChange?.(event.detail.open)
-        }
+        on:openchange={batched((event: CustomEvent<MenuOpenChangeDetail>) =>
+          props.onOpenChange?.(event.detail.open),
+        )}
       >
         {props.children}
       </lu-menu>
@@ -377,9 +379,9 @@ function CheckboxItem({
       {...rest}
       role="menuitemcheckbox"
       aria-checked={checked ?? defaultChecked ?? false}
-      on:checkedchange={(event: CustomEvent<MenuCheckedChangeDetail>) =>
-        onCheckedChange?.(event.detail.checked)
-      }
+      on:checkedchange={batched((event: CustomEvent<MenuCheckedChangeDetail>) =>
+        onCheckedChange?.(event.detail.checked),
+      )}
     >
       {children}
     </button>
@@ -416,7 +418,7 @@ function Group(props: MenuGroupProps) {
 
 function GroupLabel({ children, ...rest }: MenuGroupLabelProps) {
   const group = useContext(GroupContext);
-  if (!group) throw new Error("Menu.GroupLabel must be inside <Menu.Group> or <Menu.RadioGroup>.");
+  if (!group) throw notInside("Menu.GroupLabel", "<Menu.Group> or <Menu.RadioGroup>");
   register(group.labels);
   return (
     <div role="presentation" {...rest} id={group.labelId}>
@@ -442,12 +444,12 @@ function RadioGroup({
         <GroupElement
           {...rest}
           group={group}
-          on:checkedchange={(event: CustomEvent<MenuCheckedChangeDetail>) => {
+          on:checkedchange={batched((event: CustomEvent<MenuCheckedChangeDetail>) => {
             const item = event.target as HTMLButtonElement;
             if (item.getAttribute("role") === "menuitemradio" && event.detail.checked) {
               onValueChange?.(item.value);
             }
-          }}
+          })}
         >
           {children}
         </GroupElement>
@@ -466,7 +468,7 @@ function RadioItem({
 }: MenuRadioItemProps) {
   useMenu();
   const radio = useContext(RadioContext);
-  if (!radio) throw new Error("Menu.RadioItem must be inside <Menu.RadioGroup>.");
+  if (!radio) throw notInside("Menu.RadioItem", "<Menu.RadioGroup>");
   return (
     <button
       type="button"

package/dist/meter/meter.tsx

@@ -6,6 +6,7 @@
 import { createContext, useContext, useId } from "lumiose";
 import { withStyle } from "../placement/placement.ts";
 import { formatValue, percent } from "../progress/value.ts";
+import { notInside } from "../not-inside.ts";
 
 interface MeterContextValue {
   id: string;
@@ -52,7 +53,7 @@ export type MeterValueProps = Omit<JSX.IntrinsicElements["span"], "children"> &
 
 function useMeter(part: string): MeterContextValue {
   const context = useContext(MeterContext);
-  if (!context) throw new Error(`Meter.${part} must be inside <Meter.Root>.`);
+  if (!context) throw notInside(`Meter.${part}`, "<Meter.Root>");
   return context;
 }
 

package/dist/navigation-menu/navigation-menu.tsx

@@ -15,6 +15,8 @@ import type {
   NavigationMenuElement,
   NavigationMenuValueChangeDetail,
 } from "./navigation-menu.script.ts";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 declare module "lumiose/jsx-runtime" {
   namespace JSX {
@@ -99,7 +101,7 @@ const ItemContext = createContext<ItemContextValue>();
 
 function useItem(part: string): ItemContextValue {
   const item = useContext(ItemContext);
-  if (!item) throw new Error(`NavigationMenu.${part} must be inside <NavigationMenu.Item>.`);
+  if (!item) throw notInside(`NavigationMenu.${part}`, "<NavigationMenu.Item>");
   return item;
 }
 
@@ -150,9 +152,9 @@ function Root({
         data-delay={delay}
         data-close-delay={closeDelay}
         data-orientation={vertical() ? "vertical" : "horizontal"}
-        on:valuechange={(event: CustomEvent<NavigationMenuValueChangeDetail>) =>
-          onValueChange?.(event.detail.value)
-        }
+        on:valuechange={batched((event: CustomEvent<NavigationMenuValueChangeDetail>) =>
+          onValueChange?.(event.detail.value),
+        )}
       >
         {/* A nested menu is a `<div>`, inside its parent's landmark. */}
         <Dynamic component={nested ? "div" : "nav"} {...attributes()}>

package/dist/not-inside.ts

@@ -0,0 +1,13 @@
+// The error a compound component's part throws when the Root (or another part) it needs is not
+// above it. The case that is hard to see is an island in between (TASK-550): a part passed to an
+// island as a slot renders in the page, where the Root the island renders around the slot is not.
+
+/** `subject must be inside container.`, with the island hint. */
+export function notInside(subject: string, container: string): Error {
+  return new Error(
+    `${subject} must be inside ${container}. If this part looks inside, check for an island in between: ` +
+      "a part passed to an island as a slot (children or a JSX prop) renders in the page, not inside " +
+      "the components the island renders around it. Pass the data as props and render the parts " +
+      "inside the island.",
+  );
+}

package/dist/number-field/number-field.tsx

@@ -24,6 +24,8 @@ import { onFormReset } from "../form/reset.ts";
 import { formatNumber, formatter } from "./format.ts";
 import type { NumberFieldElement } from "./number-field.script.ts";
 import numberFieldScript from "./number-field.script.ts?client";
+import { batched } from "../batched.ts";
+import { notInside } from "../not-inside.ts";
 
 declare module "lumiose/jsx-runtime" {
   namespace JSX {
@@ -164,7 +166,7 @@ const NumberFieldContext = createContext<NumberFieldContextValue>();
 
 function useNumberField(part: string): NumberFieldContextValue {
   const context = useContext(NumberFieldContext);
-  if (!context) throw new Error(`NumberField.${part} must be inside <NumberField.Root>.`);
+  if (!context) throw notInside(`NumberField.${part}`, "<NumberField.Root>");
   return context;
 }
 
@@ -260,11 +262,11 @@ function Root({
         locale={locale}
         allow-wheel-scrub={allowWheelScrub}
         allow-out-of-range={allowOutOfRange}
-        on:input={report}
-        on:change={() => {
+        on:input={batched(report)}
+        on:change={batched(() => {
           report();
           onValueCommitted?.(element()?.value ?? null);
-        }}
+        })}
       >
         <input
           type="hidden"