@gregogun/radial-menu 0.1.0-alpha.0

package/dist/modules/radialMenu/RadialMenu.d.ts

@@ -0,0 +1,60 @@
+import { ContextMenu } from '@base-ui/react/context-menu';
+import { MenuItem, SubmenuLayout, SubsectionDirection } from '../../types';
+/** Imperative handle exposed via `RadialMenu.Root`'s `actionsRef` — open the
+ *  menu from outside any pointer gesture (e.g. a game event, a keybind). */
+export interface RadialMenuActions {
+    /** Open centred on the viewport point (clientX, clientY). */
+    open: (x: number, y: number) => void;
+    /** Open centred on an element's bounding-box centre. */
+    openAtElement: (el: Element) => void;
+    /** Close the menu. */
+    close: () => void;
+}
+export interface RadialMenuRootProps {
+    /** The ordered radial items. Position = f(index, count): order IS placement —
+     *  item 0 is the top wedge, the rest fan clockwise. A parent item carries a
+     *  `submenu`; a leaf carries `onSelect`. */
+    items: MenuItem[];
+    /** Diameter of the root ring in px. Default 250. */
+    size?: number;
+    /** Submenu band layout: `"halved"` (band spans half a wedge per child) or
+     *  `"full"` (a full wedge per child). Default "halved". */
+    layout?: SubmenuLayout;
+    /** Submenu fan direction. Default "cw". */
+    direction?: SubsectionDirection;
+    /** Submenu band thickness as a fraction of `size`. Default 0.3. */
+    submenuThickness?: number;
+    /** Gap between the root rim and the submenu band, in px. Default 8. */
+    ringGap?: number;
+    /** Dwell (ms) before a hovered submenu-parent opens. Default 280. */
+    openDelay?: number;
+    /** Controlled open state. Pair with `onOpenChange`. */
+    open?: boolean;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: boolean;
+    /** Called when the menu opens or closes (after the internal highlight-gate
+     *  reset runs). */
+    onOpenChange?: (open: boolean) => void;
+    /** Imperative handle for programmatic open/close (see RadialMenuActions). */
+    actionsRef?: React.Ref<RadialMenuActions>;
+    /** A `RadialMenu.Trigger` (the right-click target). Optional — omit for a
+     *  purely programmatic menu driven via `actionsRef` / controlled `open`. */
+    children?: React.ReactNode;
+}
+export declare function RadialMenuRoot(props: RadialMenuRootProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The right-click / long-press target. A thin wrapper over Base UI's
+ * `ContextMenu.Trigger` that registers its element with the surrounding
+ * `RadialMenu.Root` (for the imperative open path). Compose your own element via
+ * `render` (Base UI's pattern):
+ *
+ *   <RadialMenu.Trigger render={(props) => <button {...props}>Menu</button>} />
+ */
+export interface RadialMenuTriggerProps extends React.ComponentProps<typeof ContextMenu.Trigger> {
+}
+export declare function RadialMenuTrigger(props: RadialMenuTriggerProps): import("react/jsx-runtime").JSX.Element;
+/** Base-UI-style parts namespace: `<RadialMenu.Root>` + `<RadialMenu.Trigger>`. */
+export declare const RadialMenu: {
+    Root: typeof RadialMenuRoot;
+    Trigger: typeof RadialMenuTrigger;
+};

package/dist/modules/radialMenu/geometry.d.ts

@@ -0,0 +1,47 @@
+import { MenuItem, SubmenuLayout, SubsectionDirection } from '../../types';
+export declare const ITEM_OFFSET = 90;
+export declare const normalizeAngle: (angle: number) => number;
+/** Point on a circle (screen degrees, y-down). */
+export declare const polar: (cx: number, cy: number, r: number, deg: number) => [number, number];
+/** SVG path for a bare arc at radius `r` from `a0` to `a1` screen degrees. */
+export declare const arc: (cx: number, cy: number, r: number, a0: number, a1: number) => string;
+/** SVG path for an annular sector (ring slice) from `a0` to `a1` screen degrees. */
+export declare const annularSector: (cx: number, cy: number, innerR: number, outerR: number, a0: number, a1: number) => string;
+/**
+ * Sample an annular-sector wedge into a `clip-path: polygon()` point list, in
+ * percentages of a `boxSize`-sided box. The arc need not be exact — this clips
+ * a wedge's hit/focus target; the crisp visual is the SVG path beneath. We walk
+ * the outer arc a0→a1, then the inner arc back a1→a0.
+ */
+export declare const wedgeClip: (boxSize: number, cx: number, cy: number, innerR: number, outerR: number, a0: number, a1: number) => string;
+/** Resolved band placement for one open submenu (root SVG viewBox units). */
+export interface SubBandGeometry {
+    count: number;
+    startAngle: number;
+    span: number;
+    subStep: number;
+    innerR: number;
+    outerR: number;
+}
+/** Whole-menu inputs the band derivation reads (count comes from `menuItems`). */
+export interface BandLayout {
+    layout: SubmenuLayout;
+    direction: SubsectionDirection;
+    size: number;
+    ringGap: number;
+    submenuThickness: number;
+}
+/**
+ * Where the band for `parentIndex` sits: start angle, span, per-child step, and
+ * radii. `count` is the number of ROOT wedges (sets the base step); `childCount`
+ * the parent's children.
+ */
+export declare function bandGeometry(band: BandLayout & {
+    count: number;
+}, parentIndex: number, childCount: number): SubBandGeometry;
+/**
+ * Build the per-parent band lookup the router calls: given the menu's items +
+ * band layout, returns `(parentIndex) → SubBandGeometry | null` (null when the
+ * parent has no children).
+ */
+export declare function makeSubRadii(menuItems: MenuItem[], band: BandLayout): (parentIndex: number) => SubBandGeometry | null;

package/dist/modules/radialMenu/shared/context.d.ts

@@ -0,0 +1,6 @@
+export interface RadialMenuContextValue {
+    /** Trigger calls this with its DOM element (or null on unmount). */
+    registerTrigger: (el: HTMLElement | null) => void;
+}
+export declare const RadialMenuContext: import('react').Context<RadialMenuContextValue | null>;
+export declare function useRadialMenuContext(): RadialMenuContextValue;

package/dist/modules/radialMenu/shared/theme.d.ts

@@ -0,0 +1,8 @@
+export declare const RADIAL: {
+    readonly c1: "var(--radial-1, #fcfcfd)";
+    readonly c2: "var(--radial-2, #f9f9fb)";
+    readonly c3: "var(--radial-3, #f0f0f3)";
+    readonly c4: "var(--radial-4, #e8e8ec)";
+    readonly c11: "var(--radial-11, #60646c)";
+    readonly c12: "var(--radial-12, #1c2024)";
+};

package/dist/modules/radialMenu/skin/RootRing.d.ts

@@ -0,0 +1,29 @@
+import { MenuItem } from '../../../types';
+/** Root pie geometry in the SVG's local viewBox units. */
+export interface RootGeometry {
+    /** viewBox side (== size). */
+    box: number;
+    /** Centre x/y (== size / 2). */
+    c: number;
+    /** Inner radius — the centre hub edge. */
+    innerR: number;
+    /** Outer radius — the rim (== size / 2). */
+    outerR: number;
+    /** Degrees per wedge (360 / count). */
+    step: number;
+    /** Icon-placement radius along the wedge bisector. */
+    iconR: number;
+}
+/**
+ * The root ring skin. `selected` is the highlighted wedge index (Base UI's
+ * activeIndex, mirrored up by the parent); `centerLabel` is the deepest active
+ * selection. `children` are the parent-supplied focusable hit-targets, layered
+ * above the visual skin inside the same SVG.
+ */
+export declare function RootRing({ menuItems, selected, centerLabel, geometry, children, }: {
+    menuItems: MenuItem[];
+    selected: number | null;
+    centerLabel: string | null;
+    geometry: RootGeometry;
+    children?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/modules/radialMenu/skin/SubBand.d.ts

@@ -0,0 +1,17 @@
+import { MenuItem, SubmenuLayout, SubsectionDirection } from '../../../types';
+/** One submenu band, drawn locally inside the SubmenuRoot's Popup. */
+export declare function SubBand({ parent, parentIndex, count, layout, direction, size, ringGap, submenuThickness, captureChild, onActiveLabel, }: {
+    parent: MenuItem;
+    parentIndex: number;
+    /** Number of ROOT wedges (sets the base step the band fans out from). */
+    count: number;
+    layout: SubmenuLayout;
+    direction: SubsectionDirection;
+    size: number;
+    ringGap: number;
+    submenuThickness: number;
+    /** Register child j's focusable element with the router (in render order). */
+    captureChild: (j: number, el: HTMLElement | null) => void;
+    /** Report the highlighted child's label (or null) up for the centre disc. */
+    onActiveLabel: (label: string | null) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/modules/radialMenu/useAngleRouter.d.ts

@@ -0,0 +1,45 @@
+import { MenuItem } from '../../types';
+import { SubBandGeometry } from './geometry';
+interface AngleRouterOptions {
+    menuItems: MenuItem[];
+    count: number;
+    /** Root SVG viewBox size (px); the cursor is mapped back into these units. */
+    box: number;
+    /** Centre hub radius — inside this is "cancel" (deselect + close). */
+    innerR: number;
+    /** Root rim radius — outside this, an open submenu owns the angle. */
+    outerR: number;
+    /** Degrees per root wedge (360 / count). */
+    step: number;
+    /** Dwell before a hovered submenu-parent opens (ms). */
+    openDelay: number;
+    /** Band geometry for a given parent index, or null if it has no children. */
+    subRadii: (parentIndex: number) => SubBandGeometry | null;
+    /** Currently-open submenu parent index (controlled), or null. */
+    openSub: number | null;
+    setOpenSub: (next: number | null) => void;
+    /**
+     * Called on the first genuine pointer move that lands OUTSIDE the hub (i.e. on
+     * a wedge/band, not the centre-cancel zone). Lets the component arm its
+     * highlight gate so a stale reopen-highlight is suppressed until the user
+     * actually moves onto an item. A no-op once armed (cheap to call every move).
+     */
+    onArm?: () => void;
+    /**
+     * Called when the pointer enters the centre hub (cancel zone) — clears the
+     * component's highlight directly. Needed because closing a submenu from the
+     * hub leaves Base UI's root activeIndex pinned on the trigger (focus was in
+     * the band, so no root focusout fires), which `blurActive` alone can't reset.
+     */
+    onCancel?: () => void;
+}
+export interface AngleRouter {
+    /** Callback ref for the root SVG — attaches/detaches the global pointermove. */
+    attachRouter: (svg: SVGSVGElement | null) => void;
+    /** Root wedge hit-target elements, by item index (the JSX fills these). */
+    rootEls: React.MutableRefObject<(HTMLElement | null)[]>;
+    /** Open submenu child hit-target elements, by child index (the band fills these). */
+    subEls: React.MutableRefObject<(HTMLElement | null)[]>;
+}
+export declare function useAngleRouter(opts: AngleRouterOptions): AngleRouter;
+export {};

package/dist/modules/radialMenu/wiring/WedgeItem.d.ts

@@ -0,0 +1,46 @@
+import { MenuItem } from '../../../types';
+/** Props common to both wedge wrappers — the wedge's identity + hit geometry. */
+interface WedgeBase {
+    item: MenuItem;
+    /** The wedge's clip-path polygon (full-box coords). */
+    clip: string;
+    /** Mirror Base UI's `highlighted` for this wedge up to the component. */
+    onHi: (hi: boolean) => void;
+    /** Register this wedge's focusable element with the router. */
+    captureRef: (el: HTMLElement | null) => void;
+    /** Full-box side length (the foreignObject spans the whole root SVG box). */
+    box: number;
+}
+/**
+ * A LEAF wedge: a `ContextMenu.Item` rendered as a wedge-clipped hit-target.
+ * Selecting it fires `item.onSelect` and (unless `closeOnSelect === false`)
+ * closes the menu.
+ */
+export declare function WedgeItem({ item, clip, onHi, captureRef, box }: WedgeBase): import("react/jsx-runtime").JSX.Element;
+/**
+ * A SUBMENU wedge: the parent wedge is a `SubmenuTrigger`; its Popup hosts the
+ * band passed as `children` (the SubBand skin). The ANGLE-ROUTER owns open/close
+ * (dwell to open, leave-all/centre to close) via the controlled `open` prop, so:
+ * - opens are router-owned EXCEPT a genuine `trigger-press` (keyboard Enter/Space
+ *   or a real click), which we honour so keyboard can open the submenu;
+ * - closes honour only real dismiss/select reasons (`escape-key` /
+ *   `outside-press` / `item-press` / `close-press`), ignoring `sibling-open` and
+ *   hover/focus/list-nav — the router's synthetic `mousemove`s wake Base UI's
+ *   auto open/close, and `openSub` (the controlled prop) is the single source of
+ *   truth for which submenu is open.
+ * The trigger wedge stays highlighted while its submenu is open (`highlighted ||
+ * open`): focus moves into the band, so `highlighted` alone goes false and the
+ * indicator would wrongly drop off the trigger.
+ */
+export declare function WedgeSubmenu({ item, index, clip, onHi, captureRef, box, open, onOpen, onClose, children, }: WedgeBase & {
+    index: number;
+    /** Whether this submenu is open (controlled by the router via `openSub`). */
+    open: boolean;
+    /** A genuine press opened it (keyboard/click) — open this submenu. */
+    onOpen: (index: number) => void;
+    /** A genuine dismiss/select closed it. */
+    onClose: () => void;
+    /** The band skin (SubBand), composed into the submenu Popup. */
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/radial-menu.css

@@ -0,0 +1,152 @@
+/* @gregogun/radial-menu — default skin styles.
+ *
+ * Import ONCE in your app:  import "@gregogun/radial-menu/styles.css";
+ *
+ * Theming is driven entirely by the `--radial-*` CSS variables below. They are
+ * the Radix `slate` scale by default (so the menu looks good out of the box with
+ * zero config), but you can override any of them on a parent selector to retheme.
+ * The numbers mirror Radix's slate steps; their roles in the menu:
+ *   --radial-1   base / hub & gap discs        (Radix slate 1)
+ *   --radial-2   wedge fill (idle)             (Radix slate 2)
+ *   --radial-3   wedge fill (selected) + borders (Radix slate 3)
+ *   --radial-4   ring strokes                  (Radix slate 4)
+ *   --radial-11  icon color (idle) + indicator (Radix slate 11)
+ *   --radial-12  icon / label color (active)   (Radix slate 12)
+ *
+ * Dark mode applies automatically via `prefers-color-scheme`, AND under a
+ * `.dark` class (or `[data-theme="dark"]`) if you drive theme manually (e.g.
+ * next-themes). Override the vars yourself to opt out of either.
+ */
+
+:root {
+  --radial-1: #fcfcfd;
+  --radial-2: #f9f9fb;
+  --radial-3: #f0f0f3;
+  --radial-4: #e8e8ec;
+  --radial-11: #60646c;
+  --radial-12: #1c2024;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --radial-1: #111113;
+    --radial-2: #18191b;
+    --radial-3: #212225;
+    --radial-4: #272a2d;
+    --radial-11: #b0b4ba;
+    --radial-12: #edeef0;
+  }
+}
+
+/* Manual dark theming (class- or data-attribute-driven) wins over the media
+ * query so a forced light theme in a dark OS still works, and vice versa. */
+.dark,
+[data-theme="dark"] {
+  --radial-1: #111113;
+  --radial-2: #18191b;
+  --radial-3: #212225;
+  --radial-4: #272a2d;
+  --radial-11: #b0b4ba;
+  --radial-12: #edeef0;
+}
+
+/* --- Popups (root menu + submenu band) ----------------------------------- */
+/* Enter/exit are CSS transitions driven by Base UI's transition status. Base UI
+ * holds the unmount through the transition so the exit fade plays. */
+.radial-popup,
+.radial-band-popup {
+  transform-origin: center;
+  background: transparent;
+  outline: none;
+  transition: opacity 200ms ease-out, transform 200ms ease-out;
+}
+.radial-band-popup {
+  pointer-events: none;
+}
+.radial-popup[data-starting-style],
+.radial-popup[data-ending-style],
+.radial-band-popup[data-starting-style],
+.radial-band-popup[data-ending-style] {
+  opacity: 0;
+}
+.radial-popup[data-starting-style],
+.radial-band-popup[data-starting-style] {
+  transform: scale(0.6);
+}
+
+/* --- SVG surfaces --------------------------------------------------------- */
+.radial-svg,
+.radial-band-svg {
+  position: absolute;
+  inset: 0;
+  overflow: visible;
+}
+.radial-svg {
+  filter: drop-shadow(0 1px 2px rgb(0 0 0 / 0.08));
+}
+.radial-band-svg {
+  filter: drop-shadow(0 1px 1px rgb(0 0 0 / 0.06));
+}
+@media (prefers-color-scheme: dark) {
+  .radial-svg {
+    filter: drop-shadow(0 12px 24px rgb(0 0 0 / 0.55));
+  }
+  .radial-band-svg {
+    filter: drop-shadow(0 8px 16px rgb(0 0 0 / 0.5));
+  }
+}
+.dark .radial-svg,
+[data-theme="dark"] .radial-svg {
+  filter: drop-shadow(0 12px 24px rgb(0 0 0 / 0.55));
+}
+.dark .radial-band-svg,
+[data-theme="dark"] .radial-band-svg {
+  filter: drop-shadow(0 8px 16px rgb(0 0 0 / 0.5));
+}
+
+.radial-band-box {
+  position: relative;
+}
+
+/* --- Wedges / icons ------------------------------------------------------- */
+.radial-wedge {
+  transition: fill 150ms ease;
+}
+.radial-icon {
+  display: flex;
+  width: 100%;
+  height: 100%;
+  align-items: center;
+  justify-content: center;
+  user-select: none;
+  transition: color 200ms ease;
+}
+
+/* Focusable hit-target overlay (one per wedge): transparent, owns the pointer
+ * area, never visible. */
+.radial-hit {
+  position: absolute;
+  inset: 0;
+  opacity: 0;
+  outline: none;
+  pointer-events: auto;
+}
+
+.radial-label {
+  user-select: none;
+}
+
+/* foreignObject wrappers that only host visuals never take the pointer. */
+.radial-no-pointer {
+  pointer-events: none;
+}
+
+/* --- Reduced motion ------------------------------------------------------- */
+@media (prefers-reduced-motion: reduce) {
+  .radial-popup,
+  .radial-band-popup,
+  .radial-wedge,
+  .radial-icon {
+    transition: none;
+  }
+}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+import { ReactNode } from 'react';
+export interface MenuItem {
+    icon: ReactNode;
+    label: string;
+    submenu?: MenuItem[];
+    /**
+     * Fired when this leaf item is chosen (click / Enter / pointer-release on it).
+     * Items with a `submenu` open their children instead of selecting; only
+     * leaves call `onSelect`. The menu closes afterwards unless `closeOnSelect`
+     * is false.
+     */
+    onSelect?: () => void;
+    /** Keep the menu open after selecting this item (default: close). */
+    closeOnSelect?: boolean;
+}
+/**
+ * How wide each submenu segment is, relative to a base ring segment:
+ * - "halved": each child occupies half a base segment (so at most two children
+ *             fit in one base segment), spanning childCount / 2 base segments.
+ * - "full":   each child occupies a whole base segment, spanning childCount.
+ * Either way child 0 is anchored to the parent item's base segment.
+ */
+export type SubmenuLayout = "halved" | "full";
+/**
+ * Which way a submenu's children fan out from the parent item's base segment:
+ * "cw" extends into clockwise (increasing-angle) base segments, "ccw" into
+ * counter-clockwise ones. Child 0 stays anchored to the parent slice either way.
+ */
+export type SubsectionDirection = "cw" | "ccw";
+/**
+ * How the root menu is activated:
+ * - "fixed": always visible, centred in the viewport.
+ * - "area":  hidden until you press inside a defined area; the menu then opens
+ *            at the press point and tracks the cursor while held, closing on
+ *            release.
+ */
+export type RadialMode = "fixed" | "area";
+/** Tunable motion values for the submenu intro and selection indicator. */
+export interface MotionConfig {
+    /** How far (px) segments slide outward from on intro. */
+    introOutward: number;
+    /** Per-segment delay (s) for the intro stagger. */
+    introStagger: number;
+    /** Intro slide duration (s). */
+    introDuration: number;
+    /** Thickness (px) of the selection arc just beyond the band's outer edge. */
+    indicatorRim: number;
+    /** Gap (px) between the segment's outer edge and the selection arc. */
+    indicatorGap: number;
+    /** Selection-arc spring damping. */
+    indicatorDamping: number;
+    /** Selection-arc spring stiffness. */
+    indicatorStiffness: number;
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@gregogun/radial-menu",
+  "version": "0.1.0-alpha.0",
+  "description": "A radial (pie) context menu for React, built on Base UI — right-click / long-press or open programmatically, with angle-from-centre routing, nested submenus, and CSS-variable theming.",
+  "license": "MIT",
+  "author": "Greg Ogun",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/radial-menu.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "radial-menu",
+    "pie-menu",
+    "context-menu",
+    "base-ui",
+    "menu",
+    "svg"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "build:lib": "vite build --config vite.lib.config.ts",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "test:e2e": "playwright test",
+    "test:e2e:bench": "playwright test --project=bench"
+  },
+  "peerDependencies": {
+    "@base-ui/react": ">=1.5.0",
+    "motion": ">=12.0.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.11.3",
+    "@base-ui/react": "^1.5.0",
+    "@eslint/js": "^9.17.0",
+    "@playwright/test": "^1.60.0",
+    "@radix-ui/colors": "3.0.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint": "^9.17.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.16",
+    "globals": "^15.14.0",
+    "leva": "^0.10.1",
+    "motion": "12.0.5",
+    "next-themes": "^0.4.6",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-icons": "5.4.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "~5.6.2",
+    "typescript-eslint": "^8.18.2",
+    "vite": "^6.0.5",
+    "vite-plugin-dts": "^5.0.2"
+  }
+}