@uniflowed/ui 0.0.0-alpha.13 → 0.0.0-alpha.15

package/internal/disclosure.js

@@ -48,6 +48,58 @@
 // or re-adds the attribute and this upgrades it again. Nothing here writes an
 // attribute React believes it owns while React believes it.
 //
+// # The height a closed panel would have
+//
+// The third rule, and the one that took a piece of work rather than a line.
+// `height: 0 → var(--uf-collapsible-height)` is the whole of animating a
+// disclosure, and the number in that property is the one thing a stylesheet
+// cannot compute: it is the height the content *would* have, wanted at the
+// moment the panel is still closed, because a transition has to know its
+// destination before it starts.
+//
+// Every obvious way of getting it answers zero. A closed panel is `hidden`, so
+// it has no box: `ResizeObserver` reports `0`, `getBoundingClientRect()` is
+// empty, `scrollHeight` is `0`, and `useElementSize` from
+// `@uniflowed/hooks/dom` measures a hidden element and reports zero — which is
+// exactly the moment the number is wanted. Measuring after the panel opens
+// gives the right number one frame late, which is the jank this removes.
+//
+// So `useMeasuredHeight` lays the panel out without painting it: inline
+// `display`, `position: absolute` and `visibility: hidden`, read, restore. Four
+// things about that are not obvious:
+//
+//   * It overrides `display` inline rather than removing `hidden`. The
+//     attribute is `useUntilFound`'s and React's; an effect that took it away
+//     and put it back would be fighting both of them for one frame, and would
+//     lose whichever ran last. An inline declaration beats the user-agent
+//     stylesheet's `[hidden] { display: none }` and touches nothing anybody
+//     else believes they own.
+//   * It sets `content-visibility: visible` in the same pass, because
+//     `hidden="until-found"` is `content-visibility: hidden`, which does not lay
+//     its subtree out either. Defeating one of the two and not the other
+//     measures zero on exactly the panels this package ships.
+//   * It sets `height: auto` in the same pass, for the same reason and against
+//     the very rule this property exists for. A closed panel is `height: 0` —
+//     that is the half of `height: 0 → var(--uf-collapsible-height)` that is
+//     always on — so a panel laid out with the stylesheet still applying
+//     measures zero and writes `0px` back into the property it was asked to
+//     fill. Defeating `display` and not `height` is the same mistake as
+//     defeating `display` and not `content-visibility`, one declaration along.
+//   * And it pins the width, because taking a box out of flow makes it
+//     shrink-to-fit against its containing block — the nearest positioned
+//     ancestor, which on most pages is the viewport. Text that wraps to four
+//     lines where the panel lives measures one line there. The width it would
+//     have in flow is its parent's content box; when that cannot be read the
+//     pass leaves the width alone rather than inventing one.
+//
+// It is opt-in, and that is the honest answer to "it should cost nothing on a
+// page that never animates". Whether a stylesheet reads the property is not
+// something the component can ask — `getComputedStyle` on a `display: none`
+// element answers about the declaration, not about whether anybody transitions
+// on it — so the alternative to a prop is a forced layout per panel per render
+// on every page that has a collapsible, animated or not. A forty-section FAQ is
+// forty synchronous layouts nobody asked for.
+//
 // # Why this is `internal/` and not a subpath
 //
 // The same reason `roving-focus.js` gives. These are rules about markup this
@@ -95,3 +147,152 @@ export hook useUntilFound(ref: { current: HTMLElement | null }, open: boolean):
     element.setAttribute("hidden", "until-found");
   }, [ref, open]);
 }
+
+/** The custom property a stylesheet transitions a disclosure's height to. */
+export const HEIGHT_PROPERTY: string = "--uf-collapsible-height";
+
+/**
+ * The width `element` would have in flow, as a CSS length, or nothing.
+ *
+ * Taking the panel out of flow to measure it costs shrink-to-fit: an absolutely
+ * positioned box with `width: auto` is as wide as its *content* wants to be,
+ * bounded by its containing block — which is the nearest positioned ancestor
+ * and, on most pages, is the viewport rather than the panel's parent. A
+ * paragraph that wraps to four lines in a sidebar measures one line there, and
+ * the number written into the property is then a height the panel never has.
+ *
+ * The width it would have in flow is its parent's content box, which is what
+ * `getComputedStyle` reports for `width` on a laid-out element. Nothing is
+ * returned when the answer is not a length — a parent that is itself
+ * `display: none`, or a DOM with no layout to report — and the pass then does
+ * what it did before rather than pinning a width it had to guess.
+ */
+function widthInFlow(element: HTMLElement): string | null {
+  const parent = element.parentElement;
+  const view: $FlowFixMe = element.ownerDocument?.defaultView;
+  if (parent == null || view == null || typeof view.getComputedStyle !== "function") {
+    return null;
+  }
+  const width: mixed = view.getComputedStyle(parent).width;
+  return typeof width === "string" && width.endsWith("px") ? width : null;
+}
+
+/**
+ * The height `element` has, or would have if it were not hidden.
+ *
+ * The measuring pass, and the reason this module has a header section about it.
+ * An open panel is measured where it stands; a closed one is briefly laid out
+ * and not painted. Either way this reads layout, which is a synchronous reflow
+ * — the caller is the one that decides it is worth paying.
+ *
+ * # The two things a closed panel is not, and has to be made
+ *
+ * Laying it out is necessary and is not sufficient, because the stylesheet this
+ * property exists for is `height: 0` on the closed panel and
+ * `height: var(--uf-collapsible-height)` on the open one. A panel laid out with
+ * that rule still applying measures **zero**, the property is written back as
+ * `0px`, and the transition has a destination of nothing — the bug the whole
+ * hook was written to avoid, arriving through the rule it was written for. So
+ * `height: auto` is set inline for the pass, exactly as `display` is: not
+ * because the panel wants an inline height but because the author declaration
+ * has to be defeated for one synchronous read and put back.
+ *
+ * `width` is the same argument for the other axis and is `widthInFlow`'s. Both
+ * are restored with everything else; a stylesheet is never left fighting an
+ * inline declaration this wrote.
+ */
+function heightOf(element: HTMLElement): number {
+  if (!element.hasAttribute("hidden")) {
+    return element.getBoundingClientRect().height;
+  }
+  const style = element.style;
+  const before = {
+    boxSizing: style.boxSizing,
+    contentVisibility: style.getPropertyValue("content-visibility"),
+    display: style.display,
+    height: style.height,
+    position: style.position,
+    visibility: style.visibility,
+    width: style.width,
+  };
+  // Out of flow and unpainted, so nothing below the panel moves and no frame
+  // shows it. The order is not significant; this is all one style
+  // recalculation, paid for by the single read below.
+  style.display = "block";
+  style.setProperty("content-visibility", "visible");
+  style.position = "absolute";
+  style.visibility = "hidden";
+  style.height = "auto";
+  const width = widthInFlow(element);
+  if (width != null) {
+    // `border-box`, because what fills the parent's content width in flow is
+    // the panel's margin box rather than its content box: measuring a padded
+    // panel content-box wide would make it wider than it will ever be and its
+    // text shorter than it will ever wrap to.
+    style.boxSizing = "border-box";
+    style.width = width;
+  }
+  const height = element.getBoundingClientRect().height;
+  style.boxSizing = before.boxSizing;
+  style.display = before.display;
+  style.setProperty("content-visibility", before.contentVisibility);
+  style.height = before.height;
+  style.position = before.position;
+  style.visibility = before.visibility;
+  style.width = before.width;
+  return height;
+}
+
+/**
+ * Keep `HEIGHT_PROPERTY` on a disclosure's panel equal to its content's height.
+ *
+ * `enabled` is the caller's opt-in; see the module header for why there is one.
+ * When it is off this writes nothing and measures nothing, which is what makes
+ * a page with no animation pay nothing.
+ *
+ * Two effects rather than one, because they answer different questions. The
+ * first measures on every render, with no dependency array on purpose: what the
+ * panel would be worth changes when the *caller* renders different children
+ * into it, and a dependency list here would be a claim about when that happens
+ * that only the caller could keep — `useFirstItem` in `roving-focus.js` makes
+ * the same argument for the same reason. The second watches for a size change
+ * no render caused: an image that finished loading, a font that swapped. It
+ * only ever fires while the panel is open, because a `display: none` element
+ * has no box for a `ResizeObserver` to report on — which is the whole problem
+ * this hook exists for, arriving one more time.
+ */
+export hook useMeasuredHeight(ref: { current: HTMLElement | null }, enabled: boolean): void {
+  useEffect(() => {
+    const element = ref.current;
+    if (!enabled || element == null) {
+      return;
+    }
+    const measured = `${String(heightOf(element))}px`;
+    // Compared before writing, so a render that changed nothing does not dirty
+    // the element's style and invite another style recalculation.
+    if (element.style.getPropertyValue(HEIGHT_PROPERTY) !== measured) {
+      element.style.setProperty(HEIGHT_PROPERTY, measured);
+    }
+  });
+
+  useEffect(() => {
+    const element = ref.current;
+    const view = element?.ownerDocument?.defaultView;
+    if (!enabled || element == null || view == null) {
+      return;
+    }
+    // Read off the window rather than through a local, for the reason
+    // `internal/anchor.js` gives where it does the same: a capitalised name
+    // holding a constructor is read as a React component by `uf lint`, and the
+    // window's own property is the thing being asked about anyway.
+    const host: $FlowFixMe = view;
+    if (typeof host.ResizeObserver !== "function") {
+      return;
+    }
+    const sizes = new host.ResizeObserver(() => {
+      element.style.setProperty(HEIGHT_PROPERTY, `${String(heightOf(element))}px`);
+    });
+    sizes.observe(element);
+    return () => sizes.disconnect();
+  }, [ref, enabled]);
+}

package/internal/menu-tree.js

@@ -0,0 +1,228 @@
+// @flow
+//
+// What every menu in this package is a menu *of*.
+//
+// `menu.js` was one module because there was one menu. shadcn ships four
+// components on this behaviour — a dropdown menu, a context menu, a menubar and
+// the checkable items all three of them share — and the three that are not the
+// dropdown differ from it in exactly two places: what opens the menu, and where
+// the menu goes. Everything between those two — the tree of open levels, what
+// `Escape` closes, what "choosing an item" dismisses, which selector finds an
+// item and which finds its owner — is one set of rules, and this is it.
+//
+// Written down here rather than exported from `menu.js` for the reason every
+// other module in `internal/` gives: these are relationships the components
+// build, not a menu-building kit. `MENU_SELECTOR` is only true because
+// `Menu.Body` renders `role="menu"`; handed to a consumer it would be a
+// selector that happens to work.
+//
+// # A menu is a chain, not a flag
+//
+// A submenu is a menu whose parent is another menu, and almost every rule that
+// distinguishes the two is a statement about that chain:
+//
+//   * `Escape` closes *one* level, so it needs to know which one it is in.
+//   * Choosing an item closes the whole chain, because leaving the parent menu
+//     open after a command has run is a state no native menu has been in.
+//   * Only the outermost level listens for a press outside, because a submenu
+//     closes with the tree and two listeners would each answer one press.
+//
+// So the chain is the shape the context carries, and `parent` is what a level
+// is given rather than something it works out.
+//
+// # Where a menu goes, when it is not against its trigger
+//
+// A context menu opens at the pointer, which is a *point* and not an element.
+// `MenuAnchorContext` is how a level says so: a rectangle that replaces the
+// trigger's own measurement inside `internal/anchor.js`, and nothing else — the
+// trigger element is still what the writing direction is read from and what
+// focus goes back to. A level with no provider above it measures its trigger,
+// which is every menu that hangs off a button.
+
+"use client";
+
+import * as React from "@uniflowed/react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+import type { Rect } from "./anchor.js";
+import type { Direction } from "./roving-focus.js";
+import { useControlled } from "./controlled-state.js";
+
+/**
+ * Anything that plays the part of a menu item, including the two checkable
+ * kinds. The keyboard has to move between all of them, so the selector names
+ * all of them rather than only the plain command.
+ */
+export const ITEM_SELECTOR: string =
+  '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]';
+
+/** What owns an item: the nearest menu, so a submenu keeps its own. */
+export const MENU_SELECTOR: string = '[role="menu"]';
+
+/**
+ * Which arrow key opens a submenu, and which closes it.
+ *
+ * The WAI-ARIA menu pattern puts a submenu on the *inline end*, so it opens to
+ * the right of a left-to-right menu and to the left of a right-to-left one, and
+ * the key that opens it is the one pointing at it. Written out as
+ * `ArrowRight` to open and `ArrowLeft` to close, an RTL reader pressed the key
+ * aimed at the submenu and closed the menu they were standing in — which is
+ * worse than nothing happening, because it loses their place.
+ */
+export function submenuKeys(direction: Direction): {|
+  readonly open: string,
+  readonly close: string,
+|} {
+  return direction === "rtl"
+    ? { open: "ArrowLeft", close: "ArrowRight" }
+    : { open: "ArrowRight", close: "ArrowLeft" };
+}
+
+export type MenuState = {|
+  readonly base: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  /** What opened this menu, and what focus goes back to when it closes. */
+  readonly triggerRef: { current: HTMLElement | null },
+  /**
+   * Which end the menu should open onto, written by whatever opened it.
+   *
+   * A ref rather than state because it is an instruction for the next commit,
+   * not a value anything renders: `ArrowUp` on a closed menu opens it *and*
+   * lands on the last item, and re-rendering the trigger to say so would be a
+   * render whose only purpose is to carry a message to an effect.
+   */
+  readonly pendingFocus: { current: "first" | "last" | null },
+  /** The menu this one hangs off, or null for the outermost. */
+  readonly parent: MenuState | null,
+  /**
+   * Whether a trigger is rendered *and* is something worth naming the menu
+   * after, so the body only claims a name that exists.
+   *
+   * A menu opened by `defaultOpen` in a page that never renders a trigger is a
+   * real arrangement, and an `aria-labelledby` pointing at the id that trigger
+   * *would* have had makes a screen reader announce nothing at all. A context
+   * menu's trigger is arbitrary content rather than a label, and registers
+   * itself as a trigger without registering itself as a name.
+   */
+  readonly triggered: boolean,
+  readonly registerTrigger: (present: boolean) => void,
+|};
+
+export const MenuContext: React.Context<MenuState | null> = createContext(null);
+
+/**
+ * The roving tab stop of one open menu.
+ *
+ * Provided by `Menu.Body` rather than by the root, because a submenu is a
+ * second list with a tab stop of its own: nesting the provider is what stops
+ * the parent menu and the submenu from fighting over which item is `tabindex=0`.
+ */
+export type MenuListState = {|
+  readonly activeId: string | null,
+  readonly setActiveId: (id: string | null) => void,
+|};
+
+export const MenuListContext: React.Context<MenuListState | null> = createContext(null);
+
+/**
+ * A box a menu body is placed against instead of its trigger's own.
+ *
+ * `null`, and no provider at all, both mean "measure the trigger". See the
+ * module header, and `AnchorRequest.anchorRect` for what it replaces.
+ */
+export const MenuAnchorContext: React.Context<Rect | null> = createContext(null);
+
+export hook useMenu(part: string): MenuState {
+  const state = useContext(MenuContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Menu.Root`);
+  }
+  return state;
+}
+
+/**
+ * Tell the menu that something worth naming it after is in the document.
+ *
+ * `Menu.Body` names its trigger with `aria-labelledby`, and it may only do that
+ * while there is one to name — a menu opened by `defaultOpen` in a page with no
+ * trigger would otherwise point at an id nothing has, and a screen reader given
+ * a dangling `aria-labelledby` announces nothing at all rather than falling back
+ * to the element's own content.
+ */
+export hook useTriggerRegistration(menu: MenuState): void {
+  const register = menu.registerTrigger;
+  useEffect(() => {
+    register(true);
+    return () => register(false);
+  }, [register]);
+}
+
+/** Every menu from `menu` outwards, innermost first. */
+export function ancestry(menu: MenuState): Array<MenuState> {
+  const chain = [];
+  let at: MenuState | null = menu;
+  while (at != null) {
+    chain.push(at);
+    at = at.parent;
+  }
+  return chain;
+}
+
+/**
+ * Close this menu and every menu it hangs off.
+ *
+ * Choosing an item in a submenu dismisses the whole thing — leaving the parent
+ * menu open after a command has run is a state no native menu has ever been in,
+ * and it leaves the reader looking at a menu whose action already happened.
+ */
+export function closeTree(menu: MenuState): void {
+  for (const each of ancestry(menu)) {
+    each.setOpen(false);
+  }
+}
+
+/**
+ * One level of the menu tree.
+ *
+ * Shared by `Menu.Root`, `Menu.Sub`, `ContextMenu.Root` and `Menubar.Menu`,
+ * which differ only in what they hand it: a submenu knows its parent, and a
+ * menubar's menu is opened and closed by the bar rather than by itself.
+ */
+export component MenuLevel(
+  children: React.Node,
+  parent: MenuState | null,
+  defaultOpen: boolean,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  const base = useId();
+  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const pendingFocus = useRef<"first" | "last" | null>(null);
+  const [triggered, setTriggered] = useState(false);
+
+  const state = useMemo(
+    () => ({
+      base,
+      open: isOpen,
+      setOpen,
+      triggerRef,
+      pendingFocus,
+      parent,
+      triggered,
+      registerTrigger: setTriggered,
+    }),
+    [base, isOpen, setOpen, parent, triggered],
+  );
+
+  return <MenuContext.Provider value={state}>{children}</MenuContext.Provider>;
+}