torch-glare 2.5.6 → 2.6.0

package/docs/components/color-picker.md

@@ -1,101 +0,0 @@
----
-title: ColorPicker
-description: A full Figma-style color picker with a saturation/value area, hue and opacity sliders, an eyedropper, switchable HEX/RGB/HSL inputs, and preset swatches
-group: Forms
-keywords: [color-picker, color, palette, hex, rgb, hsl, hsv, opacity, alpha, eyedropper, swatch]
----
-
-# ColorPicker
-
-> A full Figma-style color palette opened from **a trigger you supply**: a draggable
-> saturation/value area, a hue slider, an optional opacity slider, an eyedropper (where the
-> browser supports it), switchable **HEX / RGB / HSL** numeric inputs, and preset swatches.
-> The value is always a hex string.
-
-## Installation
-
-```bash
-npx torch-glare@latest init
-npx torch-glare@latest add ColorPicker
-```
-
-`add` also copies its dependencies — `utils/color` (the pure hex/RGB/HSV/HSL math), plus the
-`Popover` and `Input` components.
-
-## Import
-
-```tsx
-import { ColorPicker } from "@/components/ColorPicker";
-```
-
-## Usage
-
-ColorPicker renders **no trigger of its own** — you pass one as its child (rendered via `asChild`,
-so it must forward ref/props to a DOM node). The current color is handed to that child based on
-what it is:
-
-| Child | Receives |
-|---|---|
-| an **input** — native `<input>`/`<textarea>`, or any element already given a `value` prop | the hex as **`value`** (plus an `onChange` that commits a typed hex, if you didn't supply one) |
-| **anything else** | the hex as **`children`** — unless it already has children, which are left untouched |
-
-```tsx
-const [color, setColor] = useState("#3B82F6");
-
-// input child → gets `value={color}`
-<ColorPicker value={color} onChange={setColor}>
-  <input className="…" />
-</ColorPicker>
-
-// non-input child → gets the hex as its content
-<ColorPicker value={color} onChange={setColor}>
-  <Button variant="BorderStyle" />
-</ColorPicker>
-
-// a child with its own content keeps it — render the value yourself
-<ColorPicker value={color} onChange={setColor}>
-  <button type="button">
-    <span style={{ backgroundColor: color }} />
-    {color}
-  </button>
-</ColorPicker>
-```
-
-With presets and opacity disabled (always emits `#rrggbb`):
-
-```tsx
-<ColorPicker
-  value={color}
-  onChange={setColor}
-  alpha={false}
-  presets={["#005ECC", "#047854", "#E30C30", "#F5A623"]}
->
-  <Button variant="BorderStyle" />
-</ColorPicker>
-```
-
-## Props
-
-| Prop        | Type                       | Default       | Description                                                                 |
-| ----------- | -------------------------- | ------------- | --------------------------------------------------------------------------- |
-| `children`  | `ReactElement`             | — (required)  | The trigger. Gets the hex as `value` if it's an input, else as `children`.   |
-| `value`     | `string`                   | `"#000000"`   | Current color as a hex string (`#rrggbb` or `#rrggbbaa`).                    |
-| `onChange`  | `(hex: string) => void`    | —             | Called on every change. Emits `#rrggbbaa` only when opacity < 100%.         |
-| `presets`   | `string[]`                 | —             | Quick-pick swatches shown at the bottom of the panel.                       |
-| `alpha`     | `boolean`                  | `true`        | Show the opacity slider + input and allow 8-digit output.                    |
-| `disabled`  | `boolean`                  | `false`       | Disable the trigger and all controls.                                       |
-| `theme`     | `"dark" \| "light" \| "default"` | —       | Applied as `data-theme`.                                                     |
-
-## Value format
-
-The value stays `#rrggbb` while fully opaque (backward-compatible with plain hex fields) and is
-promoted to `#rrggbbaa` only when opacity drops below 100%. Feeding a 3-, 6-, or 8-digit hex
-(with or without `#`) back in via `value` is always accepted.
-
-## Notes
-
-- The **eyedropper** button appears only where the native [`EyeDropper` API](https://developer.mozilla.org/docs/Web/API/EyeDropper)
-  is available (Chromium/Edge); it is hidden on Firefox/Safari.
-- Used by `FormBuilder.Color` — see [form-builder.md](./form-builder.md).
-- Color math lives in `utils/color` (`parseHex`, `formatHex`, `rgbToHsv`, `hsvToRgb`,
-  `rgbToHsl`, `hslToRgb`) and is reusable on its own.

package/docs/components/conclusion-header.md

@@ -1,80 +0,0 @@
----
-title: ConclusionHeader
-description: A clickable section header with a chevron toggle — white-alpha hover surfaces, chevron down when open and sideways when closed, and a "Disabled" badge when disabled. Direction-aware (LTR/RTL). Used for each FormSummary group title.
-component: true
-group: Layout & Containers
-keywords: [conclusion-header, collapsible, header, disclosure, accordion, toggle, chevron, expand, collapse, section]
----
-
-# ConclusionHeader
-
-A clickable **section header** that toggles a collapsible region, per the
-*Conclusion-Header-2.0* design. Its surfaces are **button overlays** (not an input field): at
-rest the label stands alone, and on hover it gains a `Button/ContStyle-Hover` pill while the
-chevron gains a `Button/Secondary` box. The chevron is hidden at rest while open, shows
-**sideways** when closed (left in LTR, right in RTL), and flips to **down** on hover. When
-`disabled` the label greys out, truncates at 120px, and a gray-subtle `Badge` replaces the
-chevron.
-
-It renders only the header — you own the collapsible body. It works **uncontrolled**
-(manages its own open state) or **controlled** (pass `open` + `onOpenChange`):
-
-```tsx
-// Uncontrolled — reflect the state with onOpenChange
-const [open, setOpen] = useState(true)
-
-<ConclusionHeader label="Invoice" defaultOpen onOpenChange={setOpen} />
-{open && <section>…body…</section>}
-
-// Controlled — you drive `open`
-<ConclusionHeader label="Invoice" open={open} onOpenChange={setOpen} />
-```
-
-## Installation
-
-```bash
-npx torch-glare@latest init
-npx torch-glare@latest add ConclusionHeader
-```
-
-## Imports
-
-```tsx
-import { ConclusionHeader } from '@/components/ConclusionHeader'
-```
-
-## Props
-
-| Prop | Type | Default | Notes |
-|---|---|---|---|
-| `label` | `ReactNode` | — | The header text. |
-| `open` | `boolean` | — | **Controlled** open state. Omit to let the header manage its own. |
-| `defaultOpen` | `boolean` | `true` | Initial open state when **uncontrolled**. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called with the next open state on click. |
-| `disabled` | `boolean` | `false` | Greys the label and shows a `Badge` instead of the chevron. |
-| `disabledLabel` | `string` | `"Disabled"` | Badge text when `disabled`. |
-| `theme` | `'dark' \| 'light' \| 'default'` | — | Theme override; otherwise inherits the nearest `data-theme`. |
-
-Extra props spread to the underlying `<button>`, which is what the header renders — so it is
-focusable, toggles on <kbd>Enter</kbd>/<kbd>Space</kbd>, and exposes `aria-expanded` for
-free. A `ref` is forwarded to that `HTMLButtonElement`.
-
-## Behaviour
-
-- **Open** (rest): label only — no surface, no chevron.
-- **Open hover**: `Button/ContStyle-Hover` pill (label inset 4px) + `Button/Secondary`
-  chevron box with a **down** chevron.
-- **Closed** (rest): label + a bare **sideways** chevron (`<` LTR / `>` RTL), no box.
-- **Closed hover**: same surfaces as open hover; the chevron flips to down.
-- **Disabled**: greyed label truncated at 120px + a `● Disabled` badge sitting beside it
-  (not at the row's end); not clickable.
-
-Direction is inherited from the ambient `dir` — the design's RTL variants are the LTR ones
-mirrored, which the component's logical properties produce automatically.
-
-## Composition
-
-Uses the design-system tokens directly (`Button/Secondary`, `Button/ContStyle-Hover`) rather
-than the input/button components, and reuses [Badge](./badge.md) for the disabled state.
-[FormSummary](./form-summary.md) uses it as each **group** title, so every group of totals
-collapses independently.

package/docs/components/context-menu.md

@@ -1,483 +0,0 @@
----
-title: ContextMenu
-description: Right-click (or long-press) menu that opens at the pointer, with submenus, checkboxes, radio groups, and keyboard navigation
-group: Overlays & Dialogs
-keywords: [context-menu, right-click, menu, radix-ui, submenu, checkbox, contextmenu]
----
-
-# ContextMenu
-
-> A right-click / long-press menu that opens at the pointer. Wrap any zone in a `ContextMenuTrigger` and the menu appears where the user clicks — same surface as DropdownMenu (items, groups, the boxed look, auto-grouping), built on `@radix-ui/react-context-menu`.
-
-## Installation
-
-TORCH Glare is a copy-in library: the CLI copies this component's source into your project
-(you do **not** install it from the npm package). Run `init` once, then `add`:
-
-```bash
-npx torch-glare@latest init
-npx torch-glare@latest add ContextMenu
-```
-
-`add` also copies any components, hooks, and utilities that `ContextMenu` depends on.
-
-## Import
-
-Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
-
-```tsx
-import { ContextMenu } from "@/components/ContextMenu";
-```
-
-## Quick Examples
-
-### Basic Menu
-
-Wrap the right-click zone in `ContextMenuTrigger`. The menu opens at the pointer.
-
-```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem } from "@/components/ContextMenu";
-
-function Example() {
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger asChild>
-        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
-          Right-click here
-        </div>
-      </ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuItem>Profile</ContextMenuItem>
-        <ContextMenuItem>Settings</ContextMenuItem>
-        <ContextMenuItem>Logout</ContextMenuItem>
-      </ContextMenuContent>
-    </ContextMenu>
-  )
-}
-```
-
-### With Icons, Shortcuts, and a Negative Item
-
-```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuShortcut } from "@/components/ContextMenu";
-
-function ActionsMenu() {
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger asChild>
-        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
-          Right-click the canvas
-        </div>
-      </ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuItem>
-          <i className="ri-edit-line" />
-          <span>Edit</span>
-          <ContextMenuShortcut>⌘E</ContextMenuShortcut>
-        </ContextMenuItem>
-        <ContextMenuItem>
-          <i className="ri-share-line" />
-          <span>Share</span>
-          <ContextMenuShortcut>⌘⇧S</ContextMenuShortcut>
-        </ContextMenuItem>
-        <ContextMenuItem variant="Negative">
-          <i className="ri-delete-bin-line" />
-          <span>Delete</span>
-          <ContextMenuShortcut>⌫</ContextMenuShortcut>
-        </ContextMenuItem>
-      </ContextMenuContent>
-    </ContextMenu>
-  )
-}
-```
-
-### With Checkboxes
-
-> Clicking a checkbox item keeps the menu open — `onSelect` calls `preventDefault()` internally so Radix does not auto-close. Toggle several options without the menu dismissing.
-
-```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuCheckboxItem } from "@/components/ContextMenu";
-import { useState } from 'react'
-
-function CheckboxMenu() {
-  const [showStatusBar, setShowStatusBar] = useState(true)
-  const [showActivityBar, setShowActivityBar] = useState(false)
-  const [showPanel, setShowPanel] = useState(false)
-
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger asChild>
-        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
-          Right-click to toggle view
-        </div>
-      </ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuCheckboxItem
-          checked={showStatusBar}
-          onCheckedChange={setShowStatusBar}
-        >
-          Status Bar
-        </ContextMenuCheckboxItem>
-        <ContextMenuCheckboxItem
-          checked={showActivityBar}
-          onCheckedChange={setShowActivityBar}
-        >
-          Activity Bar
-        </ContextMenuCheckboxItem>
-        <ContextMenuCheckboxItem
-          checked={showPanel}
-          onCheckedChange={setShowPanel}
-        >
-          Panel
-        </ContextMenuCheckboxItem>
-      </ContextMenuContent>
-    </ContextMenu>
-  )
-}
-```
-
-### With Radio Group
-
-> Like checkboxes, selecting a radio item keeps the menu open (`onSelect` `preventDefault` is built in).
-
-```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuRadioGroup, ContextMenuRadioItem } from "@/components/ContextMenu";
-import { useState } from 'react'
-
-function RadioMenu() {
-  const [position, setPosition] = useState('bottom')
-
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger asChild>
-        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
-          Right-click to pick a position
-        </div>
-      </ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuRadioGroup value={position} onValueChange={setPosition}>
-          <ContextMenuRadioItem value="top">Top</ContextMenuRadioItem>
-          <ContextMenuRadioItem value="bottom">Bottom</ContextMenuRadioItem>
-          <ContextMenuRadioItem value="right">Right</ContextMenuRadioItem>
-        </ContextMenuRadioGroup>
-      </ContextMenuContent>
-    </ContextMenu>
-  )
-}
-```
-
-### With Submenu
-
-```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent } from "@/components/ContextMenu";
-
-function SubmenuExample() {
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger asChild>
-        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
-          Right-click for more
-        </div>
-      </ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuItem>New Tab</ContextMenuItem>
-        <ContextMenuItem>New Window</ContextMenuItem>
-
-        <ContextMenuSub>
-          <ContextMenuSubTrigger>More Tools</ContextMenuSubTrigger>
-          <ContextMenuSubContent>
-            <ContextMenuItem>Developer Tools</ContextMenuItem>
-            <ContextMenuItem>Task Manager</ContextMenuItem>
-            <ContextMenuItem>Extensions</ContextMenuItem>
-          </ContextMenuSubContent>
-        </ContextMenuSub>
-
-        <ContextMenuItem>Print</ContextMenuItem>
-      </ContextMenuContent>
-    </ContextMenu>
-  )
-}
-```
-
-### RTL
-
-Set `dir="rtl"` on the Root and the menu, items, and submenu arrows mirror automatically.
-
-```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuShortcut } from "@/components/ContextMenu";
-
-function RtlMenu() {
-  return (
-    <ContextMenu dir="rtl">
-      <ContextMenuTrigger asChild>
-        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
-          انقر بزر الفأرة الأيمن
-        </div>
-      </ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuItem>
-          تحرير
-          <ContextMenuShortcut>⌘E</ContextMenuShortcut>
-        </ContextMenuItem>
-        <ContextMenuItem variant="Negative">حذف</ContextMenuItem>
-      </ContextMenuContent>
-    </ContextMenu>
-  )
-}
-```
-
-### Long Menu (max height + scroll)
-
-Tall menus scroll instead of overflowing off-screen. The surface caps at `maxHeight` (default `320`px) and never exceeds the space available after collision handling. Pass `maxHeight` to change the cap.
-
-The panel itself does not scroll — it clips, and an inner viewport inside it does the scrolling. That keeps the panel's 4px frosted gutter fixed instead of scrolling away with the rows. Submenus behave identically and take their own `maxHeight` (same `320`px default).
-
-```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLabel } from "@/components/ContextMenu";
-
-function LongMenu() {
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger asChild>
-        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
-          Right-click here
-        </div>
-      </ContextMenuTrigger>
-      {/* Cap the surface at 220px — the rest scrolls. */}
-      <ContextMenuContent maxHeight={220}>
-        <ContextMenuLabel>Jump to section</ContextMenuLabel>
-        {Array.from({ length: 20 }, (_, i) => (
-          <ContextMenuItem key={i}>Section {i + 1}</ContextMenuItem>
-        ))}
-      </ContextMenuContent>
-    </ContextMenu>
-  )
-}
-```
-
-## API Reference
-
-### ContextMenu (Root)
-
-A controlled wrapper around the Radix root. It tracks the open state internally (so a second right-click can dismiss the menu) while still forwarding `open` / `onOpenChange` when you control it.
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | - | Controlled open state |
-| `onOpenChange` | `(open: boolean) => void` | - | Callback when state changes |
-| `dir` | `'ltr' \| 'rtl'` | - | Reading direction; mirrors layout and arrows |
-| `modal` | `boolean` | `true` | Whether to block outside interactions |
-| `children` | `React.ReactNode` | - | Trigger and content |
-
-### ContextMenuTrigger
-
-The right-click zone. Wrap it around the element the menu should open from.
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `asChild` | `boolean` | `false` | Merge props onto the child element instead of rendering a wrapper |
-| `disabled` | `boolean` | `false` | Disables opening on right-click |
-
-### ContextMenuContent
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'PresentationStyle'` | `'PresentationStyle'` | Visual style variant |
-| `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant (applied as `data-theme`) |
-| `className` | `string` | - | Additional CSS classes |
-| `collisionPadding` | `number` | `8` | Min distance kept from the viewport edge |
-| `maxHeight` | `number` | `320` | Max height (px) of the surface before it scrolls. Capped at `min(maxHeight, available-height)` so the menu never overflows off-screen |
-| `autoGroup` | `boolean` | `true` | Auto-wrap loose items in a Boxed group (see Behavior notes) |
-
-### ContextMenuItem
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Item style variant |
-| `size` | `'S' \| 'M'` | `'M'` | Item size |
-| `inset` | `boolean` | `false` | Add left padding to align with items that have icons |
-| `active` | `boolean` | `false` | Active (selected) state |
-| `disabled` | `boolean` | `false` | Disabled state (still shows but is not selectable) |
-| `onSelect` | `(event: Event) => void` | - | Select handler; closes the menu by default |
-
-### ContextMenuCheckboxItem
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `checked` | `boolean \| 'indeterminate'` | `false` | Checked state |
-| `onCheckedChange` | `(checked: boolean) => void` | - | Change handler |
-| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Style variant |
-| `size` | `'S' \| 'M'` | `'M'` | Item size |
-
-> Selecting a checkbox item keeps the menu open — `onSelect` `preventDefault` is built in.
-
-### ContextMenuRadioGroup
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | - | Selected radio value |
-| `onValueChange` | `(value: string) => void` | - | Change handler |
-| `variant` | `'Boxed' \| 'Plain'` | `'Boxed'` | `Boxed` renders a bordered container; `Plain` is semantic grouping only |
-
-### ContextMenuRadioItem
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | Required | Radio option value |
-| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Style variant |
-| `size` | `'S' \| 'M'` | `'M'` | Item size |
-
-> Selecting a radio item keeps the menu open — `onSelect` `preventDefault` is built in.
-
-### ContextMenuSubTrigger
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Style variant |
-| `size` | `'S' \| 'M'` | `'M'` | Item size |
-| `inset` | `boolean` | `false` | Add left padding to align with items that have icons |
-| `className` | `string` | - | Additional CSS classes |
-
-Renders a trailing chevron (`ri-arrow-right-s-line`) that mirrors in RTL.
-
-### ContextMenuLabel
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `inset` | `boolean` | `false` | Add left padding to align with items that have icons |
-| `className` | `string` | - | Additional CSS classes |
-
-A non-interactive section heading. Acts as a boundary for auto-grouping.
-
-### ContextMenuShortcut
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | - | Additional CSS classes |
-
-A right-aligned (RTL-aware) span for keyboard hints inside an item.
-
-## TypeScript
-
-### Key Interfaces
-
-```typescript
-import * as ContextMenuPrimitive from '@radix-ui/react-context-menu'
-
-// Root — controlled wrapper
-type ContextMenuProps = React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.Root>
-// { open?, onOpenChange?, dir?, modal?, children, ... }
-
-export const ContextMenu: React.FC<ContextMenuProps>
-
-// Content
-interface ContextMenuContentProps {
-  variant?: 'PresentationStyle'
-  theme?: 'dark' | 'light' | 'default'
-  className?: string
-  collisionPadding?: number // default 8
-  maxHeight?: number         // default 320 — surface scrolls past this
-  autoGroup?: boolean        // default true
-}
-
-export const ContextMenuContent: React.ForwardRefExoticComponent<ContextMenuContentProps>
-
-// Item
-interface ContextMenuItemProps {
-  variant?: 'Default' | 'info' | 'Negative'
-  size?: 'S' | 'M'
-  active?: boolean
-  disabled?: boolean
-  onSelect?: (event: Event) => void
-}
-
-export const ContextMenuItem: React.ForwardRefExoticComponent<ContextMenuItemProps>
-
-// CheckboxItem
-interface ContextMenuCheckboxItemProps {
-  checked?: boolean | 'indeterminate'
-  onCheckedChange?: (checked: boolean) => void
-  variant?: 'Default' | 'info' | 'Negative'
-  size?: 'S' | 'M'
-}
-
-export const ContextMenuCheckboxItem: React.ForwardRefExoticComponent<ContextMenuCheckboxItemProps>
-
-// RadioGroup
-interface ContextMenuRadioGroupProps {
-  value?: string
-  onValueChange?: (value: string) => void
-  variant?: 'Boxed' | 'Plain'
-}
-
-export const ContextMenuRadioGroup: React.ForwardRefExoticComponent<ContextMenuRadioGroupProps>
-
-// RadioItem
-interface ContextMenuRadioItemProps {
-  value: string
-  variant?: 'Default' | 'info' | 'Negative'
-  size?: 'S' | 'M'
-}
-
-export const ContextMenuRadioItem: React.ForwardRefExoticComponent<ContextMenuRadioItemProps>
-```
-
-## Behavior Notes
-
-- **Opens at the pointer**: the menu opens on right-click (`contextmenu`) at the exact cursor position, not anchored to a fixed trigger button.
-- **Second right-click closes it**: the Root is made controlled and tracks `open` in context. The Trigger listens in the capture phase, and when the menu is already open it `preventDefault()` / `stopPropagation()` and closes — so a second right-click dismisses instead of re-anchoring (which Radix handles unreliably).
-- **Auto-grouping**: by default (`autoGroup` on `ContextMenuContent`, default `true`) consecutive loose items (`ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioItem`, and `ContextMenuSub`) are automatically wrapped in a `Boxed` `ContextMenuGroup`, so they render inside a boxed container like DropdownMenu even when you do not write a group. Labels and explicit groups act as boundaries and pass through unchanged. Set `autoGroup={false}` to render children verbatim.
-- **Max height & scrolling**: the surface caps its height at `min(maxHeight, available-height)` (where `maxHeight` defaults to `320`px and `available-height` is the space Radix has after collision handling). A taller menu scrolls vertically instead of overflowing off-screen — items and groups keep their full height rather than squishing. The panel clips and an inner viewport scrolls, so the panel's frosted gutter stays put. Pass `maxHeight={N}` to change the cap; `ContextMenuSubContent` accepts it too.
-- **Checkbox / radio keep the menu open**: `ContextMenuCheckboxItem` and `ContextMenuRadioItem` call `event.preventDefault()` inside `onSelect`, stopping Radix's default auto-close so users can toggle multiple options in one pass.
-- **Open-only animation**: only the open (enter) state animates (`fade-in`). There is intentionally no exit animation — holding the old DOM node during close breaks close/reposition on a second right-click, so it is omitted to keep repositioning reliable.
-- **Submenus and RTL**: nested `ContextMenuSub` / `ContextMenuSubTrigger` / `ContextMenuSubContent` are supported, and `dir="rtl"` on the Root mirrors the layout (including the submenu chevron).
-
-## Accessibility
-
-- **Keyboard Support**:
-  - Shift+F10 or the Menu (context) key: open the menu from the focused trigger
-  - Arrow Down / Arrow Up: move between items
-  - Arrow Right: open submenu (Arrow Left to close) — mirrored in RTL
-  - Enter / Space: select item
-  - Escape: close menu
-- **Touch**: long-press on the trigger opens the menu on touch devices.
-- **ARIA Attributes**: roles and states are applied automatically by Radix UI.
-- **Focus Management**: focus is trapped within the open menu and restored on close.
-- **Screen Readers**: menu structure, checked/selected states, and submenus are announced.
-
-## Best Practices
-
-1. **Use a clear right-click zone**
-   ```typescript
-   <ContextMenuTrigger asChild>
-     <div className="rounded-md border border-dashed">Right-click here</div>
-   </ContextMenuTrigger>
-   ```
-
-2. **Use labels to separate sections** — they also break auto-grouping into distinct boxed runs
-   ```typescript
-   <ContextMenuLabel>Edit</ContextMenuLabel>
-   ```
-
-3. **Show keyboard shortcuts**
-   ```typescript
-   <ContextMenuItem>
-     Save
-     <ContextMenuShortcut>⌘S</ContextMenuShortcut>
-   </ContextMenuItem>
-   ```
-
-4. **Use the Negative variant for destructive actions**
-   ```typescript
-   <ContextMenuItem variant="Negative">Delete</ContextMenuItem>
-   ```
-
-5. **Let checkbox/radio toggles stay open**: rely on the built-in behavior so users can adjust several settings without reopening.
-6. **Avoid deeply nested submenus**: 2 levels max.
-7. **Keep item labels concise**: short, action-oriented text.
-
-## Related Components
-
-- [DropdownMenu](./dropdown-menu.md) - Button-anchored menu
-- [Popover](./popover.md) - Non-menu popover
-- [Select](./select.md) - Form select field