@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/menu/react/context.ts

@@ -0,0 +1,31 @@
+"use client";
+
+import { createContext, use } from "react";
+import type { MenuCloseReason, MenuSlot } from "../core/types";
+
+export interface MenuContextValue {
+  /** Closes this menu and, for a submenu, everything above it. */
+  close(reason: MenuCloseReason): void;
+  /** Close the whole stack after a choice. False keeps it open, e.g. for checkboxes. */
+  closeOnSelect: boolean;
+  classNames?: Partial<Record<MenuSlot, string>>;
+  /** Depth, so a submenu knows it has a parent to hand focus back to. */
+  depth: number;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext(component: string): MenuContextValue {
+  const context = use(MenuContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside a <Menu>.`);
+  }
+  return context;
+}
+
+export interface RadioGroupContextValue {
+  value: string | undefined;
+  select(value: string): void;
+}
+
+export const MenuRadioContext = createContext<RadioGroupContextValue | null>(null);

package/source/components/menu/react/items.tsx

@@ -0,0 +1,268 @@
+"use client";
+
+import {
+  use,
+  useId,
+  useMemo,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { CheckIcon } from "../../shared/react/icons";
+import { MenuRadioContext, useMenuContext } from "./context";
+import { cx } from "./props";
+
+interface BaseItemProps {
+  children: ReactNode;
+  /** Drawn before the label, at the size of the text. */
+  icon?: ReactNode;
+  /** A hint such as ⌘K. The menu shows it; binding the key is up to you. */
+  shortcut?: ReactNode;
+  disabled?: boolean;
+  /** Styles it as a destructive action. */
+  destructive?: boolean;
+  className?: string;
+}
+
+export interface MenuItemProps extends BaseItemProps {
+  /** Called when the item is chosen, by click, Enter or Space. */
+  onSelect?(): void;
+  /** Keep the menu open after choosing. Defaults to the Menu's `closeOnSelect`. */
+  closeOnSelect?: boolean;
+}
+
+/**
+ * Disabled items stay focusable, as the WAI-ARIA menu pattern prefers: someone
+ * navigating by keyboard should be able to find out that an action exists but
+ * is unavailable, rather than have it silently skipped. `useMenuKeys` does skip
+ * them when arrowing, so they never trap the sequence.
+ */
+function itemAttributes(disabled: boolean, destructive: boolean) {
+  return {
+    tabIndex: -1,
+    "aria-disabled": disabled || undefined,
+    "data-disabled": disabled || undefined,
+    "data-destructive": destructive || undefined,
+  } as const;
+}
+
+/** Runs an action on Enter or Space, the keys the pattern reserves for choosing. */
+function activationKeys(run: () => void) {
+  return (event: KeyboardEvent<HTMLElement>) => {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    event.preventDefault();
+    event.stopPropagation();
+    run();
+  };
+}
+
+export function MenuItem(props: MenuItemProps) {
+  const {
+    children,
+    icon,
+    shortcut,
+    disabled = false,
+    destructive = false,
+    onSelect,
+    closeOnSelect,
+    className,
+  } = props;
+  const menu = useMenuContext("MenuItem");
+
+  const choose = () => {
+    if (disabled) return;
+    onSelect?.();
+    if (closeOnSelect ?? menu.closeOnSelect) menu.close("select");
+  };
+
+  return (
+    <div
+      role="menuitem"
+      {...itemAttributes(disabled, destructive)}
+      className={cx("mn-item", menu.classNames?.item, className)}
+      onClick={(event: MouseEvent<HTMLElement>) => {
+        event.stopPropagation();
+        choose();
+      }}
+      onKeyDown={activationKeys(choose)}
+    >
+      {icon && <span className={cx("mn-icon", menu.classNames?.icon)}>{icon}</span>}
+      <span className={cx("mn-label", menu.classNames?.label)}>{children}</span>
+      {shortcut && (
+        <span className={cx("mn-shortcut", menu.classNames?.shortcut)}>{shortcut}</span>
+      )}
+    </div>
+  );
+}
+
+export interface MenuCheckboxItemProps extends BaseItemProps {
+  checked?: boolean;
+  onCheckedChange?(checked: boolean): void;
+  /** Default false: toggling several options in a row is the usual case. */
+  closeOnSelect?: boolean;
+}
+
+export function MenuCheckboxItem(props: MenuCheckboxItemProps) {
+  const {
+    children,
+    icon,
+    shortcut,
+    checked = false,
+    onCheckedChange,
+    disabled = false,
+    destructive = false,
+    closeOnSelect = false,
+    className,
+  } = props;
+  const menu = useMenuContext("MenuCheckboxItem");
+
+  const toggle = () => {
+    if (disabled) return;
+    onCheckedChange?.(!checked);
+    if (closeOnSelect) menu.close("select");
+  };
+
+  return (
+    <div
+      role="menuitemcheckbox"
+      aria-checked={checked}
+      {...itemAttributes(disabled, destructive)}
+      className={cx("mn-item", menu.classNames?.item, className)}
+      onClick={(event: MouseEvent<HTMLElement>) => {
+        event.stopPropagation();
+        toggle();
+      }}
+      onKeyDown={activationKeys(toggle)}
+    >
+      <span className={cx("mn-indicator", menu.classNames?.indicator)} aria-hidden="true">
+        {checked && <CheckIcon width={14} height={14} />}
+      </span>
+      {icon && <span className={cx("mn-icon", menu.classNames?.icon)}>{icon}</span>}
+      <span className={cx("mn-label", menu.classNames?.label)}>{children}</span>
+      {shortcut && (
+        <span className={cx("mn-shortcut", menu.classNames?.shortcut)}>{shortcut}</span>
+      )}
+    </div>
+  );
+}
+
+export interface MenuRadioGroupProps {
+  value?: string;
+  onValueChange?(value: string): void;
+  /** Names the group, and is shown above it when it is a string. */
+  label?: ReactNode;
+  children: ReactNode;
+  className?: string;
+}
+
+export function MenuRadioGroup({
+  value,
+  onValueChange,
+  label,
+  children,
+  className,
+}: MenuRadioGroupProps) {
+  const menu = useMenuContext("MenuRadioGroup");
+  const id = useId();
+  const context = useMemo(
+    () => ({ value, select: (next: string) => onValueChange?.(next) }),
+    [value, onValueChange],
+  );
+
+  return (
+    <MenuRadioContext value={context}>
+      <div
+        role="group"
+        aria-labelledby={label ? `${id}-label` : undefined}
+        className={cx("mn-group", menu.classNames?.group, className)}
+      >
+        {label && (
+          <div id={`${id}-label`} className={cx("mn-group-label", menu.classNames?.groupLabel)}>
+            {label}
+          </div>
+        )}
+        {children}
+      </div>
+    </MenuRadioContext>
+  );
+}
+
+export interface MenuRadioItemProps extends BaseItemProps {
+  value: string;
+  /** Default false, so a list of choices can be tried without reopening. */
+  closeOnSelect?: boolean;
+}
+
+export function MenuRadioItem(props: MenuRadioItemProps) {
+  const { children, icon, shortcut, value, disabled = false, closeOnSelect = false, className } = props;
+  const menu = useMenuContext("MenuRadioItem");
+  const group = use(MenuRadioContext);
+  if (!group) throw new Error("MenuRadioItem must be rendered inside a <MenuRadioGroup>.");
+
+  const checked = group.value === value;
+  const choose = () => {
+    if (disabled) return;
+    group.select(value);
+    if (closeOnSelect) menu.close("select");
+  };
+
+  return (
+    <div
+      role="menuitemradio"
+      aria-checked={checked}
+      {...itemAttributes(disabled, false)}
+      className={cx("mn-item", menu.classNames?.item, className)}
+      onClick={(event: MouseEvent<HTMLElement>) => {
+        event.stopPropagation();
+        choose();
+      }}
+      onKeyDown={activationKeys(choose)}
+    >
+      <span className={cx("mn-indicator", menu.classNames?.indicator)} aria-hidden="true">
+        {checked && <span className="mn-dot" />}
+      </span>
+      {icon && <span className={cx("mn-icon", menu.classNames?.icon)}>{icon}</span>}
+      <span className={cx("mn-label", menu.classNames?.label)}>{children}</span>
+      {shortcut && (
+        <span className={cx("mn-shortcut", menu.classNames?.shortcut)}>{shortcut}</span>
+      )}
+    </div>
+  );
+}
+
+export interface MenuGroupProps {
+  label?: ReactNode;
+  children: ReactNode;
+  className?: string;
+}
+
+/** A titled section. The title is a label, not an item, so it is never focused. */
+export function MenuGroup({ label, children, className }: MenuGroupProps) {
+  const menu = useMenuContext("MenuGroup");
+  const id = useId();
+
+  return (
+    <div
+      role="group"
+      aria-labelledby={label ? `${id}-label` : undefined}
+      className={cx("mn-group", menu.classNames?.group, className)}
+    >
+      {label && (
+        <div id={`${id}-label`} className={cx("mn-group-label", menu.classNames?.groupLabel)}>
+          {label}
+        </div>
+      )}
+      {children}
+    </div>
+  );
+}
+
+export function MenuSeparator({ className }: { className?: string }) {
+  const menu = useMenuContext("MenuSeparator");
+  return (
+    <div
+      role="separator"
+      className={cx("mn-separator", menu.classNames?.separator, className)}
+    />
+  );
+}

package/source/components/menu/react/locale.ts

@@ -0,0 +1,6 @@
+import type { MenuLocaleText } from "../core/types";
+
+export const defaultMenuText: MenuLocaleText = {
+  label: "Menu",
+  submenu: (label) => `${label} submenu`,
+};

package/source/components/menu/react/props.ts

@@ -0,0 +1,4 @@
+export type { MenuShortcut, MenuSlot } from "../core/types";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/menu/react/useMenuKeys.ts

@@ -0,0 +1,124 @@
+"use client";
+
+import { useCallback, useRef, type KeyboardEvent, type RefObject } from "react";
+import {
+  edgeIndex,
+  isTypeaheadKey,
+  nextIndex,
+  typeaheadBuffer,
+  typeaheadIndex,
+} from "../core/navigation";
+
+/** Every item the keyboard can reach, in the order they appear. */
+const ITEM_SELECTOR = '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]';
+
+export interface MenuKeysOptions {
+  listRef: RefObject<HTMLElement | null>;
+  /** Escape, or ArrowLeft inside a submenu. */
+  onDismiss(): void;
+  /** True inside a submenu, where ArrowLeft goes back to the parent. */
+  nested: boolean;
+  rtl?: boolean;
+}
+
+/**
+ * Keyboard behaviour for the WAI-ARIA menu pattern: arrows with wrap-around,
+ * Home and End, and typeahead.
+ *
+ * Items are read from the DOM rather than registered through context. A menu is
+ * a flat list of elements that are already in the document in the right order,
+ * so asking the DOM is both simpler and impossible to get out of step with what
+ * is on screen.
+ */
+export function useMenuKeys({ listRef, onDismiss, nested, rtl = false }: MenuKeysOptions) {
+  const typeahead = useRef({ buffer: "", at: 0 });
+
+  const items = useCallback(
+    () => Array.from(listRef.current?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []),
+    [listRef],
+  );
+
+  const focusAt = useCallback(
+    (elements: HTMLElement[], index: number) => {
+      if (index < 0) return;
+      elements[index]?.focus();
+    },
+    [],
+  );
+
+  /** Focus the first item; used when the menu opens from the keyboard. */
+  const focusFirst = useCallback(() => {
+    const elements = items();
+    focusAt(elements, edgeIndex(describe(elements), "first"));
+  }, [items, focusAt]);
+
+  const focusLast = useCallback(() => {
+    const elements = items();
+    focusAt(elements, edgeIndex(describe(elements), "last"));
+  }, [items, focusAt]);
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      const elements = items();
+      if (elements.length === 0) return;
+      const described = describe(elements);
+      const current = elements.indexOf(document.activeElement as HTMLElement);
+
+      const back = rtl ? "ArrowRight" : "ArrowLeft";
+
+      switch (event.key) {
+        case "ArrowDown":
+          event.preventDefault();
+          focusAt(elements, nextIndex(described, current, 1));
+          return;
+        case "ArrowUp":
+          event.preventDefault();
+          focusAt(elements, nextIndex(described, current, -1));
+          return;
+        case "Home":
+          event.preventDefault();
+          focusAt(elements, edgeIndex(described, "first"));
+          return;
+        case "End":
+          event.preventDefault();
+          focusAt(elements, edgeIndex(described, "last"));
+          return;
+        case "Escape":
+          event.preventDefault();
+          event.stopPropagation();
+          onDismiss();
+          return;
+        case back:
+          if (!nested) return;
+          event.preventDefault();
+          event.stopPropagation();
+          onDismiss();
+          return;
+        case "Tab":
+          // Tab leaves the menu entirely, as the pattern requires.
+          onDismiss();
+          return;
+        default:
+          break;
+      }
+
+      if (!isTypeaheadKey(event.key, event.ctrlKey || event.metaKey || event.altKey)) return;
+      event.preventDefault();
+      const now = Date.now();
+      const buffer = typeaheadBuffer(typeahead.current.buffer, event.key, now - typeahead.current.at);
+      typeahead.current = { buffer, at: now };
+      focusAt(elements, typeaheadIndex(described, buffer, current));
+    },
+    [items, focusAt, onDismiss, nested, rtl],
+  );
+
+  return { onKeyDown, focusFirst, focusLast };
+}
+
+/** The bits of each element the navigation rules care about. */
+function describe(elements: HTMLElement[]) {
+  return elements.map((element) => ({
+    disabled: element.getAttribute("aria-disabled") === "true",
+    text: element.textContent ?? "",
+  }));
+}

package/source/components/menu/styles.css

@@ -0,0 +1,224 @@
+/*
+ * Menu styles.
+ *
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules are unlayered: they beat a framework
+ * reset on specificity, and lose to anything you pass through `className`.
+ * With Tailwind v4, import this file after the framework and inside its
+ * components layer - see the README.
+ */
+
+.mn-root {
+  --mn-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --mn-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --mn-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --mn-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --mn-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --mn-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --mn-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --mn-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --mn-shadow: var(--gbs-shadow, var(--dg-shadow, 0 10px 30px -8px light-dark(rgb(0 0 0 / 0.18), rgb(0 0 0 / 0.6))));
+  --mn-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --mn-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --mn-item-radius: 5px;
+  --mn-min-width: 180px;
+  --mn-duration: 120ms;
+
+  position: fixed;
+  inset: auto;
+  z-index: 60;
+  min-width: var(--mn-min-width);
+  max-width: min(320px, calc(100vw - 16px));
+  margin: 0;
+  padding: 4px;
+  overflow: auto;
+  overscroll-behavior: contain;
+  border: 1px solid var(--mn-border);
+  border-radius: var(--mn-radius);
+  background: var(--mn-bg);
+  color: var(--mn-fg);
+  box-shadow: var(--mn-shadow);
+  color-scheme: inherit;
+  font-size: var(--mn-font-size);
+  line-height: 1.4;
+  scrollbar-width: var(--gbs-scrollbar-width, thin);
+  scrollbar-color: var(--gbs-scrollbar-thumb, light-dark(#c4c4ca, #3f3f46))
+    var(--gbs-scrollbar-track, transparent);
+}
+
+:where(.dark, [data-theme="dark"]) .mn-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .mn-root {
+  color-scheme: light;
+}
+
+:where(.mn-root) *,
+:where(.mn-root) *::before,
+:where(.mn-root) *::after {
+  box-sizing: border-box;
+}
+
+/* The list takes focus before the first item does; that flash of an outline
+   around the whole menu is not useful. */
+.mn-root:focus,
+.mn-list:focus {
+  outline: none;
+}
+
+.mn-root:popover-open {
+  animation: mn-in var(--mn-duration) ease;
+}
+@keyframes mn-in {
+  from {
+    opacity: 0;
+    translate: 0 -2px;
+  }
+}
+.mn-root[data-side="top"]:popover-open {
+  animation-name: mn-in-top;
+}
+@keyframes mn-in-top {
+  from {
+    opacity: 0;
+    translate: 0 2px;
+  }
+}
+
+.mn-list {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+/* --------------------------------------------------------------- items */
+
+.mn-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+  padding: 6px 8px;
+  border-radius: var(--mn-item-radius);
+  cursor: default;
+  user-select: none;
+}
+.mn-item:hover:not([data-disabled]) {
+  background: var(--mn-hover);
+}
+/* Menus move focus rather than tracking a separate active item, so the
+   focused item is the highlighted one. */
+.mn-item:focus {
+  background: var(--mn-hover);
+  outline: none;
+}
+.mn-item:focus-visible {
+  outline: 2px solid var(--mn-focus);
+  outline-offset: -2px;
+}
+.mn-item[data-disabled] {
+  color: var(--mn-muted);
+  cursor: not-allowed;
+}
+.mn-item[data-destructive]:not([data-disabled]) {
+  color: var(--mn-danger);
+}
+
+.mn-label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.mn-icon {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  color: var(--mn-muted);
+}
+.mn-item[data-destructive] .mn-icon {
+  color: inherit;
+}
+
+.mn-shortcut {
+  flex: none;
+  margin-inline-start: auto;
+  padding-inline-start: 12px;
+  color: var(--mn-muted);
+  font-size: 0.92em;
+  font-variant-numeric: tabular-nums;
+}
+
+/* The indicator column keeps labels aligned whether or not an item is
+   checked, so the list does not shift as things are toggled. */
+.mn-indicator {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  color: var(--mn-accent);
+}
+.mn-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: currentColor;
+}
+
+/* -------------------------------------------------------------- groups */
+
+.mn-group {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+.mn-group-label {
+  padding: 6px 8px 2px;
+  color: var(--mn-muted);
+  font-size: 0.85em;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.mn-separator {
+  height: 1px;
+  margin: 4px -4px;
+  background: var(--mn-border);
+}
+
+/* ------------------------------------------------------------ submenus */
+
+.mn-sub-trigger .mn-sub-arrow {
+  flex: none;
+  margin-inline-start: auto;
+  color: var(--mn-muted);
+}
+/* The arrow points into the submenu, which is on the other side in RTL. */
+.mn-root:dir(rtl) .mn-sub-arrow {
+  rotate: 180deg;
+}
+.mn-sub-trigger[aria-expanded="true"] {
+  background: var(--mn-hover);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mn-root:popover-open {
+    animation: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .mn-root {
+    border: 1px solid CanvasText;
+  }
+  .mn-item:focus {
+    outline: 2px solid Highlight;
+    outline-offset: -2px;
+  }
+}