@gregogun/radial-menu 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Ogun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @gregogun/radial-menu
+
+A radial (pie) context menu for React, built on [Base UI](https://base-ui.com).
+Right-click / long-press or open it programmatically. Angle-from-centre pointer
+routing, nested submenus, and CSS-variable theming with light/dark defaults.
+
+> **Alpha.** The API is settling but may still change before `1.0`.
+
+## Install
+
+```sh
+npm i @gregogun/radial-menu @base-ui/react motion
+```
+
+`react`, `react-dom`, `@base-ui/react`, and `motion` are **peer dependencies** —
+nothing is bundled. Base UI must be a single copy (it shares React context with
+the rest of your app), and keeping `motion` external preserves the lazy-loaded
+animation features.
+
+## Usage
+
+```tsx
+import { RadialMenu } from "@gregogun/radial-menu";
+import "@gregogun/radial-menu/styles.css";
+
+const items = [
+  { icon: <CopyIcon />, label: "Copy", onSelect: () => copy() },
+  { icon: <ReloadIcon />, label: "Reload", onSelect: () => reload() },
+  {
+    icon: <DownloadIcon />,
+    label: "Download",
+    submenu: [
+      { icon: <PdfIcon />, label: "Save as PDF", onSelect: () => savePdf() },
+      { icon: <ImgIcon />, label: "Save as image", onSelect: () => saveImg() },
+    ],
+  },
+];
+
+function Editor() {
+  return (
+    <RadialMenu.Root items={items}>
+      <RadialMenu.Trigger
+        render={(props) => <div {...props}>Right-click me</div>}
+      />
+    </RadialMenu.Root>
+  );
+}
+```
+
+Item order **is** placement: item 0 is the top wedge, the rest fan clockwise. A
+parent item carries a `submenu`; a leaf carries `onSelect`.
+
+## Programmatic / controlled open
+
+For games or external events (a network message, an NPC interaction, a keybind)
+you can open the menu with no pointer — and omit the `Trigger` entirely:
+
+```tsx
+import { useRef } from "react";
+import { RadialMenu, RadialMenuActions } from "@gregogun/radial-menu";
+
+function Game() {
+  const menu = useRef<RadialMenuActions>(null);
+
+  // later: menu.current?.open(clientX, clientY)
+  return <RadialMenu.Root items={items} actionsRef={menu} />;
+}
+```
+
+`actionsRef` exposes `{ open(x, y), openAtElement(el), close() }`. You can also
+drive visibility with the controlled `open` / `onOpenChange` props.
+
+## Props (`RadialMenu.Root`)
+
+| Prop               | Type                              | Default     | Description                                                      |
+| ------------------ | --------------------------------- | ----------- | -------------------------------------------------------------- |
+| `items`            | `MenuItem[]`                      | —           | The ordered radial items (order is placement).                  |
+| `size`             | `number`                          | `250`       | Diameter of the root ring, in px.                               |
+| `layout`           | `"halved" \| "full"`              | `"halved"`  | Submenu band layout (half a wedge per child, or a full wedge).  |
+| `direction`        | `"cw" \| "ccw"`                   | `"cw"`      | Submenu fan direction.                                          |
+| `submenuThickness` | `number`                          | `0.3`       | Submenu band thickness as a fraction of `size`.                 |
+| `ringGap`          | `number`                          | `8`         | Gap between the root rim and the submenu band, in px.           |
+| `openDelay`        | `number`                          | `280`       | Dwell (ms) before a hovered submenu-parent opens.               |
+| `open`             | `boolean`                         | —           | Controlled open state (pair with `onOpenChange`).               |
+| `defaultOpen`      | `boolean`                         | —           | Uncontrolled initial open state.                                |
+| `onOpenChange`     | `(open: boolean) => void`         | —           | Fired when the menu opens or closes.                            |
+| `actionsRef`       | `Ref<RadialMenuActions>`          | —           | Imperative handle: `open` / `openAtElement` / `close`.          |
+| `children`         | `ReactNode`                       | —           | A `RadialMenu.Trigger`. Optional for programmatic-only menus.   |
+
+### `MenuItem`
+
+| Field           | Type            | Description                                                       |
+| --------------- | --------------- | --------------------------------------------------------------- |
+| `icon`          | `ReactNode`     | Wedge icon.                                                      |
+| `label`         | `string`        | Accessible label for the wedge.                                  |
+| `submenu`       | `MenuItem[]`    | Children. Parents open their submenu instead of selecting.      |
+| `onSelect`      | `() => void`    | Fired when a leaf is chosen.                                     |
+| `closeOnSelect` | `boolean`       | Keep the menu open after selecting (default: close).            |
+
+## Theming
+
+The skin reads namespaced CSS variables (Radix slate values baked in as
+defaults). Override any of them to retheme:
+
+```css
+:root {
+  --radial-1: #fcfcfd; /* app / popup background */
+  --radial-2: #f9f9fb; /* wedge fill */
+  --radial-3: #f0f0f3; /* selected / border */
+  --radial-4: #e8e8ec; /* ring stroke */
+  --radial-11: #60646c; /* icon */
+  --radial-12: #1c2024; /* active icon */
+}
+```
+
+**Dark mode** ships out of the box: dark values apply under both
+`@media (prefers-color-scheme: dark)` and a `.dark` / `[data-theme="dark"]`
+selector, so it follows the system or an explicit class. Animations respect
+`prefers-reduced-motion`.
+
+## License
+
+MIT © Greg Ogun

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RadialMenu, RadialMenuRoot, RadialMenuTrigger, } from './modules/radialMenu/RadialMenu';
+export type { RadialMenuRootProps, RadialMenuTriggerProps, RadialMenuActions, } from './modules/radialMenu/RadialMenu';
+export type { MenuItem, SubmenuLayout, SubsectionDirection, } from './types';