npm - @gusnips/react - Versions diffs - 0.1.0 - Mend

@gusnips/react 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (138) hide show

package/LICENSE +21 -0
package/README.md +180 -0
package/dist/api-client.d.ts +139 -0
package/dist/api-client.d.ts.map +1 -0
package/dist/api-client.js +133 -0
package/dist/api-client.js.map +1 -0
package/dist/api-error.d.ts +45 -0
package/dist/api-error.d.ts.map +1 -0
package/dist/api-error.js +52 -0
package/dist/api-error.js.map +1 -0
package/dist/auth-store.d.ts +49 -0
package/dist/auth-store.d.ts.map +1 -0
package/dist/auth-store.js +27 -0
package/dist/auth-store.js.map +1 -0
package/dist/chunk-reload.d.ts +61 -0
package/dist/chunk-reload.d.ts.map +1 -0
package/dist/chunk-reload.js +92 -0
package/dist/chunk-reload.js.map +1 -0
package/dist/cn.d.ts +13 -0
package/dist/cn.d.ts.map +1 -0
package/dist/cn.js +16 -0
package/dist/cn.js.map +1 -0
package/dist/describe-error.d.ts +74 -0
package/dist/describe-error.d.ts.map +1 -0
package/dist/describe-error.js +70 -0
package/dist/describe-error.js.map +1 -0
package/dist/error-boundary.d.ts +61 -0
package/dist/error-boundary.d.ts.map +1 -0
package/dist/error-boundary.js +32 -0
package/dist/error-boundary.js.map +1 -0
package/dist/guards.d.ts +65 -0
package/dist/guards.d.ts.map +1 -0
package/dist/guards.js +52 -0
package/dist/guards.js.map +1 -0
package/dist/hydrate.d.ts +30 -0
package/dist/hydrate.d.ts.map +1 -0
package/dist/hydrate.js +25 -0
package/dist/hydrate.js.map +1 -0
package/dist/i18n.d.ts +70 -0
package/dist/i18n.d.ts.map +1 -0
package/dist/i18n.js +66 -0
package/dist/i18n.js.map +1 -0
package/dist/index.d.ts +12 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +31 -0
package/dist/index.js.map +1 -0
package/dist/prerender-contract.d.ts +30 -0
package/dist/prerender-contract.d.ts.map +1 -0
package/dist/prerender-contract.js +30 -0
package/dist/prerender-contract.js.map +1 -0
package/dist/query.d.ts +28 -0
package/dist/query.d.ts.map +1 -0
package/dist/query.js +51 -0
package/dist/query.js.map +1 -0
package/dist/sse.d.ts +64 -0
package/dist/sse.d.ts.map +1 -0
package/dist/sse.js +105 -0
package/dist/sse.js.map +1 -0
package/dist/states.d.ts +69 -0
package/dist/states.d.ts.map +1 -0
package/dist/states.js +2 -0
package/dist/states.js.map +1 -0
package/dist/ui/class-name.d.ts +16 -0
package/dist/ui/class-name.d.ts.map +1 -0
package/dist/ui/class-name.js +13 -0
package/dist/ui/class-name.js.map +1 -0
package/dist/ui/combobox.d.ts +81 -0
package/dist/ui/combobox.d.ts.map +1 -0
package/dist/ui/combobox.js +70 -0
package/dist/ui/combobox.js.map +1 -0
package/dist/ui/dialog.d.ts +39 -0
package/dist/ui/dialog.d.ts.map +1 -0
package/dist/ui/dialog.js +32 -0
package/dist/ui/dialog.js.map +1 -0
package/dist/ui/drawer.d.ts +63 -0
package/dist/ui/drawer.d.ts.map +1 -0
package/dist/ui/drawer.js +55 -0
package/dist/ui/drawer.js.map +1 -0
package/dist/ui/glyphs.d.ts +4 -0
package/dist/ui/glyphs.d.ts.map +1 -0
package/dist/ui/glyphs.js +20 -0
package/dist/ui/glyphs.js.map +1 -0
package/dist/ui/index.d.ts +9 -0
package/dist/ui/index.d.ts.map +1 -0
package/dist/ui/index.js +48 -0
package/dist/ui/index.js.map +1 -0
package/dist/ui/input.d.ts +45 -0
package/dist/ui/input.d.ts.map +1 -0
package/dist/ui/input.js +108 -0
package/dist/ui/input.js.map +1 -0
package/dist/ui/menu.d.ts +70 -0
package/dist/ui/menu.d.ts.map +1 -0
package/dist/ui/menu.js +85 -0
package/dist/ui/menu.js.map +1 -0
package/dist/ui/select.d.ts +69 -0
package/dist/ui/select.d.ts.map +1 -0
package/dist/ui/select.js +48 -0
package/dist/ui/select.js.map +1 -0
package/dist/ui/tabs.d.ts +52 -0
package/dist/ui/tabs.d.ts.map +1 -0
package/dist/ui/tabs.js +62 -0
package/dist/ui/tabs.js.map +1 -0
package/package.json +124 -0
package/src/api-client.test.ts +256 -0
package/src/api-client.ts +305 -0
package/src/api-error.ts +60 -0
package/src/auth-store.ts +59 -0
package/src/chunk-reload.test.ts +46 -0
package/src/chunk-reload.ts +94 -0
package/src/cn.ts +16 -0
package/src/describe-error.test.ts +102 -0
package/src/describe-error.ts +140 -0
package/src/error-boundary.tsx +88 -0
package/src/guards.tsx +99 -0
package/src/hydrate.ts +36 -0
package/src/i18n.test.ts +68 -0
package/src/i18n.ts +101 -0
package/src/index.ts +63 -0
package/src/prerender-contract.ts +31 -0
package/src/query.test.ts +54 -0
package/src/query.ts +79 -0
package/src/sse.test.ts +50 -0
package/src/sse.ts +117 -0
package/src/states.ts +71 -0
package/src/ui/class-name.ts +23 -0
package/src/ui/combobox.test.ts +32 -0
package/src/ui/combobox.tsx +242 -0
package/src/ui/dialog.tsx +87 -0
package/src/ui/drawer.tsx +161 -0
package/src/ui/focus.test.ts +82 -0
package/src/ui/glyphs.tsx +35 -0
package/src/ui/index.ts +145 -0
package/src/ui/input.test.ts +22 -0
package/src/ui/input.tsx +181 -0
package/src/ui/menu.test.ts +73 -0
package/src/ui/menu.tsx +186 -0
package/src/ui/select.tsx +191 -0
package/src/ui/tabs.tsx +95 -0

package/src/ui/index.ts ADDED Viewed

@@ -0,0 +1,145 @@
+// @gusnips/react/ui — the Base UI wrappers, behind a subpath so an app on a different
+// primitive library (or none) never resolves `@base-ui/react`.
+//
+// SEVEN, out of twenty-seven in the donor. The rest added a class string and nothing else:
+// Base UI already does scroll lock, focus trap, escape, outside-dismiss, focus return, roving
+// focus and typeahead, so a wrapper earns its place for one of three reasons only —
+// composition a caller cannot skip (a dialog with no scrim is unwritable), a required a11y
+// prop expressed as a TYPE (no close button without its label, no tab rail without a name),
+// or an encoded gotcha (the drawer's four, the menu's caption, the tab rail's padding).
+//
+// These are not styled components. The classes here are the ones that make the primitive
+// work — position, stacking, overflow, an opaque surface, the transition hooks Base UI
+// animates through. Padding, radius, shadow and type are the product's, and every part takes
+// a `className` that wins over ours.
+//
+// Nothing here draws a focus ring, and nothing removes one outside a popup container. The
+// app's single `:focus-visible` outline lives in `@gusnips/tokens`' base layer; a wrapper
+// that swaps it for a `ring-*` box-shadow looks identical in every normal browser and
+// vanishes under `forced-colors: active`. `focus.test.ts` pins that.
+//
+// The stacking contract, in one place, because the parts are all portalled to `<body>` and
+// nesting decides nothing:
+//   z-40  drawer backdrop
+//   z-50  the overlay layer — dialog, drawer. A tie on purpose: a dialog opened from inside
+//         a drawer must paint over it, and at a tie the later portal wins.
+//   z-60  popups anchored inside that layer — a select, combobox or menu opened in a dialog.
+//         Every one of the three takes `positionerProps={{ className: "z-…" }}` to move.
+export { mergeClassName, type StateClassName } from "./class-name.ts";
+export {
+  Dialog,
+  DialogBackdrop,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogPopup,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+  type DialogContentProps,
+} from "./dialog.tsx";
+export {
+  Drawer,
+  DrawerBackdrop,
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHandle,
+  DrawerPopup,
+  DrawerPortal,
+  DrawerRoot,
+  DrawerSwipeArea,
+  DrawerTitle,
+  DrawerTrigger,
+  DrawerViewport,
+  type DrawerProps,
+  type DrawerSide,
+} from "./drawer.tsx";
+// `SelectGroupLabel` and `ComboboxGroupLabel` below ARE exported, and the menu's is not. The
+// hazard is identical — all three read their group's context and throw when written outside
+// it, reported in production as `Base UI error #56` for select, `#18` for combobox and `#31`
+// for the menu — so the difference is a decision, not an oversight.
+//
+// It turns on what the wrapper already covers. `MenuGroup` composes the caption as a `label`
+// prop, so the raw part has no job left and withholding it is free. `Select` and `Combobox`
+// take a flat option list and cannot express a grouped one at all, so these are the escape
+// hatch for that shape — and a caller reaching for `SelectGroup` is writing its
+// `SelectGroupLabel` in the same breath, which is the arrangement that works.
+export {
+  Select,
+  SelectGroup,
+  SelectGroupLabel,
+  SelectIcon,
+  SelectItem,
+  SelectItemIndicator,
+  SelectItemText,
+  SelectList,
+  SelectPopup,
+  SelectPortal,
+  SelectPositioner,
+  SelectRoot,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+  type SelectOption,
+  type SelectProps,
+} from "./select.tsx";
+export {
+  Combobox,
+  comboboxInputValue,
+  ComboboxClear,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxGroupLabel,
+  ComboboxInput,
+  ComboboxInputGroup,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxPopup,
+  ComboboxPortal,
+  ComboboxPositioner,
+  ComboboxRoot,
+  ComboboxTrigger,
+  type ComboboxProps,
+} from "./combobox.tsx";
+export {
+  Input,
+  textareaHeight,
+  type FieldProps,
+  type InputProps,
+  type MultilineInputProps,
+} from "./input.tsx";
+// No `MenuGroupLabel`, and no raw `Group` / `RadioGroup`. That is the whole guarantee — see
+// the note at the top of menu.tsx.
+export {
+  Menu,
+  MenuArrow,
+  MenuBackdrop,
+  MenuCheckboxItem,
+  MenuCheckboxItemIndicator,
+  MenuContent,
+  MenuGroup,
+  MenuItem,
+  MenuLinkItem,
+  MenuPopup,
+  MenuPortal,
+  MenuPositioner,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuRadioItemIndicator,
+  MenuSeparator,
+  MenuSubmenuRoot,
+  MenuSubmenuTrigger,
+  MenuTrigger,
+  type MenuContentProps,
+  type MenuRadioItemProps,
+} from "./menu.tsx";
+export { Tab, TabIndicator, TabList, TabPanel, Tabs, type TabListProps } from "./tabs.tsx";

package/src/ui/input.test.ts ADDED Viewed

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { textareaHeight } from "./input.tsx";
+describe("textareaHeight", () => {
+  it("grows with the content", () => {
+    expect(textareaHeight(400, 72)).toBe("72px");
+  });
+  it("stops at the cap, so a long paste scrolls instead of taking the page", () => {
+    expect(textareaHeight(400, 900)).toBe("160px");
+  });
+  // A field squeezed to nothing wraps every word, so scrollHeight reads as tall as the cap
+  // and the box opens to full height for one line of text. Hand it back to CSS instead.
+  it("does not autosize a field too narrow to measure honestly", () => {
+    expect(textareaHeight(120, 900)).toBe("");
+  });
+  it("takes over again the moment the column is wide enough", () => {
+    expect(textareaHeight(180, 40)).toBe("40px");
+  });
+});

package/src/ui/input.tsx ADDED Viewed

@@ -0,0 +1,181 @@
+import { Input as Primitive } from "@base-ui/react/input";
+import * as React from "react";
+import { cn } from "../cn.ts";
+/** Below this width a textarea wraps almost every word, so `scrollHeight` jumps straight to
+ *  the cap and the field opens to full height for one word. Under it, let CSS decide. */
+const TEXTAREA_MIN_AUTO_WIDTH = 180;
+/** Past this the textarea stops growing and starts scrolling, so a long paste cannot push
+ *  the submit button off the screen. */
+const TEXTAREA_MAX_HEIGHT = 160;
+/**
+ * The inline height an autosizing textarea should carry, or `""` for "leave it to CSS".
+ *
+ * ponytail: this whole observer is here only until `field-sizing: content` is baseline —
+ * one CSS line does the same job. Ceiling: it does not exist in every browser we support yet.
+ */
+export function textareaHeight(clientWidth: number, scrollHeight: number): string {
+  if (clientWidth < TEXTAREA_MIN_AUTO_WIDTH) return "";
+  return `${Math.min(scrollHeight, TEXTAREA_MAX_HEIGHT)}px`;
+}
+type FieldChrome = {
+  label?: React.ReactNode;
+  /**
+   * The message under the field. Its presence is what wires `aria-invalid` and
+   * `aria-describedby`, so a field that looks wrong also announces that it is.
+   */
+  error?: React.ReactNode;
+  /**
+   * Classes for the control. A plain string here, not Base UI's state-callback form: this
+   * component renders a native `<textarea>` for the multiline case, which has no Base UI
+   * state to call back with, and one field type styling differently from the other would be
+   * a worse trade than the callback is worth.
+   */
+  className?: string;
+  wrapperClassName?: string;
+  labelClassName?: string;
+  errorClassName?: string;
+};
+export type InputProps = FieldChrome & Omit<Primitive.Props, "className"> & { multiline?: false };
+export type MultilineInputProps = FieldChrome &
+  Omit<React.ComponentProps<"textarea">, "className"> & { multiline: true };
+export type FieldProps = InputProps | MultilineInputProps;
+function withoutChrome<P extends FieldChrome & { multiline?: boolean }>(props: P) {
+  const {
+    label: _label,
+    error: _error,
+    className: _className,
+    wrapperClassName: _wrapperClassName,
+    labelClassName: _labelClassName,
+    errorClassName: _errorClassName,
+    multiline: _multiline,
+    ...rest
+  } = props;
+  return rest;
+}
+/**
+ * `border-input` rather than `border-border`: a control's boundary is a non-text contrast
+ * target and has to clear 3:1 (WCAG 1.4.11), which the hairline between two panels does not.
+ *
+ * `text-base` up to `md`: iOS Safari zooms the whole page in when a field it focuses has type
+ * smaller than 16px, and it does not zoom back out. The pair is the fix, not a size choice.
+ *
+ * No focus style here, deliberately. The app's one ring is the `:focus-visible` outline in
+ * `@gusnips/tokens`' base layer, and a control that swaps it for `outline-none` plus a
+ * `ring-*` gains nothing and loses forced-colors mode: a ring is a `box-shadow`, which the UA
+ * forces to `none` under Windows High Contrast, while an outline survives and takes a system
+ * colour. The swap therefore deletes the focus indicator for exactly the people who need it
+ * most — and it is invisible in review, because it looks correct in every normal browser.
+ */
+const controlClasses =
+  "w-full min-w-0 rounded-md border border-input bg-background px-3 py-2 text-base text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive md:text-sm";
+/**
+ * A field with its label, its error, and the aria that ties the three together.
+ *
+ * That wiring is the reason this exists: `htmlFor`/`id`, `aria-describedby` pointing at the
+ * error, `aria-invalid` set from the same prop that draws the red border, and an id generated
+ * when the caller has not given one. Every one of those is a line somebody forgets, and
+ * forgetting it is invisible until a screen reader reads the field with no name and no reason.
+ */
+export function Input(props: FieldProps) {
+  const { label, error, className, wrapperClassName, labelClassName, errorClassName } = props;
+  const generatedId = React.useId();
+  const fieldId = props.id ?? (label || error ? generatedId : undefined);
+  const errorId = error ? `${fieldId ?? generatedId}-error` : undefined;
+  // Appended, never replaced: a caller describing the field with a hint of their own keeps it.
+  const describedBy = errorId
+    ? [props["aria-describedby"], errorId].filter(Boolean).join(" ")
+    : props["aria-describedby"];
+  const shared = {
+    id: fieldId,
+    "aria-invalid": error ? true : props["aria-invalid"],
+    "aria-describedby": describedBy,
+    className: cn(controlClasses, props.multiline && "resize-none", className),
+  };
+  return (
+    <div className={cn("w-full", wrapperClassName)}>
+      {label ? (
+        <label htmlFor={fieldId} className={cn("mb-1.5 block text-sm", labelClassName)}>
+          {label}
+        </label>
+      ) : null}
+      {props.multiline ? (
+        <AutosizeTextarea {...withoutChrome(props)} {...shared} />
+      ) : (
+        <Primitive {...withoutChrome(props)} {...shared} />
+      )}
+      {error ? (
+        <div
+          id={errorId}
+          role="alert"
+          className={cn("mt-1.5 text-xs text-destructive", errorClassName)}
+        >
+          {error}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+/**
+ * A textarea that grows with its content and then scrolls.
+ *
+ * It watches its own SIZE, not just its value: a textarea also reflows when the column it
+ * sits in changes width — a drawer opening, a sidebar collapsing, a phone turning — and
+ * height set from the old width is either a gap under the text or a scrollbar over two lines.
+ */
+function AutosizeTextarea({ ref, onInput, ...rest }: React.ComponentProps<"textarea">) {
+  const element = React.useRef<HTMLTextAreaElement | null>(null);
+  const setElement = React.useCallback(
+    (node: HTMLTextAreaElement | null) => {
+      element.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref],
+  );
+  const fit = React.useCallback(() => {
+    const node = element.current;
+    if (!node) return;
+    // Reset first. `scrollHeight` is the content height OR the box height, whichever is
+    // larger, so a box already held open at yesterday's height never reports a smaller one —
+    // the field would grow and never shrink.
+    node.style.height = "auto";
+    node.style.height = textareaHeight(node.clientWidth, node.scrollHeight);
+  }, []);
+  React.useEffect(() => {
+    fit();
+  }, [fit, rest.value, rest.placeholder]);
+  React.useEffect(() => {
+    const node = element.current;
+    if (!node || typeof ResizeObserver === "undefined") return undefined;
+    const observer = new ResizeObserver(fit);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [fit]);
+  return (
+    <textarea
+      {...rest}
+      ref={setElement}
+      onInput={(event) => {
+        fit();
+        onInput?.(event);
+      }}
+    />
+  );
+}

package/src/ui/menu.test.ts ADDED Viewed

@@ -0,0 +1,73 @@
+/**
+ * The group-caption rule, which only a structure can keep.
+ *
+ * `GroupLabel` reads its group's context in all three components that have one, so a caption
+ * written as a SIBLING of the group throws at render. A production build reports that as
+ * `Base UI error #31` for the menu, `#56` for select and `#18` for combobox, plus a link — a
+ * number to go look up, naming neither the file, nor the part, nor the component. Documenting
+ * that would not have stopped it. Two things do, and both are checked here.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+// `fileURLToPath`, never `import.meta.dir` — invariant 11.
+const here = dirname(fileURLToPath(import.meta.url));
+/**
+ * Comments out, code in. A guard that reads its own explanation as a violation is a guard that
+ * teaches people to delete the explanation — and this rule is worth a paragraph that has to be
+ * free to name the part it forbids.
+ */
+function codeOf(name: string): string {
+  return readFileSync(join(here, name), "utf8")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+const count = (text: string, pattern: RegExp) => text.match(pattern)?.length ?? 0;
+/** Every `<Primitive.Group>…</Primitive.Group>` body in a file, for one group kind. */
+function bodiesOf(code: string, part: string): string[] {
+  const tag = `<Primitive\\.${part}\\b[^>]*>[\\s\\S]*?</Primitive\\.${part}>`;
+  return code.match(new RegExp(tag, "g")) ?? [];
+}
+function misplacedCaptions(code: string): number {
+  const inside = ["Group", "RadioGroup"]
+    .flatMap((part) => bodiesOf(code, part))
+    .reduce((total, body) => total + count(body, /<Primitive\.GroupLabel\b/g), 0);
+  return count(code, /<Primitive\.GroupLabel\b/g) - inside;
+}
+const sources = readdirSync(here)
+  .filter((name) => name.endsWith(".tsx"))
+  .map((name) => ({ name, code: codeOf(name) }));
+describe("a group caption cannot be placed outside its group", () => {
+  // Folder-wide rather than menu-only: today `menu.tsx` is the one file that renders a
+  // caption, but `Select` and `Combobox` both have the part and would grow one the day either
+  // wrapper learns grouped options. That is exactly where this bug lands next.
+  it.each(sources)("$name keeps every GroupLabel inside a Group", ({ code }) => {
+    expect(misplacedCaptions(code)).toBe(0);
+  });
+  it("has a caption somewhere to check, so the rule above is not vacuous", () => {
+    const captions = sources.reduce(
+      (total, { code }) => total + count(code, /<Primitive\.GroupLabel\b/g),
+      0,
+    );
+    expect(captions).toBeGreaterThan(0);
+  });
+  it("never exports the menu's GroupLabel, Group or RadioGroup as raw parts", () => {
+    // Menu only, on purpose. `MenuGroup` composes the caption as a prop, so the raw parts have
+    // no job left and withholding them is free. Select and Combobox export theirs as the
+    // escape hatch for grouped options, a shape those wrappers do not express — see the note
+    // beside them in index.ts. Widening this assertion would forbid that on purpose.
+    const surface = codeOf("menu.tsx") + codeOf("index.ts");
+    expect(surface).not.toMatch(/=\s*Primitive\.(?:GroupLabel|Group|RadioGroup)\s*;/);
+    expect(surface).not.toMatch(/\bMenuGroupLabel\b/);
+  });
+});

package/src/ui/menu.tsx ADDED Viewed

@@ -0,0 +1,186 @@
+import { Menu as Primitive } from "@base-ui/react/menu";
+import type { ReactNode } from "react";
+import { mergeClassName } from "./class-name.ts";
+import { CheckGlyph } from "./glyphs.tsx";
+// The parts — every one of them EXCEPT `GroupLabel`, and every one except `Group` and
+// `RadioGroup`, which are wrapped below. That omission is not tidying: it is the only thing
+// that actually prevents the bug. `Menu.GroupLabel` reads its group's context, so a caption
+// written as a SIBLING of the group throws at render, and a production build reports that as
+// `Base UI error #31` plus a link — a number to go look up, naming neither the file, nor the
+// part, nor the component it came from. A comment cannot stop that; not shipping the part
+// can. The caption is a prop on the group instead, so the wrong arrangement has nowhere to be
+// written. `Select.GroupLabel` and `Combobox.GroupLabel` throw the same way (#56 and #18) and
+// ARE exported — see the note beside them in index.ts for why that is the right call there.
+export const Menu = Primitive.Root;
+export const MenuTrigger = Primitive.Trigger;
+export const MenuPortal = Primitive.Portal;
+export const MenuPositioner = Primitive.Positioner;
+export const MenuPopup = Primitive.Popup;
+export const MenuBackdrop = Primitive.Backdrop;
+export const MenuArrow = Primitive.Arrow;
+export const MenuLinkItem = Primitive.LinkItem;
+export const MenuCheckboxItem = Primitive.CheckboxItem;
+export const MenuCheckboxItemIndicator = Primitive.CheckboxItemIndicator;
+export const MenuRadioItemIndicator = Primitive.RadioItemIndicator;
+export const MenuSubmenuRoot = Primitive.SubmenuRoot;
+export const MenuSubmenuTrigger = Primitive.SubmenuTrigger;
+export type MenuContentProps = Primitive.Popup.Props & {
+  /**
+   * Accessible name for the menu. Usually leave this out: Base UI already points the popup's
+   * `aria-labelledby` at whichever trigger opened it, so a name here REPLACES the words on
+   * the button a screen reader just read. Pass it only when the menu is about something the
+   * trigger does not say.
+   */
+  label?: string;
+  /** Where the portal mounts. Defaults to `<body>`. */
+  container?: Primitive.Portal.Props["container"];
+  /**
+   * Positioner props — `side`, `align`, `sideOffset`, `collisionPadding`, and the stacking
+   * order. The default `z-[60]` puts the menu above the overlay layer (z-50: dialog, drawer)
+   * so a menu opened inside a dialog is not painted behind it; raise it with
+   * `positionerProps={{ className: "z-[80]" }}` if the app stacks something higher.
+   */
+  positionerProps?: Primitive.Positioner.Props;
+};
+/**
+ * A dropdown of decisions — the account menu, a row's actions, a picker. Portal, positioner
+ * and popup composed once, for the same reason the dialog's are: the arrangement is not
+ * optional and getting it wrong throws a number.
+ *
+ * Roving focus, typeahead, escape, outside-dismiss and focus return all come from Base UI.
+ * Nothing here re-implements any of them.
+ */
+export function MenuContent({
+  className,
+  children,
+  label,
+  container,
+  positionerProps,
+  ...rest
+}: MenuContentProps) {
+  return (
+    <Primitive.Portal container={container}>
+      <Primitive.Positioner
+        side="bottom"
+        align="end"
+        sideOffset={6}
+        {...positionerProps}
+        className={mergeClassName(
+          "z-[60] max-w-[var(--available-width)]",
+          positionerProps?.className,
+        )}
+      >
+        {/* `outline-none` on the popup and nowhere else in this file: the popup takes focus
+            programmatically the moment it opens, and the ring is meant to answer a keyboard,
+            not to frame a panel that just appeared. The items keep theirs — see below. */}
+        <Primitive.Popup
+          aria-label={label}
+          {...rest}
+          className={mergeClassName(
+            "max-h-[var(--available-height)] min-w-[var(--anchor-width)] origin-[var(--transform-origin)] overflow-y-auto border border-border bg-popover text-popover-foreground outline-none transition-[scale,opacity] data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+            className,
+          )}
+        >
+          {children}
+        </Primitive.Popup>
+      </Primitive.Positioner>
+    </Primitive.Portal>
+  );
+}
+/**
+ * Base UI gives the highlighted item a real `tabIndex: 0` and moves DOM focus to it, so a
+ * keyboard user gets the app's `:focus-visible` outline for free and `data-highlighted` draws
+ * the pointer's highlight. Nothing here suppresses either — a menu row is one of the places
+ * the ring is most needed and most often deleted.
+ *
+ * The coarse-pointer minimum is a 44px row: a thumb misses anything smaller, and a menu is
+ * usually a list of one-way actions.
+ */
+const itemClasses =
+  "flex cursor-default items-center gap-2 px-3 py-1.5 select-none data-disabled:pointer-events-none data-disabled:opacity-50 data-highlighted:bg-accent data-highlighted:text-accent-foreground [@media(pointer:coarse)]:min-h-11";
+export function MenuItem({ className, ...rest }: Primitive.Item.Props) {
+  return <Primitive.Item {...rest} className={mergeClassName(itemClasses, className)} />;
+}
+export function MenuSeparator({ className, ...rest }: Primitive.Separator.Props) {
+  return (
+    <Primitive.Separator {...rest} className={mergeClassName("my-1 h-px bg-border", className)} />
+  );
+}
+/** The caption a group is named by, or nothing. Never a part you place yourself. */
+type MenuGroupCaption = { label?: string };
+const captionClasses = "px-3 pt-2 pb-1 text-muted-foreground";
+// The caption block below is written out TWICE, once per group kind, and that is deliberate.
+// Lifting it into a `caption(label)` helper is the obvious cleanup and it was tried: it moves
+// the `<Primitive.GroupLabel>` out of the `<Primitive.Group>` body it is written inside, and
+// `menu.test.ts` fails immediately — correctly. That guard proves placement by READING THE
+// SOURCE, so an indirection it cannot follow does not just break the test, it retires the
+// guarantee: after the extraction nothing stops a later edit calling `caption()` somewhere that
+// is not inside a group, which is the render-time throw this whole file exists to prevent.
+// Six duplicated lines are the price of a rule a machine can still check. Leave them.
+/**
+ * A set of related items with an optional caption.
+ *
+ * The caption is a PROP because that is the only arrangement that cannot be got wrong: it
+ * lands inside the group, which is both what stops Base UI throwing and what gives the set
+ * its `aria-labelledby`. It is also not focusable, so it never eats an arrow-key stop.
+ * Optional, because a group whose trigger already says what it is would only repeat itself.
+ */
+export function MenuGroup({ label, children, ...rest }: Primitive.Group.Props & MenuGroupCaption) {
+  return (
+    <Primitive.Group {...rest}>
+      {label === undefined ? null : (
+        <Primitive.GroupLabel className={captionClasses}>{label}</Primitive.GroupLabel>
+      )}
+      {children}
+    </Primitive.Group>
+  );
+}
+/** A set of choices — theme, locale, one axis of a filter. Same caption rule as `MenuGroup`. */
+export function MenuRadioGroup({
+  label,
+  children,
+  ...rest
+}: Primitive.RadioGroup.Props & MenuGroupCaption) {
+  return (
+    <Primitive.RadioGroup {...rest}>
+      {label === undefined ? null : (
+        <Primitive.GroupLabel className={captionClasses}>{label}</Primitive.GroupLabel>
+      )}
+      {children}
+    </Primitive.RadioGroup>
+  );
+}
+export type MenuRadioItemProps = Primitive.RadioItem.Props & {
+  /** Mark for the chosen item. */
+  indicator?: ReactNode;
+};
+/**
+ * One choice in a set. The mark keeps a fixed leading column whether or not it is showing, so
+ * the labels do not shift sideways when the selection moves.
+ */
+export function MenuRadioItem({ className, children, indicator, ...rest }: MenuRadioItemProps) {
+  return (
+    <Primitive.RadioItem
+      {...rest}
+      className={mergeClassName([itemClasses, "data-checked:text-foreground"], className)}
+    >
+      <span aria-hidden="true" className="grid size-4 shrink-0 place-items-center">
+        <Primitive.RadioItemIndicator>{indicator ?? <CheckGlyph />}</Primitive.RadioItemIndicator>
+      </span>
+      {children}
+    </Primitive.RadioItem>
+  );
+}