# ContextMenu

A right-click menu container that wraps a `MenuList`.

## Usage

Wrap a `MenuList`.
```svelte
<ContextMenu {...props}>
  <MenuList {...props} />
</ContextMenu>
```

## Anatomy

The `class` attribute values represent part names. Other attributes represent their corresponding props.

```svelte
<div class="whole" {...rest} style={positioning}>
  {children}
</div>
```

Container for a descendant `MenuList`. ContextMenu provides `MenuContainerContext` and owns the contextmenu trigger, touch long-press fallback, fixed positioning, visibility, focus restore, Escape dismissal, and outside-click dismissal. Menu semantics, navigation, typeahead, data-mode, and item context live in `MenuList`.

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` | - | Usually renders a `MenuList`; menu semantics and navigation are owned by `MenuList` |
| `open` | `boolean` | `false` | Bindable open state; observable, not a positioning control |
| `lock` | `boolean` | `false` | Prevents the current open state from changing |
| `target` | `HTMLElement` | - | Limits the contextmenu trigger to a specific element; otherwise the document is used |
| `attach` | `Attachment` | - | Svelte attachment on the root menu |
| `element` | `HTMLDivElement` | - | Bindable root element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Menu variant |
Other `HTMLAttributes` are passed to `<div>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching.

### Default Class Name

`svs-context-menu`

## Behavior

Container for a descendant `MenuList`. ContextMenu provides `MenuContainerContext` and owns the contextmenu trigger, touch long-press fallback, fixed positioning, visibility, focus restore, Escape dismissal, and outside-click dismissal. Menu semantics, navigation, typeahead, data-mode, and item context live in `MenuList`.

When closed, the menu is hidden with `visibility` rather than unmounted; the `children` DOM, including the descendant `MenuList`, is always present in the document.

On touch input, a long press on the trigger opens the menu. Moving the finger past a small threshold before the press completes cancels the long-press open.

Touch targets that should avoid iOS's native selection callout should apply caller CSS such as `-webkit-touch-callout: none; user-select: none;` to the trigger element.

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `Escape` | Closes the open menu |
For item navigation and type-ahead, see [MenuList](/docs/menu-list).

Opening records the previously focused element. Closing the menu, including by outside click, restores focus to that element when it is still connected.

### ARIA Roles and Attributes

The component applies these automatically:

- ContextMenu does not add menu roles or menu ARIA attributes itself.

Menu semantics come from a descendant [MenuList](/docs/menu-list), including `role="menu"` on the menu body and `role="menuitem"` from `MenuItem`.

## Exports

### Types

```ts
interface ContextMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "style"> {
  children?: Snippet<[string]>; // Snippet<[variant]>; usually renders a MenuList
  open?: boolean; // bindable (false); to observe state, not to control
  lock?: boolean; // (false)
  target?: HTMLElement;
  attach?: Attachment<HTMLDivElement>;
  element?: HTMLDivElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // other HTMLAttributes are passed to <div> via ...rest; `class` is merged onto root
  // style is component-owned
}
type ContextMenuReqdProps = never;
type ContextMenuBindProps = "open" | "element";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=ContextMenuBasic.svelte
<script lang="ts">
  import { ContextMenu, MenuItem, MenuList } from "svseeds";

  let target: HTMLDivElement | undefined = $state();
  const styling = {
    whole: "rounded-md border bg-white p-1 shadow-lg select-none dark:bg-black",
  };
  const childStyle1 = {
    whole: "flex min-w-40 flex-col gap-1",
  };
  const childStyle2 = {
    whole:
      "rounded-sm px-2 py-1 text-left text-sm hover:bg-gray-100 focus-visible:bg-gray-100 focus:outline-hidden dark:hover:bg-gray-800 dark:focus-visible:bg-gray-800",
  };
</script>

<div bind:this={target} class="w-60 h-30 flex justify-center items-center rounded-md border-2 border-dashed text-xl select-none">
  Right click HERE
</div>

<ContextMenu {target} {styling}>
  <MenuList styling={childStyle1}>
    <MenuItem styling={childStyle2}>Profile</MenuItem>
    <MenuItem styling={childStyle2}>Settings</MenuItem>
    <MenuItem styling={childStyle2}>Sign out</MenuItem>
  </MenuList>
</ContextMenu>
```
### With Interactive Variant

**Code**

```svelte src=ContextMenuPract.svelte
<script lang="ts">
  import { ContextMenu, MenuItem, MenuList } from "svseeds";

  let { variant = $bindable() } = $props();
  let target: HTMLDivElement | undefined = $state();
  const variantStyle1 = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const variantStyle2 = {
    neutral: "hover:bg-gray-100 focus-visible:bg-gray-100 dark:hover:bg-gray-800 dark:focus-visible:bg-gray-800",
    active: "hover:bg-teal-100 focus-visible:bg-teal-100 dark:hover:bg-teal-900 dark:focus-visible:bg-teal-900",
    inactive: "hover:bg-red-100 focus-visible:bg-red-100 dark:hover:bg-red-900 dark:focus-visible:bg-red-900",
    blue: "hover:bg-blue-100 focus-visible:bg-blue-100 dark:hover:bg-blue-900 dark:focus-visible:bg-blue-900",
    yellow: "hover:bg-yellow-100 focus-visible:bg-yellow-100 dark:hover:bg-yellow-900 dark:focus-visible:bg-yellow-900",
    sky: "hover:bg-sky-100 focus-visible:bg-sky-100 dark:hover:bg-sky-900 dark:focus-visible:bg-sky-900",
  };
  const styling = {
    whole: {
      base: "rounded-md border bg-white p-1 shadow-lg select-none dark:bg-black",
      ...variantStyle1,
    },
  };
  const childStyle1 = {
    whole: "flex min-w-44 flex-col gap-1",
  };
  const childStyle2 = {
    whole: {
      base: "flex justify-between gap-8 rounded-sm px-2 py-1 text-left text-sm focus:outline-hidden",
      ...variantStyle2,
    },
  };
  const menu = [
    ["Cut", "Ctrl+X"],
    ["Copy", "Ctrl+C"],
    ["Paste", "Ctrl+V"],
  ];
</script>

<div
  bind:this={target}
  class="w-60 h-30 flex justify-center items-center rounded-md border-2 border-gray-500 text-gray-500 text-xl select-none"
>
  Right click HERE
</div>

<ContextMenu {variant} {target} {styling}>
  <MenuList styling={childStyle1}>
    {#each menu as [text, cmd]}
      <MenuItem styling={childStyle2}>
        <span>{text}</span>
        <kbd class="text-sm">{cmd}</kbd>
      </MenuItem>
    {/each}
  </MenuList>
</ContextMenu>
```