@gtivr4/a1-design-system-react 0.12.0 → 0.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtivr4/a1-design-system-react",
-  "version": "0.12.0",
+  "version": "0.13.3",
   "description": "React components for the A1 token-driven design system.",
   "type": "module",
   "main": "./src/index.js",

package/src/components/accordion/Accordion.jsx

@@ -13,6 +13,7 @@ export function Accordion({
   size = "md",
   disabled = false,
   className = "",
+  ...rest
 }) {
   const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
   const isControlled = controlledOpen !== undefined;
@@ -48,6 +49,7 @@ export function Accordion({
         disabled && "a1-accordion--disabled",
         className,
       ].filter(Boolean).join(" ")}
+      {...rest}
     >
       <button
         id={triggerId}

package/src/components/banner/Banner.jsx

@@ -28,7 +28,9 @@ export function Banner({
   icon,
   action,
   onDismiss,
+  className = "",
   children,
+  ...rest
 }) {
   const resolvedVariant = VARIANTS.includes(variant) ? variant : "inline";
   const resolvedStatus  = STATUSES.includes(status)  ? status  : "neutral";
@@ -36,9 +38,10 @@ export function Banner({
 
   return (
     <div
-      className={`a1-banner a1-banner--${resolvedVariant} a1-banner--${resolvedStatus}`}
+      className={`a1-banner a1-banner--${resolvedVariant} a1-banner--${resolvedStatus}${className ? ` ${className}` : ""}`}
       role="alert"
       aria-live="polite"
+      {...rest}
     >
       <div className="a1-banner__inner">
         <span className="a1-banner__icon" aria-hidden="true">

package/src/components/blockquote/blockquote.css

@@ -80,8 +80,6 @@
 }
 
 .a1-blockquote--feature .a1-blockquote__cite {
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
   font-size: var(--semantic-font-size-body-xs);
   margin-top: var(--base-spacing-20);
 }

package/src/components/bottom-drawer/BottomDrawer.jsx

@@ -1,11 +1,11 @@
 import { Icon } from "../icon/Icon.jsx";
 import "./bottom-drawer.css";
 
-export function BottomDrawer({ items = [], "aria-label": ariaLabel = "Primary navigation", className = "" }) {
+export function BottomDrawer({ items = [], "aria-label": ariaLabel = "Primary navigation", className = "", ...rest }) {
   const visibleItems = items.slice(0, 5);
 
   return (
-    <nav className={["a1-bottom-drawer", className].filter(Boolean).join(" ")} aria-label={ariaLabel}>
+    <nav className={["a1-bottom-drawer", className].filter(Boolean).join(" ")} aria-label={ariaLabel} {...rest}>
       <ul className="a1-bottom-drawer__list" role="list">
         {visibleItems.map((item) => {
           const Tag = item.href ? "a" : "button";

package/src/components/button/Button.d.ts

@@ -11,6 +11,10 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
   icon?: string;
   /** Whether the icon appears before or after the label. Default: "start" */
   iconPosition?: "start" | "end";
+  /** Stretch the button to fill the width of its container. When false the button uses its natural content width. Default: false */
+  fullWidth?: boolean;
+  /** Show a loading spinner (replacing the icon) and make the button inert (disabled + aria-busy). Use while an action is in progress, e.g. submitting a form. Default: false */
+  loading?: boolean;
   children?: React.ReactNode;
 }
 

package/src/components/button/Button.jsx

@@ -11,35 +11,47 @@ export function Button({
   size = "md",
   icon,
   iconPosition = "start",
+  fullWidth = false,
+  loading = false,
   className = "",
   type,
+  disabled,
   children,
   ...props
 }) {
   const resolvedVariant = variants.includes(variant) ? variant : "primary";
   const resolvedSize = sizes.includes(size) ? size : "md";
   const resolvedPosition = iconPositions.includes(iconPosition) ? iconPosition : "start";
+  const isButton = Component === "button";
+  const isInert = disabled || loading;
   const classes = [
     "a1-button",
     `a1-button--${resolvedVariant}`,
     resolvedSize !== "md" && `a1-button--${resolvedSize}`,
     icon && "a1-button--has-icon",
+    fullWidth && "a1-button--full-width",
+    loading && "a1-button--loading",
     className
   ]
     .filter(Boolean)
     .join(" ");
 
   const iconEl = icon ? <Icon name={icon} className="a1-button__icon" /> : null;
+  // While loading, a spinner replaces the icon and the button becomes inert.
+  const spinnerEl = loading ? <span className="a1-button__spinner" aria-hidden="true" /> : null;
 
   return (
     <Component
       className={classes}
-      type={Component === "button" ? type ?? "button" : type}
+      type={isButton ? type ?? "button" : type}
+      disabled={isButton ? isInert || undefined : undefined}
+      aria-disabled={!isButton && isInert ? "true" : undefined}
+      aria-busy={loading ? "true" : undefined}
       {...props}
     >
-      {resolvedPosition === "start" && iconEl}
+      {loading ? spinnerEl : resolvedPosition === "start" && iconEl}
       {children}
-      {resolvedPosition === "end" && iconEl}
+      {!loading && resolvedPosition === "end" && iconEl}
     </Component>
   );
 }

package/src/components/button/button.css

@@ -62,6 +62,45 @@
   pointer-events: none;
 }
 
+/* Full-width: stretch to fill the container. Default buttons stay inline-flex
+   (natural content width). */
+.a1-button--full-width {
+  display: flex;
+  width: 100%;
+}
+
+/* Loading: the button is inert but reads as working (not disabled). A spinner
+   replaces the icon; full opacity distinguishes it from the disabled state. */
+.a1-button--loading {
+  cursor: progress;
+}
+
+.a1-button--loading:disabled,
+.a1-button--loading[aria-disabled="true"] {
+  opacity: 1;
+  pointer-events: none;
+}
+
+.a1-button__spinner {
+  inline-size: var(--component-button-icon-size);
+  block-size: var(--component-button-icon-size);
+  flex-shrink: 0;
+  border: var(--base-spacing-2) solid currentColor;
+  border-top-color: transparent;
+  border-radius: var(--base-radius-pill);
+  animation: a1-button-spin var(--semantic-motion-duration-slowest) linear infinite;
+}
+
+@keyframes a1-button-spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .a1-button__spinner {
+    animation-duration: calc(var(--semantic-motion-duration-slowest) * 3);
+  }
+}
+
 .a1-button--primary {
   --a1-button-background: var(--component-button-primary-background);
   --a1-button-background-hover: var(--component-button-primary-background-hover);

package/src/components/calendar/calendar.css

@@ -57,8 +57,6 @@
   color: var(--semantic-color-text-muted);
   text-align: center;
   padding-block: var(--component-calendar-cell-padding);
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
   border-block-end: 1px solid var(--semantic-color-border-subtle);
 }
 

package/src/components/card/card.css

@@ -1,6 +1,7 @@
 .a1-card {
   container: a1-card / inline-size;
   box-sizing: border-box;
+  inline-size: 100%;
   background: var(--semantic-color-surface-card);
   border: var(--component-card-border-width) solid var(--semantic-color-border-subtle);
   border-radius: var(--component-card-border-radius);

package/src/components/checkbox-group/CheckboxGroup.jsx

@@ -64,7 +64,7 @@ export function CheckboxGroup({
           <span className="a1-checkbox-group__legend-inner">
             {label}
             {required && resolvedSize === "comfortable" ? (
-              <MessageBadge status="info" subtle>{requiredText}</MessageBadge>
+              <MessageBadge status="info" subtle size="sm" icon={null}>{requiredText}</MessageBadge>
             ) : required ? (
               <span className="a1-field__asterisk" aria-hidden="true"> *</span>
             ) : null}

package/src/components/checkbox-group/checkbox-group.css

@@ -16,7 +16,7 @@
   --a1-cb-input-nudge:   var(--component-checkbox-group-input-nudge);     /* top margin aligning box center with label cap-height */
   --a1-cb-row-py:        var(--component-checkbox-group-row-padding-block);     /* vertical padding on each item row */
   --a1-cb-row-px:        var(--component-checkbox-group-row-padding-inline);     /* horizontal padding on each item row */
-  --a1-cb-legend-size:  var(--semantic-font-size-body-sm);
+  --a1-cb-legend-size:  var(--semantic-font-size-form-label-default);
   --a1-cb-label-size:   var(--semantic-font-size-body-md);
   --a1-cb-hint-size:    var(--semantic-font-size-body-xs);
   --a1-cb-msg-size:     var(--semantic-font-size-body-xs);
@@ -37,7 +37,7 @@
   --a1-cb-input-nudge:   var(--component-checkbox-group-comfortable-input-nudge);
   --a1-cb-row-py:        var(--component-checkbox-group-comfortable-row-padding-block);
   --a1-cb-row-px:        var(--component-checkbox-group-comfortable-row-padding-inline);
-  --a1-cb-legend-size: var(--semantic-font-size-body-md);
+  --a1-cb-legend-size: var(--semantic-font-size-form-label-comfortable);
   --a1-cb-label-size:  var(--semantic-font-size-body-md);
   --a1-cb-hint-size:   var(--semantic-font-size-body-sm);
   --a1-cb-msg-size:    var(--semantic-font-size-body-sm);
@@ -65,7 +65,7 @@
   --a1-cb-input-nudge:   var(--component-checkbox-group-compact-input-nudge);
   --a1-cb-row-py:        var(--component-checkbox-group-compact-row-padding-block);
   --a1-cb-row-px:        var(--component-checkbox-group-compact-row-padding-inline);
-  --a1-cb-legend-size: var(--semantic-font-size-body-xs);
+  --a1-cb-legend-size: var(--semantic-font-size-form-label-compact);
   --a1-cb-label-size:  var(--semantic-font-size-body-sm);
   --a1-cb-hint-size:   var(--semantic-font-size-body-xs);
   --a1-cb-msg-size:    var(--semantic-font-size-body-xs);

package/src/components/choice-group/ChoiceGroup.d.ts

@@ -11,7 +11,18 @@ export interface ChoiceOption {
   value: string;
   label: string;
   subtext?: string;
+  /** Material Symbols icon name. Mutually exclusive with swatch — swatch takes precedence. */
   icon?: string;
+  /**
+   * CSS color value rendered as a filled circle swatch instead of an icon.
+   * Accepts any CSS color including custom properties, e.g. "var(--semantic-color-action-background)".
+   */
+  swatch?: string;
+  /**
+   * Visually hide this tile's label/subtext, showing only the icon. The label
+   * is still rendered for screen readers. Requires `icon` to be set. Default: false
+   */
+  iconOnly?: boolean;
   disabled?: boolean;
 }
 
@@ -42,6 +53,18 @@ export interface ChoiceGroupProps {
    * above the content block. Has no effect on tiles with no icon. Default: false
    */
   inlineIcon?: boolean;
+  /**
+   * Hide the radio/checkbox selection indicator from all tiles. Selection state is
+   * still communicated via border, background, and the accessible input.
+   * Useful for compact configuration controls. Default: false
+   */
+  hideIndicator?: boolean;
+  /**
+   * Visually hide the label and subtext, showing only the icon. The label is still
+   * rendered in the DOM for screen readers. Requires each option to have both
+   * `icon` and `label`. Default: false
+   */
+  iconOnly?: boolean;
   required?: boolean;
   /** Input name attribute. Defaults to the group id. */
   name?: string;

package/src/components/choice-group/ChoiceGroup.jsx

@@ -13,19 +13,21 @@ export function ChoiceGroup({
   hint,
   error,
   success,
-  size        = "default",
+  size          = "default",
   columns,
-  multiple    = false,
-  inlineIcon  = false,
-  required    = false,
+  multiple      = false,
+  inlineIcon    = false,
+  hideIndicator = false,
+  iconOnly      = false,
+  required      = false,
   name,
-  options     = [],
+  options       = [],
   sections,
   value,
   defaultValue,
   onChange,
   id: providedId,
-  className   = "",
+  className     = "",
   ...props
 }) {
   const autoId = useId();
@@ -77,7 +79,9 @@ export function ChoiceGroup({
     "a1-choice-group",
     resolvedSize !== "default" && `a1-choice-group--${resolvedSize}`,
     multiple ? "a1-choice-group--multiple" : "a1-choice-group--single",
-    inlineIcon && "a1-choice-group--inline-icon",
+    inlineIcon    && "a1-choice-group--inline-icon",
+    hideIndicator && "a1-choice-group--no-indicator",
+    iconOnly      && "a1-choice-group--icon-only",
     isFixedColumns && "a1-choice-group--fixed-columns",
     responsiveClass,
     error   && "a1-choice-group--error",
@@ -105,7 +109,8 @@ export function ChoiceGroup({
         htmlFor={itemId}
         className={[
           "a1-choice-item",
-          isDisabled && "a1-choice-item--disabled",
+          isDisabled   && "a1-choice-item--disabled",
+          option.iconOnly && "a1-choice-item--icon-only",
         ].filter(Boolean).join(" ")}
       >
         <input
@@ -118,7 +123,14 @@ export function ChoiceGroup({
           disabled={isDisabled}
           onChange={(e) => handleChange(option.value, e.target.checked)}
         />
-        {option.icon && (
+        {option.swatch && (
+          <span
+            className="a1-choice-item__swatch"
+            aria-hidden="true"
+            style={{ "--a1-swatch-color": option.swatch }}
+          />
+        )}
+        {!option.swatch && option.icon && (
           <span className="a1-choice-item__icon" aria-hidden="true">
             <Icon name={option.icon} />
           </span>
@@ -160,7 +172,7 @@ export function ChoiceGroup({
             <span className="a1-choice-group__legend-inner">
               {label}
               {required && resolvedSize === "comfortable" ? (
-                <MessageBadge status="info" subtle>{requiredText}</MessageBadge>
+                <MessageBadge status="info" subtle size="sm" icon={null}>{requiredText}</MessageBadge>
               ) : required ? (
                 <span className="a1-field__asterisk" aria-hidden="true"> *</span>
               ) : null}

package/src/components/choice-group/choice-group.css

@@ -5,6 +5,8 @@
   margin: 0;
   padding: 0;
   min-width: 0;
+  inline-size: 100%; /* fill the container regardless of flex/grid/intrinsic sizing */
+  box-sizing: border-box;
 
   /* Tile size defaults (default) */
   --a1-cg-padding:             var(--component-choice-group-default-padding);
@@ -12,9 +14,9 @@
   --a1-cg-indicator-size:      var(--component-choice-group-default-indicator-size);
   --a1-cg-content-gap:         var(--component-choice-group-default-content-gap);
   --a1-cg-min-width:           var(--component-choice-group-default-min-width);
-  --a1-cg-label-size:          var(--semantic-font-size-body-md);
-  --a1-cg-subtext-size:        var(--semantic-font-size-body-sm);
-  --a1-cg-legend-size:         var(--semantic-font-size-body-sm);
+  --a1-cg-label-size:          var(--semantic-font-size-body-sm);
+  --a1-cg-subtext-size:        var(--semantic-font-size-body-xs);
+  --a1-cg-legend-size:         var(--semantic-font-size-form-label-default);
   --a1-cg-section-label-size:  var(--semantic-font-size-body-xs);
 
   /* Gap between tiles — tracks size */
@@ -37,9 +39,10 @@
   --a1-cg-indicator-size: var(--component-choice-group-compact-indicator-size);
   --a1-cg-content-gap:    var(--component-choice-group-compact-content-gap);
   --a1-cg-min-width:      var(--component-choice-group-compact-min-width);
-  --a1-cg-label-size:     var(--semantic-font-size-body-sm);
-  --a1-cg-subtext-size:   var(--semantic-font-size-body-xs);
-  --a1-cg-legend-size:    var(--semantic-font-size-body-xs);
+  /* Compact reduces label and subtext one step below the default size. */
+  --a1-cg-label-size:     var(--semantic-font-size-body-xs);
+  --a1-cg-subtext-size:   var(--semantic-font-size-body-2xs);
+  --a1-cg-legend-size:    var(--semantic-font-size-form-label-compact);
   --a1-cg-gap:            var(--component-choice-group-gap-sm);
   --a1-cg-group-gap:      var(--component-choice-group-compact-group-gap);
   --a1-cg-items-top-gap:  var(--component-choice-group-compact-items-top-gap);
@@ -53,7 +56,7 @@
   --a1-cg-min-width:           var(--component-choice-group-comfortable-min-width);
   --a1-cg-label-size:          var(--semantic-font-size-body-lg);
   --a1-cg-subtext-size:        var(--semantic-font-size-body-md);
-  --a1-cg-legend-size:         var(--semantic-font-size-body-md);
+  --a1-cg-legend-size:         var(--semantic-font-size-form-label-comfortable);
   --a1-cg-section-label-size:  var(--semantic-font-size-body-sm);
   --a1-cg-gap:                 var(--component-choice-group-gap-lg);
   --a1-cg-group-gap:           var(--component-choice-group-comfortable-group-gap);
@@ -138,7 +141,6 @@
   display: flex;
   flex-wrap: wrap;
   gap: var(--a1-cg-gap);
-  margin-top: var(--a1-cg-items-top-gap);
 }
 
 /* Fixed column count when --a1-cg-columns is set */
@@ -328,6 +330,49 @@
   flex-shrink: 0;
 }
 
+/* ─── No indicator ──────────────────────────────────────────────────────────── */
+
+.a1-choice-group--no-indicator .a1-choice-item {
+  padding-inline-start: var(--a1-cg-padding);
+}
+
+.a1-choice-group--no-indicator .a1-choice-item__indicator {
+  display: none;
+}
+
+/* ─── Icon only (group-level and per-option) ────────────────────────────────── */
+
+.a1-choice-group--icon-only .a1-choice-item,
+.a1-choice-item--icon-only {
+  align-items: center;
+  justify-content: center;
+}
+
+.a1-choice-group--icon-only .a1-choice-item__content,
+.a1-choice-item--icon-only .a1-choice-item__content {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* ─── Swatch ────────────────────────────────────────────────────────────────── */
+
+.a1-choice-item__swatch {
+  display: block;
+  width: var(--base-spacing-20);
+  height: var(--base-spacing-20);
+  border-radius: var(--base-radius-sm);
+  background-color: var(--a1-swatch-color, var(--semantic-color-text-default));
+  border: var(--base-spacing-1) solid var(--semantic-color-border-subtle);
+  flex-shrink: 0;
+}
+
 /* ─── Error state ───────────────────────────────────────────────────────────── */
 
 .a1-choice-group--error

package/src/components/code/Code.d.ts

@@ -9,6 +9,10 @@ export interface CodeProps extends React.HTMLAttributes<HTMLElement> {
   copyCode?: boolean;
   /** Text copied to the clipboard. Defaults to the rendered text children. */
   copyText?: string;
+  /** Render the block as an editable textarea initialized from children. Only meaningful in block mode. Default: false */
+  editable?: boolean;
+  /** Called with the current string value whenever the editable textarea changes. */
+  onChangeValue?: (value: string) => void;
   children?: React.ReactNode;
 }
 

package/src/components/code/Code.jsx

@@ -54,20 +54,34 @@ export function Code({
   wrapping = false,
   copyCode = false,
   copyText,
+  editable = false,
+  onChangeValue,
   className = "",
   children,
   ...props
 }) {
   const resolvedVariant = variants.includes(variant) ? variant : "inline";
   const [copied, setCopied] = useState(false);
+  const [editableValue, setEditableValue] = useState(() =>
+    textFromChildren(Children.toArray(children))
+  );
   const resetTimer = useRef(null);
+
+  // Keep the textarea in sync when children change from outside (e.g. undo/redo).
+  // React's Object.is bail-out means this is a no-op while the user is typing
+  // (children and editableValue are already equal after each keystroke).
+  useEffect(() => {
+    if (!editable) return;
+    setEditableValue(textFromChildren(Children.toArray(children)));
+  }, [children, editable]); // eslint-disable-line react-hooks/exhaustive-deps
+
   const copyLabel = useLabel("code.copyCode", "Copy code");
   const copiedLabel = useLabel("code.copied", "Copied");
   const textToCopy = useMemo(
-    () => copyText || textFromChildren(Children.toArray(children)),
-    [children, copyText],
+    () => copyText || (editable ? editableValue : textFromChildren(Children.toArray(children))),
+    [children, copyText, editable, editableValue],
   );
-  const shouldRenderBlock = resolvedVariant === "block" || copyCode;
+  const shouldRenderBlock = resolvedVariant === "block" || copyCode || editable;
 
   useEffect(() => {
     return () => {
@@ -75,6 +89,11 @@ export function Code({
     };
   }, []);
 
+  function handleTextareaChange(e) {
+    setEditableValue(e.target.value);
+    onChangeValue?.(e.target.value);
+  }
+
   async function handleCopy() {
     await writeClipboard(textToCopy);
     setCopied(true);
@@ -108,16 +127,33 @@ export function Code({
       className={[
         "a1-code-block",
         copyCode && "a1-code-block--copyable",
+        editable && "a1-code-block--editable",
         className,
       ]
         .filter(Boolean)
         .join(" ")}
     >
-      <pre className="a1-code-block__pre">
-        <code className={codeClasses} {...props}>
-          {children}
-        </code>
-      </pre>
+      {editable ? (
+        <textarea
+          className={[
+            "a1-code-block__textarea",
+            wrapping && "a1-code-block__textarea--wrapping",
+          ]
+            .filter(Boolean)
+            .join(" ")}
+          rows={10}
+          value={editableValue}
+          onChange={handleTextareaChange}
+          spellCheck={false}
+          {...props}
+        />
+      ) : (
+        <pre className="a1-code-block__pre">
+          <code className={codeClasses} {...props}>
+            {children}
+          </code>
+        </pre>
+      )}
       {copyCode && (
         <Button
           className="a1-code-block__copy"

package/src/components/code/code.css

@@ -55,6 +55,35 @@
   overflow-wrap: anywhere;
 }
 
+.a1-code-block__textarea {
+  box-sizing: border-box;
+  align-self: stretch;
+  inline-size: 100%;
+  margin: 0;
+  padding: var(--base-spacing-16);
+  border: var(--component-card-border-width) solid var(--semantic-color-border-subtle);
+  border-radius: var(--base-radius-md);
+  background: var(--semantic-color-surface-panel);
+  font-family: var(--component-inline-font-family-mono);
+  font-size: var(--component-inline-code-font-size);
+  line-height: 1.6;
+  color: var(--semantic-color-text-default);
+  white-space: pre;
+  overflow-x: auto;
+  resize: vertical;
+}
+
+.a1-code-block__textarea:focus-visible {
+  outline: none;
+  border-color: var(--semantic-color-action-background);
+  box-shadow: 0 0 0 var(--component-card-border-width) var(--semantic-color-action-background);
+}
+
+.a1-code-block__textarea--wrapping {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
 .a1-code-block__copy {
   margin: 0;
 }

package/src/components/context-menu/ContextMenu.d.ts

@@ -0,0 +1,56 @@
+import * as React from 'react';
+
+export interface ContextMenuItemEntry {
+  /** Default entry type — a clickable menu item. */
+  type?: 'item';
+  /** Unique identifier for this entry. */
+  id: string;
+  /** Display label. */
+  label: string;
+  /** Material Symbols icon name shown before the label. */
+  icon?: string;
+  /** Keyboard shortcut hint shown after the label (e.g. "⌦", "⌘Z"). */
+  shortcut?: string;
+  /** Visual variant. `destructive` uses error colors to signal a dangerous action. Default: "default" */
+  variant?: 'default' | 'destructive';
+  /** Highlights this item as the currently active/selected option. */
+  active?: boolean;
+  /** Prevents interaction. */
+  disabled?: boolean;
+  /** Called when the item is clicked. The menu closes automatically after. */
+  onClick?: () => void;
+}
+
+export interface ContextMenuDividerEntry {
+  type: 'divider';
+  id: string;
+}
+
+export interface ContextMenuGroupEntry {
+  type: 'group';
+  id: string;
+  /** Label shown as a non-interactive section heading. */
+  label: string;
+}
+
+export type ContextMenuEntry =
+  | ContextMenuItemEntry
+  | ContextMenuDividerEntry
+  | ContextMenuGroupEntry;
+
+export interface ContextMenuProps {
+  /** Controls visibility. Default: false */
+  open?: boolean;
+  /** Horizontal position in viewport pixels (typically event.clientX). */
+  x?: number;
+  /** Vertical position in viewport pixels (typically event.clientY). */
+  y?: number;
+  /** Menu entries — items, dividers, and group headings. */
+  items?: ContextMenuEntry[];
+  /** Called when the menu should close (outside click or Escape key). */
+  onClose?: () => void;
+  /** Accessible name for the menu. Default: "Context menu" */
+  'aria-label'?: string;
+}
+
+export declare function ContextMenu(props: ContextMenuProps): React.ReactElement | null;