@deepseek-ai/dsh-client-ui-context-menu 0.0.0-stage → 0.2.2-alpha.3

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host Loader entry; menus belong to the Client. */
+/** Register the browser plugin without Host behavior. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/View.d.ts

@@ -0,0 +1,26 @@
+import type { MenuEntry } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { InjectFace, PropsStore, PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots';
+import type { Shortcuts, ShortcutCatalogEntry } from '@deepseek-ai/dsh-client-shortcuts/client';
+import type { createMenuStore } from './store.ts';
+import type { MenuActionView } from './types.ts';
+/**
+ * @param actions - plain presentation.
+ * @param catalog - effective user shortcuts.
+ * @param renderSlot - owner-authorized keyed icon renderer.
+ * @returns Existing Menu entries.
+ */
+export declare function menuEntries(actions: readonly MenuActionView[], catalog: readonly ShortcutCatalogEntry[], renderSlot: PropsRenderSlots<'contextMenu.icon'>['renderSlot']): MenuEntry[];
+/** Shared overlay callbacks. */
+export interface MenuOverlayInjected {
+    hooks: {
+        catalog: Shortcuts['catalog'];
+    };
+    close: () => void;
+    returnFocus?: () => HTMLElement | null;
+    select: (id: string) => void;
+}
+type Props = PropsStore<ReturnType<typeof createMenuStore>> & PropsRenderSlots<'contextMenu.content' | 'contextMenu.icon'> & InjectFace<MenuOverlayInjected>;
+/** @param props - registered state, target-specific legacy rows, and actions. @returns one menu and persistent feedback. */
+export declare function MenuOverlay({ useStore, actions, renderSlot, close, select, returnFocus, useCatalog }: Props): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=View.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,52 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ContextMenus, ContextMenuTarget, ContextMenuIcon, UseContextMenu } from './types.ts';
+export type { ContextMenus, ContextMenuTarget, ContextMenuTargetMap, MenuPoint, MenuAction, MenuActionView, MenuContribution, MenuResolution } from './types.ts';
+export type { ContextMenuBindings, ContextMenuTriggerProps, UseContextMenu } from './types.ts';
+export type { ContextMenuIcon } from './types.ts';
+export { createMenuStore } from './store.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        contextMenus: ContextMenus;
+    }
+}
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface GlobalStandardProps {
+        /** Menu bindings for explicit objects, available in every Slot scope. */
+        useContextMenu: UseContextMenu;
+    }
+    interface SlotMap {
+        /** Business-owned glyph or image selected by the action's icon key. */
+        'contextMenu.icon': {
+            kind: 'keyed';
+            scope: 'root';
+            inline: true;
+            owner: {
+                icon: ContextMenuIcon;
+            };
+        };
+        /** Optional React rows for existing extension positions; data contributions need no renderer. */
+        'contextMenu.content': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: {
+                target: ContextMenuTarget;
+                dismiss: () => void;
+            };
+        };
+    }
+    interface LocaleNamespaceMap {
+        contextMenu: 'failed';
+    }
+}
+/** Maximum time to prepare each contribution before omitting its pending actions. */
+export interface Config {
+    resolutionTimeoutMs?: number;
+}
+/** Validated Client menu preparation budget. */
+export declare const Config: z<Config>;
+/** Required overlay and localization services. */
+export declare const inject: string[];
+/** @param ctx - plugin-owned Client context. @param config - validated preparation budget. */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,28 @@
+/** Context-menu operation feedback, separate from plugin display metadata. */
+export declare const dictionaries: {
+    zh: {
+        failed: string;
+    };
+    en: {
+        failed: string;
+    };
+    ja: {
+        failed: string;
+    };
+    es: {
+        failed: string;
+    };
+    fr: {
+        failed: string;
+    };
+    de: {
+        failed: string;
+    };
+    ru: {
+        failed: string;
+    };
+    pt: {
+        failed: string;
+    };
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/registry.d.ts

@@ -0,0 +1,25 @@
+import type { MenuContribution, MenuResolution, ContextMenuTarget, ContextMenuTargetMap } from './types.ts';
+/** React-free registry; each occurrence captures the providers registered at opening. */
+export declare class MenuRegistry {
+    private readonly failed;
+    private readonly timeoutMs?;
+    private readonly providers;
+    private readonly occurrences;
+    private disposed;
+    constructor(failed: (message?: string) => void, timeoutMs?: number | undefined);
+    /**
+     * Register actions for subsequent openings.
+     * @param input - provider definition.
+     * @returns removal of this contribution and its pending resolutions.
+     */
+    register<K extends keyof ContextMenuTargetMap>(input: MenuContribution<K>): () => void;
+    /**
+     * Resolve an independently owned occurrence.
+     * @param target - captured clicked identity.
+     * @returns presentation, selection, and disposal.
+     */
+    resolve(target: ContextMenuTarget): MenuResolution;
+    /** Cancel every occurrence and reject further registrations or resolutions. */
+    dispose(): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/lib/types/client/store.d.ts

@@ -0,0 +1,35 @@
+/** Single-popup viewing state and feedback retained outside trigger components. */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-store';
+import type { MenuActionView, MenuPoint, ContextMenuTarget } from './types.ts';
+interface Notice {
+    id: number;
+    text: string;
+    success: boolean;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+interface MenuState {
+    occurrence: number;
+    closing: boolean;
+    replacing: boolean;
+    target: ContextMenuTarget | null;
+    point: MenuPoint;
+    items: readonly MenuActionView[];
+    notice: Notice | null;
+}
+type MenuActions = {
+    open(draft: MenuState, target: ContextMenuTarget, point: MenuPoint): void;
+    items(draft: MenuState, items: readonly MenuActionView[]): void;
+    exit(draft: MenuState, replacing: boolean): void;
+    close(draft: MenuState): void;
+    notify(draft: MenuState, notice: Notice | null): void;
+};
+/**
+ * Create the root popup store.
+ * @returns the presentation and its mutation actions.
+ */
+export declare function createMenuStore(): EngineStoreHandle<MenuState, MenuActions>;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/lib/types/client/target-key.d.ts

@@ -0,0 +1,9 @@
+/** Stable equality for the JSON-compatible target vocabulary, independent of object insertion order. */
+import type { ContextMenuTarget } from './types.ts';
+/**
+ * Compare captured JSON targets independently of object key insertion order.
+ * @param target - captured immutable target.
+ * @returns canonical JSON identity.
+ */
+export declare function menuTargetKey(target: ContextMenuTarget): string;
+//# sourceMappingURL=target-key.d.ts.map

package/lib/types/client/trigger.d.ts

@@ -0,0 +1,11 @@
+import type { ContextMenuTriggerProps, MenuPoint, ContextMenuTarget } from './types.ts';
+/**
+ * Create stable bindings for the plugin's injected hook.
+ * @param open - Open against the supplied captured target and viewport position.
+ * @param active - Whether the plugin still owns its service.
+ * @returns Ordinary trigger-prop factory; no React subscription or context is created.
+ */
+export declare function createContextMenuBindings<Target extends object = ContextMenuTarget>(open: (target: Target, point: MenuPoint) => void, active: () => boolean): {
+    getTriggerProps: (target: Target | (() => Target) | undefined, handlers?: ContextMenuTriggerProps) => ContextMenuTriggerProps;
+};
+//# sourceMappingURL=trigger.d.ts.map

package/lib/types/client/types.d.ts

@@ -0,0 +1,161 @@
+/** Client menu contributions and explicit gesture targets. */
+import type { ShortcutCommandId } from '@deepseek-ai/dsh-client-shortcuts/client';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { PaneId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit';
+import type { HTMLAttributes } from 'react';
+/** DOM handlers bound to an explicit object; existing handlers can prevent menu activation. */
+export type ContextMenuTriggerProps = Pick<HTMLAttributes<HTMLElement>, 'onContextMenu' | 'onKeyDown' | 'tabIndex'>;
+/** Functions supplied by the globally injected useContextMenu hook. */
+export interface ContextMenuBindings {
+    /**
+     * Bind an object or deferred business target to one element. This is an ordinary function, safe in loops.
+     * @param target - Object captured when the gesture runs; undefined retains native behavior.
+     * @param handlers - Existing handlers run first and can cancel with preventDefault().
+     * @returns Combined pointer and keyboard handlers plus a keyboard focus stop.
+     */
+    getTriggerProps: (target: ContextMenuTarget | (() => ContextMenuTarget) | undefined, handlers?: ContextMenuTriggerProps) => ContextMenuTriggerProps;
+}
+/** Read menu gesture bindings owned by the current menu plugin lifetime. */
+export type UseContextMenu = () => ContextMenuBindings;
+/** External plugins extend this map with their own target families. */
+export interface ContextMenuTargetMap {
+    session: {
+        readonly sessionId: SessionId;
+        readonly displayTitle: string;
+    };
+    file: {
+        readonly sessionId: SessionId;
+        readonly path: string;
+        readonly line?: number;
+        readonly paneId?: PaneId;
+    };
+    directory: {
+        readonly sessionId: SessionId;
+        readonly path: string;
+    };
+    url: {
+        readonly sessionId: SessionId;
+        readonly url: string;
+    };
+    image: {
+        readonly sessionId?: SessionId;
+        readonly url: string;
+        readonly name?: string;
+        readonly mediaType?: string;
+        readonly path?: string;
+    };
+    tab: {
+        readonly sessionId: SessionId;
+        readonly paneId: PaneId;
+        readonly tab: TabRecord;
+    };
+}
+/** Captured target; changing selection never changes an open menu's target. */
+export type ContextMenuTarget = {
+    [K in keyof ContextMenuTargetMap]: {
+        readonly kind: K;
+        readonly value: ContextMenuTargetMap[K];
+    };
+}[keyof ContextMenuTargetMap];
+/** Pointer position in CSS pixels; keyboard gestures use the trigger's bottom edge. */
+export interface MenuPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** Keyed icon renderer and optional image URL captured with the action. */
+export interface ContextMenuIcon {
+    readonly key: string;
+    readonly src?: string;
+}
+/** Client presentation fields; callbacks stay in the registry. */
+export interface MenuActionView {
+    readonly id: string;
+    readonly label: string;
+    /** Command identity for live shortcut display only; selection still invokes this action’s run callback. */
+    readonly commandId?: ShortcutCommandId;
+    readonly disabled?: boolean;
+    readonly icon?: ContextMenuIcon;
+    readonly danger?: boolean;
+    readonly separatorBefore?: boolean;
+    /** Render after legacy component contributions in the shared Web popup. */
+    readonly afterContent?: boolean;
+    readonly children?: readonly MenuActionView[];
+}
+/** A contribution can decline, return actions immediately, or resolve metadata asynchronously. */
+export interface MenuAction extends Omit<MenuActionView, 'children'> {
+    readonly children?: readonly MenuAction[];
+    /** Localized operation and recovery guidance when execution rejects. */
+    readonly failureLabel?: string;
+    /** Execute against the captured target. Reject for a visible failure; cancellation resolves normally. */
+    readonly run?: () => void | Promise<void>;
+}
+/** A namespaced contribution, ordered within its target family. */
+export interface MenuContribution<K extends keyof ContextMenuTargetMap> {
+    readonly id: string;
+    readonly target: K;
+    readonly order: number;
+    /**
+     * Reactive inputs that re-resolve actions for the same captured target.
+     * @param target - clicked object.
+     * @returns sources owned by the contributing feature; unsubscribed on dismissal or unload.
+     */
+    observe?(target: ContextMenuTargetMap[K]): readonly ObservableSnapshot<unknown>[];
+    /**
+     * @param target - clicked object.
+     * @param signal - aborted on dismissal, plugin unload, or a newer observed preparation.
+     * @returns available actions.
+     */
+    resolve(target: ContextMenuTargetMap[K], signal: AbortSignal): readonly MenuAction[] | Promise<readonly MenuAction[]>;
+}
+/** Independent menu occurrence used by custom renderers and embedded menus. */
+export interface MenuResolution {
+    /** Read a new immutable presentation after each provider settles, updates, or is withdrawn. */
+    readonly source: ObservableSnapshot<readonly MenuActionView[]>;
+    /** Settles when all opening contributions have completed or been withdrawn. */
+    readonly ready: Promise<void>;
+    /**
+     * Select once; disposed or removed contributions cannot execute.
+     * @param id - resolved action id.
+     */
+    select(id: string): void;
+    /** Cancel metadata queries and discard callbacks. */
+    dispose(): void;
+}
+/** Client capability used equally by built-in and external plugins. */
+export interface ContextMenus {
+    /** Captured target of the shared popup; null after dismissal. */
+    readonly active: ObservableSnapshot<ContextMenuTarget | null>;
+    /**
+     * Register for subsequent openings; unloading withdraws actions and aborts their queries. Duplicate ids within a target fail.
+     * @param contribution - target provider.
+     * @returns unregister.
+     */
+    register<K extends keyof ContextMenuTargetMap>(contribution: MenuContribution<K>): () => void;
+    /**
+     * Open the single shared popup.
+     * @param target - captured object.
+     * @param point - viewport position.
+     */
+    open(target: ContextMenuTarget, point: MenuPoint): void;
+    /**
+     * Resolve an embedded menu without opening the shared popup.
+     * @param target - captured object.
+     * @returns owned occurrence.
+     */
+    resolve(target: ContextMenuTarget): MenuResolution;
+    /** Close the shared popup and cancel its metadata queries. */
+    close(): void;
+    /**
+     * Show localized feedback outside the originating surface.
+     * @param text - localized message.
+     * @param success - successful action.
+     * @param action - optional text action retained by this notice; rejects with localized failure feedback.
+     */
+    notify(text: string, success?: boolean, action?: {
+        readonly label: string;
+        readonly run: () => void | Promise<void>;
+        readonly failureLabel: string;
+    }): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host Loader entry; menus belong to the Client. */
+/** Register the browser plugin without Host behavior. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/locale/de.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "Kontextmenüs"
+  }
+}

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "Context menus"
+  }
+}

package/locale/es.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "Menús contextuales"
+  }
+}

package/locale/fr.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "Menus contextuels"
+  }
+}

package/locale/ja.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "コンテキストメニュー"
+  }
+}

package/locale/pt.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "Menus de contexto"
+  }
+}

package/locale/ru.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "Контекстные меню"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "右键菜单"
+  }
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-context-menu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Typed, plugin-extensible context menus with captured targets and shared Web presentation",
+  "version": "0.2.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-context-menu"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-shortcuts"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "~3.18.6-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-store": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-brand": "0.2.2-alpha.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@deepseek-ai/dsh-client-test-runtime": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-dockkit": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-shortcuts": "0.2.2-alpha.3"
+  },
+  "files": [
+    "locale/*.json",
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }