Command Metadata

/**
 * Get the description for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The description for the command
 */
describedBy(id: string, args?: ReadonlyPartialJSONObject): Promise<CommandRegistry.Description>;

type Description = { args: ReadonlyJSONObject | null };

/**
 * Get the display label for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The display label for the command, or an empty string if the command is not registered
 */
label(id: string, args?: ReadonlyPartialJSONObject): string;

/**
 * Get the mnemonic index for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The mnemonic index for the command, or -1 if the command is not registered
 */
mnemonic(id: string, args?: ReadonlyPartialJSONObject): number;

/**
 * Get the short form caption for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The caption for the command, or an empty string if the command is not registered
 */
caption(id: string, args?: ReadonlyPartialJSONObject): string;

/**
 * Get the usage help text for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The usage text for the command, or an empty string if the command is not registered
 */
usage(id: string, args?: ReadonlyPartialJSONObject): string;

/**
 * Get the icon renderer for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The icon renderer for the command or undefined
 */
icon(id: string, args?: ReadonlyPartialJSONObject): VirtualElement.IRenderer | undefined;

/**
 * Get the icon class for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The icon class for the command, or an empty string if the command is not registered
 */
iconClass(id: string, args?: ReadonlyPartialJSONObject): string;

/**
 * Get the icon label for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The icon label for the command, or an empty string if the command is not registered
 */
iconLabel(id: string, args?: ReadonlyPartialJSONObject): string;

/**
 * Get the extra class name for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The class name for the command, or an empty string if the command is not registered
 */
className(id: string, args?: ReadonlyPartialJSONObject): string;

/**
 * Get the dataset for a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns The dataset for the command, or an empty dataset if the command is not registered
 */
dataset(id: string, args?: ReadonlyPartialJSONObject): CommandRegistry.Dataset;

/**
 * Test whether a specific command is enabled.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns A boolean indicating whether the command is enabled, or false if the command is not registered
 */
isEnabled(id: string, args?: ReadonlyPartialJSONObject): boolean;

/**
 * Test whether a specific command is toggled.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns A boolean indicating whether the command is toggled, or false if the command is not registered
 */
isToggled(id: string, args?: ReadonlyPartialJSONObject): boolean;

/**
 * Test whether a specific command is toggleable.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns A boolean indicating whether the command is toggleable, or false if the command is not registered
 */
isToggleable(id: string, args?: ReadonlyJSONObject): boolean;

/**
 * Test whether a specific command is visible.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns A boolean indicating whether the command is visible, or false if the command is not registered
 */
isVisible(id: string, args?: ReadonlyPartialJSONObject): boolean;

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

// Command with dynamic label based on context
registry.addCommand("open-file", {
  execute: (args) => {
    console.log(`Opening ${args.filename}`);
  },
  label: (args) => {
    return args.filename ? `Open ${args.filename}` : "Open File";
  },
  caption: (args) => {
    return args.filename ? `Open the file: ${args.filename}` : "Open a file";
  }
});

// Get labels with different arguments
console.log(registry.label("open-file")); // "Open File"
console.log(registry.label("open-file", { filename: "document.txt" })); // "Open document.txt"
console.log(registry.caption("open-file", { filename: "document.txt" })); // "Open the file: document.txt"

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

// Icon renderer object
const saveIconRenderer = {
  render: (host: HTMLElement) => {
    const icon = document.createElement("i");
    icon.className = "fa fa-save";
    host.appendChild(icon);
  }
};

registry.addCommand("save", {
  execute: () => console.log("Saving..."),
  label: "Save",
  icon: saveIconRenderer,
  iconClass: "save-icon",
  iconLabel: "💾" // Emoji fallback
});

// Get icon information
const iconRenderer = registry.icon("save");
const iconClass = registry.iconClass("save"); // "save-icon"
const iconLabel = registry.iconLabel("save"); // "💾"

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();
let isPlaying = false;

registry.addCommand("play-pause", {
  execute: () => {
    isPlaying = !isPlaying;
    registry.notifyCommandChanged("play-pause");
  },
  label: () => isPlaying ? "Pause" : "Play",
  iconClass: () => isPlaying ? "fa fa-pause" : "fa fa-play",
  className: () => isPlaying ? "active playing" : "inactive",
  isToggled: () => isPlaying,
  isToggleable: true
});

// Check current state
console.log(registry.label("play-pause")); // "Play"
console.log(registry.iconClass("play-pause")); // "fa fa-play"
console.log(registry.isToggled("play-pause")); // false
console.log(registry.isToggleable("play-pause")); // true

// Execute to change state
await registry.execute("play-pause");

console.log(registry.label("play-pause")); // "Pause"
console.log(registry.iconClass("play-pause")); // "fa fa-pause"
console.log(registry.isToggled("play-pause")); // true

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

registry.addCommand("format-text", {
  execute: (args) => {
    console.log(`Formatting as ${args.format}`);
  },
  label: (args) => {
    const format = args.format || "default";
    return `Format as ${format.toUpperCase()}`;
  },
  iconClass: (args) => {
    switch (args.format) {
      case "bold": return "fa fa-bold";
      case "italic": return "fa fa-italic";
      case "underline": return "fa fa-underline";
      default: return "fa fa-font";
    }
  },
  isEnabled: (args) => Boolean(args.selectedText),
  dataset: (args) => ({
    "format-type": args.format || "default",
    "has-selection": args.selectedText ? "true" : "false"
  })
});

// Get metadata with different contexts
const boldContext = { format: "bold", selectedText: "Hello World" };
console.log(registry.label("format-text", boldContext)); // "Format as BOLD"
console.log(registry.iconClass("format-text", boldContext)); // "fa fa-bold"
console.log(registry.isEnabled("format-text", boldContext)); // true
console.log(registry.dataset("format-text", boldContext)); // { "format-type": "bold", "has-selection": "true" }

const noSelectionContext = { format: "bold" };
console.log(registry.isEnabled("format-text", noSelectionContext)); // false

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

registry.addCommand("file-menu", {
  execute: () => console.log("Opening file menu"),
  label: "File",
  mnemonic: 0, // 'F' is at index 0
  caption: "File operations menu"
});

registry.addCommand("edit-menu", {
  execute: () => console.log("Opening edit menu"),
  label: "Edit",
  mnemonic: 0, // 'E' is at index 0
  caption: "Edit operations menu"
});

// Get mnemonic indices for keyboard navigation
console.log(registry.mnemonic("file-menu")); // 0
console.log(registry.mnemonic("edit-menu")); // 0

// Dynamic mnemonic based on context
registry.addCommand("save-as", {
  execute: (args) => console.log("Save as:", args.filename),
  label: (args) => args.filename ? `Save as ${args.filename}` : "Save As...",
  mnemonic: (args) => args.filename ? 8 : 5, // 'A' in "Save As..." or 'a' in filename
});

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

// Complex command with rich metadata
registry.addCommand("document-action", {
  execute: async (args) => {
    console.log(`Performing ${args.action} on document ${args.docId}`);
    return { success: true, action: args.action };
  },
  
  describedBy: (args) => ({
    args: {
      type: "object",
      properties: {
        action: { type: "string", enum: ["save", "export", "print"] },
        docId: { type: "string" },
        format: { type: "string", optional: true }
      }
    }
  }),
  
  label: (args) => {
    const action = args.action || "action";
    const docName = args.docName || `Document ${args.docId || ""}`.trim();
    return `${action.charAt(0).toUpperCase() + action.slice(1)} ${docName}`;
  },
  
  caption: (args) => {
    return `${args.action || "Perform action on"} the current document`;
  },
  
  usage: () => "document-action --action=<save|export|print> --docId=<id> [--format=<format>]",
  
  iconClass: (args) => {
    switch (args.action) {
      case "save": return "fa fa-save";
      case "export": return "fa fa-download";
      case "print": return "fa fa-print";
      default: return "fa fa-file";
    }
  },
  
  className: (args) => {
    const classes = ["document-action"];
    if (args.action) classes.push(`action-${args.action}`);
    if (args.urgent) classes.push("urgent");
    return classes.join(" ");
  },
  
  dataset: (args) => ({
    "action": args.action || "",
    "doc-id": args.docId || "",
    "format": args.format || "",
    "timestamp": Date.now().toString()
  }),
  
  isEnabled: (args) => Boolean(args.docId && args.action),
  isVisible: (args) => Boolean(args.hasPermission),
  isToggled: (args) => args.action === "save" && args.autoSave,
  isToggleable: true
});

// Use the comprehensive metadata
const context = {
  action: "export",
  docId: "doc123",
  docName: "Annual Report", 
  format: "pdf",
  hasPermission: true,
  urgent: true
};

console.log(registry.label("document-action", context)); // "Export Annual Report"
console.log(registry.caption("document-action", context)); // "export the current document"
console.log(registry.iconClass("document-action", context)); // "fa fa-download"
console.log(registry.className("document-action", context)); // "document-action action-export urgent"
console.log(registry.isEnabled("document-action", context)); // true
console.log(registry.isVisible("document-action", context)); // true

const description = await registry.describedBy("document-action", context);
console.log(description); // { args: { type: "object", properties: { ... } } }

type Dataset = { readonly [key: string]: string };
type Description = { args: ReadonlyJSONObject | null };
type CommandFunc<T> = (args: ReadonlyPartialJSONObject) => T;