@ai-matrx/context-menu 0.0.0 → 0.1.1

package/dist/react.d.cts

@@ -0,0 +1,133 @@
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import './host-types-AOiEYwR8.cjs';
+import { ContextMenuV3Props, EditableContextMenuProps, NonEditableContextMenuProps, ContextMenuLayout } from '@ai-matrx/chat/context-menu/types';
+import { ContentSource } from '@ai-matrx/rich-content/rich-document/types';
+import { ClickTarget, ResolvedAction } from '@ai-matrx/alchemy/actions';
+import { M as MenuGrouping } from './grouping-CGcWsltu.cjs';
+export { a1 as ALL_DB_PLACEMENTS, a2 as AgentMenuCategoryGroup, a3 as AgentMenuEntry, a4 as BuildCategoryGroupsArgs, C as ContextMenuActions, a5 as DEFAULT_PLACEMENT_MODE, a6 as PLACEMENT_COLOR, a7 as PLACEMENT_LABEL_OVERRIDE, a8 as UseUnifiedAgentContextMenuArgs, a9 as UseUnifiedAgentContextMenuResult, aa as buildCategoryGroups, ab as getPlacementIcon, ac as getPlacementLabel, ad as groupsByPlacement, ae as hasItemsRecursive, af as resolveIcon, ag as resolveRichActionView, ah as useContextMenuActions, ai as useUnifiedAgentContextMenu } from './grouping-CGcWsltu.cjs';
+import { ItemContextMenuProps } from '@ai-matrx/chat/ui/item-types';
+import '@ai-matrx/icons';
+import 'lucide-react';
+import '@ai-matrx/chat/surfaces/types';
+import '@ai-matrx/chat/agents/redux/agent-shortcuts/skl-types';
+import '@ai-matrx/kit/confirm-opener';
+import '@ai-matrx/chat/agents/types/scope.types';
+import '@ai-matrx/chat/agents/redux/agent-shortcuts/types';
+import '@ai-matrx/chat/agents/redux/agent-shortcut-categories/types';
+import '@ai-matrx/chat/agents/redux/shared/scope';
+import '@ai-matrx/chat/surfaces/services/surface-bound-agents.service';
+import '@ai-matrx/chat/context-menu/utils/selection-tracking';
+import '@ai-matrx/kit/json-format';
+import '@ai-matrx/alchemy/menu';
+
+/**
+ * A gesture that reached this shell only through a React PORTAL: its target is
+ * not in the shell's DOM subtree (an open menu, a dialog or popover rendered by
+ * something inside the region). React bubbles portal events to every React
+ * ancestor, so a right-click — or a Mac two-finger tap mid-scroll — on an OPEN
+ * message menu reached the transcript's shell around it, which opened the page
+ * menu over it with both engines mounted: 18 `DuplicateActionError`s and "the
+ * menu swapped" (blind run PB-06, /chat, 2026-10-01). A portal surface that
+ * wants a menu mounts its own.
+ */
+declare function reachedThroughPortal(e: {
+    target: EventTarget | null;
+    currentTarget: EventTarget | null;
+}): boolean;
+/**
+ * Warm THAT SAME chunk once per tab, when the browser is idle after the first
+ * menu shell mounts — so the first right-click draws at once instead of
+ * fetching (and, in dev, compiling) the engine under the pointer (G11A review,
+ * 2026-10-07: the first open after a page load took 1–2 s). It is the same
+ * specifier as the `dynamic()` above, so it adds no chunk and no boundary
+ * (code-splitting rule 3); it only moves WHEN the browser fetches it. The
+ * menu still renders only on open.
+ */
+declare function warmMenuContent(): Promise<unknown>;
+declare function ContextMenuV3({ children, sourceFeature, surfaceName, menuVersion, getApplicationScope, contextData, resolveContextOnOpen, contentSource, entity, excludedRichActions, recordActionsOnly, subjectFold, extraRichActions, richDocCtxExtras, placementMode, extraSections, resolveExtraSectionsOnOpen, onUndo, onRedo, canUndo, canRedo, undoHint, redoHint, onViewHistory, hasHistory, scope, scopeId, className, menuLayout, menuDensity, suppressed, onMenuOpenChange, onCloseAutoFocus, isEditable, editorId, getTextarea, insertAtCaret, onContentInserted, onTextReplace, onTextInsertBefore, onTextInsertAfter, onSave, onDelete, }: ContextMenuV3Props): React__default.JSX.Element;
+
+declare function EditableContextMenu(props: EditableContextMenuProps): React.JSX.Element;
+
+declare function NonEditableContextMenu(props: NonEditableContextMenuProps): React.JSX.Element;
+
+type MenuProps = Parameters<typeof NonEditableContextMenu>[0];
+declare function PageSurfaceMenu({ sourceFeature, children, }: {
+    sourceFeature: MenuProps["sourceFeature"];
+    children: ReactNode;
+}): React.JSX.Element;
+
+declare const MenuPresenceProvider: React.Provider<boolean>;
+/**
+ * `true` when some ancestor already mounts a v3 menu.
+ *
+ * A shared primitive uses this to decide whether to provide its own floor:
+ *
+ * ```tsx
+ * const insideMenu = useIsInsideContextMenu();
+ * return insideMenu ? field : <EditableContextMenu …>{field}</EditableContextMenu>;
+ * ```
+ *
+ * Do NOT use it to change what a menu CONTAINS — only whether a primitive
+ * mounts one at all. Content decisions belong to the surface.
+ */
+declare function useIsInsideContextMenu(): boolean;
+declare const RegistryMenuSourceProvider: React.Provider<ContentSource | null>;
+declare function useRegistryMenuSource(): ContentSource | null;
+/** Two sources name the same content (type + every identifying id). */
+declare function sameContentSource(a: ContentSource | null | undefined, b: ContentSource | null | undefined): boolean;
+/**
+ * A content source's identity as one string (every identifying field, the
+ * read-only flag excluded). The shell stamps it on its trigger
+ * (`data-content-source`) so a ⋯ button can open the ONE menu that carries its
+ * content even when the button renders beside that content, not inside it.
+ */
+declare function contentSourceKey(s: ContentSource): string;
+
+interface MenuResolutionReport {
+    target: ClickTarget;
+    /** Exactly what the registry resolved for this open — before any grouping. */
+    resolved: readonly ResolvedAction[];
+    arrangement: ContextMenuLayout;
+}
+interface MenuRegroupValue {
+    /** null = draw the menu as it is today (report only). */
+    grouping: MenuGrouping | null;
+    mergeSameName: boolean;
+    /**
+     * Arrange the resolved rows with a function instead of a grouping (the proposed menu,
+     * `../proposed/proposed-arrangement.ts`). Wins over `grouping`.
+     */
+    transform?: ((target: ClickTarget, resolved: readonly ResolvedAction[]) => ResolvedAction[]) | undefined;
+    /** The menu's size and whether it draws its header line (the proposed menu: large, none). */
+    size?: "standard" | "large" | undefined;
+    hideHeader?: boolean | undefined;
+    /** Called on every resolve of this menu; `close` shuts the open menu. */
+    onResolved?: ((report: MenuResolutionReport, close: () => void) => void) | undefined;
+}
+declare const MenuRegroupContext: React.Context<MenuRegroupValue | null>;
+declare function MenuRegroupProvider({ value, children }: {
+    value: MenuRegroupValue;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Wraps the menu renderer; a pass-through unless a MenuRegroupContext is above it. */
+declare function RegroupBoundary({ arrangement, close, children, }: {
+    arrangement: ContextMenuLayout;
+    close: () => void;
+    children: React.ReactElement;
+}): React.ReactElement;
+
+declare function ItemMenuHostBinding({ children }: {
+    children: ReactNode;
+}): React.JSX.Element;
+
+declare function ItemContextMenuV3({ config, children, sourceFeature, surfaceName, entity, getApplicationScope, resolveItemOnOpen, onOpenChange, onCloseAutoFocus, }: ItemContextMenuProps): React.JSX.Element;
+
+declare function OpenSurfaceMenuButton({ getSurface, label, className, }: {
+    /** The element the surface's context-menu shell wraps. */
+    getSurface: () => HTMLElement | null;
+    label?: string | undefined;
+    className?: string | undefined;
+}): React.ReactElement;
+
+export { ContextMenuV3, EditableContextMenu, ItemContextMenuV3, ItemMenuHostBinding, MenuPresenceProvider, MenuRegroupContext, MenuRegroupProvider, type MenuRegroupValue, type MenuResolutionReport, NonEditableContextMenu, OpenSurfaceMenuButton, PageSurfaceMenu, RegistryMenuSourceProvider, RegroupBoundary, contentSourceKey, reachedThroughPortal, sameContentSource, useIsInsideContextMenu, useRegistryMenuSource, warmMenuContent };

package/dist/react.d.ts

@@ -0,0 +1,133 @@
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import './host-types-AOiEYwR8.js';
+import { ContextMenuV3Props, EditableContextMenuProps, NonEditableContextMenuProps, ContextMenuLayout } from '@ai-matrx/chat/context-menu/types';
+import { ContentSource } from '@ai-matrx/rich-content/rich-document/types';
+import { ClickTarget, ResolvedAction } from '@ai-matrx/alchemy/actions';
+import { M as MenuGrouping } from './grouping-CB3zlD1T.js';
+export { a1 as ALL_DB_PLACEMENTS, a2 as AgentMenuCategoryGroup, a3 as AgentMenuEntry, a4 as BuildCategoryGroupsArgs, C as ContextMenuActions, a5 as DEFAULT_PLACEMENT_MODE, a6 as PLACEMENT_COLOR, a7 as PLACEMENT_LABEL_OVERRIDE, a8 as UseUnifiedAgentContextMenuArgs, a9 as UseUnifiedAgentContextMenuResult, aa as buildCategoryGroups, ab as getPlacementIcon, ac as getPlacementLabel, ad as groupsByPlacement, ae as hasItemsRecursive, af as resolveIcon, ag as resolveRichActionView, ah as useContextMenuActions, ai as useUnifiedAgentContextMenu } from './grouping-CB3zlD1T.js';
+import { ItemContextMenuProps } from '@ai-matrx/chat/ui/item-types';
+import '@ai-matrx/icons';
+import 'lucide-react';
+import '@ai-matrx/chat/surfaces/types';
+import '@ai-matrx/chat/agents/redux/agent-shortcuts/skl-types';
+import '@ai-matrx/kit/confirm-opener';
+import '@ai-matrx/chat/agents/types/scope.types';
+import '@ai-matrx/chat/agents/redux/agent-shortcuts/types';
+import '@ai-matrx/chat/agents/redux/agent-shortcut-categories/types';
+import '@ai-matrx/chat/agents/redux/shared/scope';
+import '@ai-matrx/chat/surfaces/services/surface-bound-agents.service';
+import '@ai-matrx/chat/context-menu/utils/selection-tracking';
+import '@ai-matrx/kit/json-format';
+import '@ai-matrx/alchemy/menu';
+
+/**
+ * A gesture that reached this shell only through a React PORTAL: its target is
+ * not in the shell's DOM subtree (an open menu, a dialog or popover rendered by
+ * something inside the region). React bubbles portal events to every React
+ * ancestor, so a right-click — or a Mac two-finger tap mid-scroll — on an OPEN
+ * message menu reached the transcript's shell around it, which opened the page
+ * menu over it with both engines mounted: 18 `DuplicateActionError`s and "the
+ * menu swapped" (blind run PB-06, /chat, 2026-10-01). A portal surface that
+ * wants a menu mounts its own.
+ */
+declare function reachedThroughPortal(e: {
+    target: EventTarget | null;
+    currentTarget: EventTarget | null;
+}): boolean;
+/**
+ * Warm THAT SAME chunk once per tab, when the browser is idle after the first
+ * menu shell mounts — so the first right-click draws at once instead of
+ * fetching (and, in dev, compiling) the engine under the pointer (G11A review,
+ * 2026-10-07: the first open after a page load took 1–2 s). It is the same
+ * specifier as the `dynamic()` above, so it adds no chunk and no boundary
+ * (code-splitting rule 3); it only moves WHEN the browser fetches it. The
+ * menu still renders only on open.
+ */
+declare function warmMenuContent(): Promise<unknown>;
+declare function ContextMenuV3({ children, sourceFeature, surfaceName, menuVersion, getApplicationScope, contextData, resolveContextOnOpen, contentSource, entity, excludedRichActions, recordActionsOnly, subjectFold, extraRichActions, richDocCtxExtras, placementMode, extraSections, resolveExtraSectionsOnOpen, onUndo, onRedo, canUndo, canRedo, undoHint, redoHint, onViewHistory, hasHistory, scope, scopeId, className, menuLayout, menuDensity, suppressed, onMenuOpenChange, onCloseAutoFocus, isEditable, editorId, getTextarea, insertAtCaret, onContentInserted, onTextReplace, onTextInsertBefore, onTextInsertAfter, onSave, onDelete, }: ContextMenuV3Props): React__default.JSX.Element;
+
+declare function EditableContextMenu(props: EditableContextMenuProps): React.JSX.Element;
+
+declare function NonEditableContextMenu(props: NonEditableContextMenuProps): React.JSX.Element;
+
+type MenuProps = Parameters<typeof NonEditableContextMenu>[0];
+declare function PageSurfaceMenu({ sourceFeature, children, }: {
+    sourceFeature: MenuProps["sourceFeature"];
+    children: ReactNode;
+}): React.JSX.Element;
+
+declare const MenuPresenceProvider: React.Provider<boolean>;
+/**
+ * `true` when some ancestor already mounts a v3 menu.
+ *
+ * A shared primitive uses this to decide whether to provide its own floor:
+ *
+ * ```tsx
+ * const insideMenu = useIsInsideContextMenu();
+ * return insideMenu ? field : <EditableContextMenu …>{field}</EditableContextMenu>;
+ * ```
+ *
+ * Do NOT use it to change what a menu CONTAINS — only whether a primitive
+ * mounts one at all. Content decisions belong to the surface.
+ */
+declare function useIsInsideContextMenu(): boolean;
+declare const RegistryMenuSourceProvider: React.Provider<ContentSource | null>;
+declare function useRegistryMenuSource(): ContentSource | null;
+/** Two sources name the same content (type + every identifying id). */
+declare function sameContentSource(a: ContentSource | null | undefined, b: ContentSource | null | undefined): boolean;
+/**
+ * A content source's identity as one string (every identifying field, the
+ * read-only flag excluded). The shell stamps it on its trigger
+ * (`data-content-source`) so a ⋯ button can open the ONE menu that carries its
+ * content even when the button renders beside that content, not inside it.
+ */
+declare function contentSourceKey(s: ContentSource): string;
+
+interface MenuResolutionReport {
+    target: ClickTarget;
+    /** Exactly what the registry resolved for this open — before any grouping. */
+    resolved: readonly ResolvedAction[];
+    arrangement: ContextMenuLayout;
+}
+interface MenuRegroupValue {
+    /** null = draw the menu as it is today (report only). */
+    grouping: MenuGrouping | null;
+    mergeSameName: boolean;
+    /**
+     * Arrange the resolved rows with a function instead of a grouping (the proposed menu,
+     * `../proposed/proposed-arrangement.ts`). Wins over `grouping`.
+     */
+    transform?: ((target: ClickTarget, resolved: readonly ResolvedAction[]) => ResolvedAction[]) | undefined;
+    /** The menu's size and whether it draws its header line (the proposed menu: large, none). */
+    size?: "standard" | "large" | undefined;
+    hideHeader?: boolean | undefined;
+    /** Called on every resolve of this menu; `close` shuts the open menu. */
+    onResolved?: ((report: MenuResolutionReport, close: () => void) => void) | undefined;
+}
+declare const MenuRegroupContext: React.Context<MenuRegroupValue | null>;
+declare function MenuRegroupProvider({ value, children }: {
+    value: MenuRegroupValue;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Wraps the menu renderer; a pass-through unless a MenuRegroupContext is above it. */
+declare function RegroupBoundary({ arrangement, close, children, }: {
+    arrangement: ContextMenuLayout;
+    close: () => void;
+    children: React.ReactElement;
+}): React.ReactElement;
+
+declare function ItemMenuHostBinding({ children }: {
+    children: ReactNode;
+}): React.JSX.Element;
+
+declare function ItemContextMenuV3({ config, children, sourceFeature, surfaceName, entity, getApplicationScope, resolveItemOnOpen, onOpenChange, onCloseAutoFocus, }: ItemContextMenuProps): React.JSX.Element;
+
+declare function OpenSurfaceMenuButton({ getSurface, label, className, }: {
+    /** The element the surface's context-menu shell wraps. */
+    getSurface: () => HTMLElement | null;
+    label?: string | undefined;
+    className?: string | undefined;
+}): React.ReactElement;
+
+export { ContextMenuV3, EditableContextMenu, ItemContextMenuV3, ItemMenuHostBinding, MenuPresenceProvider, MenuRegroupContext, MenuRegroupProvider, type MenuRegroupValue, type MenuResolutionReport, NonEditableContextMenu, OpenSurfaceMenuButton, PageSurfaceMenu, RegistryMenuSourceProvider, RegroupBoundary, contentSourceKey, reachedThroughPortal, sameContentSource, useIsInsideContextMenu, useRegistryMenuSource, warmMenuContent };