frontend/latex: default vs new layout, document command type interface to clarify what is what, precedence, etc.

Author: haraldschilly

src/packages/frontend/frame-editors/frame-tree/commands/generic-commands.tsx

@@ -1320,6 +1320,39 @@ addCommands({
       defaultMessage: "Default",
     }),
   },
+  new_layout: {
+    icon: "layout",
+    group: "frame_types",
+    title: defineMessage({
+      id: "command.generic.new_layout.title",
+      defaultMessage:
+        "Switch to a simplified layout with LaTeX source editor and multi-purpose output panel",
+    }),
+    label: defineMessage({
+      id: "command.generic.new_layout.label",
+      defaultMessage: "New Layout",
+    }),
+    button: defineMessage({
+      id: "command.generic.new_layout.button",
+      defaultMessage: "New",
+    }),
+    isVisible: ({ props }) =>
+      typeof props.actions?._new_latex_frame_tree === "function",
+    onClick: ({ props }) => {
+      try {
+        // Check if this is a LaTeX editor and use its specific layout method
+        if (
+          props.actions._new_latex_frame_tree &&
+          props.actions.replace_frame_tree_with_custom
+        ) {
+          const tree = props.actions._new_latex_frame_tree();
+          props.actions.replace_frame_tree_with_custom(tree);
+        }
+      } catch (error) {
+        console.error("Error in New Layout:", error);
+      }
+    },
+  },
   button_bar: {
     alwaysShow: true,
     icon: "tool",

src/packages/frontend/frame-editors/frame-tree/commands/types.ts

@@ -6,67 +6,178 @@
 import type { ReactNode } from "react";
 
 import { IconName, IconRotation } from "@cocalc/frontend/components/icon";
+import { StudentProjectFunctionality } from "@cocalc/util/db-schema/projects";
 import { IntlMessage } from "@cocalc/frontend/i18n";
 import type { ManageCommands } from "./manage";
 import { MENUS } from "./menus";
 
+// Specification for a single menu in the frame title bar.
 interface MenuSpec {
+  // Display label for the menu. Can be translated text or special APPLICATION_MENU constant
   label: IntlMessage | string;
+
+  // Position for menu ordering. Lower numbers appear first
   pos: number;
+
+  // Array of group names that belong to this menu. Groups contain the actual commands.
   groups: string[];
 }
 
+/**
+ * Collection of all menu specifications. Menus are registered via addMenus()
+ * in generic-menus.ts and define the top-level dropdown structure in frame title bars.
+ * Examples: "file", "edit", "view", "go", "help", "app"
+ */
 export interface Menus {
   [name: string]: MenuSpec;
 }
 
 export type Group = (typeof MENUS)[keyof typeof MENUS]["groups"][number];
 
+/**
+ * Function signature for command click handlers. Receives the ManageCommands
+ * instance (providing access to frame context, props, etc.) and an optional
+ * event object from the UI interaction.
+ */
 export type OnClick = (opts: ManageCommands & { event? }) => void;
 
+/**
+ * Configuration options for Ant Design Popconfirm modal dialogs.
+ * Used to show confirmation prompts before executing potentially destructive commands.
+ * All fields support internationalization via IntlMessage.
+ */
 interface PopconfirmOpts {
+  // Main title text shown at the top of the confirmation dialog
   title?: string | IntlMessage | React.JSX.Element;
+  // Detailed description explaining the action and its consequences
   description?: string | IntlMessage | React.JSX.Element;
+  // Text for the confirmation button (defaults to "OK")
   okText?: string | IntlMessage;
+  // Text for the cancel button (defaults to "Cancel")
   cancelText?: string | IntlMessage;
 }
 
+/**
+ * Defines a command that can appear in frame editor menus, toolbars, and buttons.
+ * For example, split frame, zoom, save, etc.
+ *
+ * Commands are organized into menus via groups.
+ * Each editor (LaTeX, code, etc.) can include specific commands in their EditorDescription.commands.
+ *
+ * The ManageCommands class handles visibility, rendering, and execution of commands
+ * based on the current frame context, user permissions, and editor specifications.
+ */
 export interface Command {
-  // group -- inside of a menu
+  /**
+   * The menu group this command belongs to.
+   * Commands are organized into groups for logical menu structure.
+   */
   group: Group;
-  name?: string; //not used
-  // position, for sorting
+
+  /**
+   * Used in menu construction helpers (e.g., addEditorMenus) to identify
+   * commands within the menu system. Not used in the final Command objects
+   * that get registered, which are identified by their key in the commands object.
+   */
+  name?: string;
+
+  /**
+   * Position within the group for sorting. Lower numbers appear first.
+   * Used by ManageCommands.getAllCommandPositions() to determine display order
+   * in menus and toolbars. Defaults to 1e6 (very high) if not specified.
+   */
   pos?: number;
+
+  // Tooltip text shown when hovering over the command
   title?: ReactNode | ((opts: ManageCommands) => ReactNode) | IntlMessage;
+
+  // Icon to display for this command.
   icon?: IconName | ReactNode | ((opts: ManageCommands) => ReactNode);
+
+  // Rotation angle for the icon in degrees. Only applies when icon is an IconName.
   iconRotate?: IconRotation;
+
+  // Label for button bar buttons. Separate from 'label' to allow different text in menus vs. compact button bar.
   button?: ReactNode | ((opts: ManageCommands) => ReactNode) | IntlMessage;
+
+  // unclear?
   //color?: string | ((opts: ManageCommands) => string);
+
+  // Primary label for the command in menus.
   label?: ReactNode | ((opts: ManageCommands) => ReactNode) | IntlMessage;
-  // If onClick is NOT set, then editor_actions[name] must be defined
-  // and be a function that takes the frame id as input.
+
+  /**
+   * Click handler for the command. If not provided, the system falls back to
+   * calling props.actions[name](props.id) where 'name' is the command key.
+   * Receives ManageCommands context plus an optional 'event' parameter.
+   */
   onClick?: OnClick;
-  // isVisible: if a function, determine visibility based on that.
-  //            if a string, use editor spec for given frame.
+
+  /**
+   * Controls command visibility.
+   * Used to conditionally show commands based on frame type, file type, etc.
+   * Can be a string (references another command name in the editor spec) or a function
+   * NOTE: Completely ignored if alwaysShow is true
+   */
   isVisible?: string | (({ props }) => boolean);
-  disable?: string;
+
+  /**
+   * Disables the command when the specified student project functionality
+   * is disabled. References keys in studentProjectFunctionality object.
+   * Used in educational contexts to restrict certain features.
+   */
+  disable?: keyof StudentProjectFunctionality;
+
+  /**
+   * Keyboard shortcut display. Shown in menu items on desktop (not mobile).
+   * Should match actual keyboard shortcuts defined elsewhere in the app.
+   */
   keyboard?: ReactNode;
+
+  // Sub-commands that appear as a submenu.
   children?:
     | Partial<Command>[]
     | ((opts: ManageCommands) => Partial<Command>[]);
+
+  // if this returns true, the command should be disabled (grayed out) but still visible
   disabled?: (opts: ManageCommands) => boolean;
-  // not used yet
+
+  // for interactive tours -- not used yet
   tour?: string;
+
   // do modal popconfirm first -- takes options to antd
   // Popconfirm, or a function that returns Popconfirm options.
   // See frontend/app/popconfirm-modal.tsx for subtleties.
   popconfirm?:
     | PopconfirmOpts
     | ((opts: ManageCommands) => PopconfirmOpts | undefined);
-  // if true, never show this on mobile
+
+  /**
+   * If true, this command is never shown on mobile devices.
+   * Used for commands that don't work well on touch interfaces or
+   * are not needed in mobile contexts.
+   */
   neverVisibleOnMobile?: boolean;
-  // if true, always show this (unless neverVisibleOnMobile set, obviously).
+
+  /**
+   * If true, forces the command to always be visible, overriding all other
+   * visibility checks including isVisible functions and editor spec requirements.
+   * Used for essential commands like frame controls that should always be available.
+   * Takes precedence over neverVisibleOnMobile.
+   */
   alwaysShow?: boolean;
+
+  /**
+   * If true, keeps dropdown menus open after clicking this command.
+   * Used for commands that don't navigate away or change context,
+   * allowing multiple selections (e.g., zoom level changes).
+   */
   stayOpenOnClick?: boolean;
+
+  /**
+   * Additional search terms for the command search functionality.
+   * Used by the search_commands feature to find commands beyond their
+   * title, label, and name. Improves discoverability.
+   */
   search?: string;
 }

src/packages/frontend/frame-editors/latex-editor/actions.ts

@@ -1,4 +1,4 @@
-/*
+ /*
  *  This file is part of CoCalc: Copyright © 2020 Sagemath, Inc.
  *  License: MS-RSL – see LICENSE.md for details
  */
@@ -635,6 +635,51 @@ export class Actions extends BaseActions<LatexEditorState> {
     }
   }
 
+  _new_latex_frame_tree(): FrameTree {
+    if (this.is_public) {
+      return { type: "cm" };
+    } else {
+      return {
+        type: "node",
+        direction: "col",
+        first: { type: "cm" },
+        second: { type: "output" },
+        pos: 0.5,
+      };
+    }
+  }
+
+  // Method to replace the entire frame tree with a custom tree structure
+  replace_frame_tree_with_custom(customTree: FrameTree): void {
+    let local = this.store.get("local_view_state");
+
+    // Process the custom tree: assign IDs and ensure uniqueness
+    let frame_tree = fromJS(customTree) as Map<string, any>;
+    frame_tree = tree_ops.assign_ids(frame_tree);
+    frame_tree = tree_ops.ensure_ids_are_unique(frame_tree);
+
+    // Set the frame tree to the custom tree
+    local = local.set("frame_tree", frame_tree);
+
+    // Also make some id active, since existing active_id is no longer valid
+    local = local.set("active_id", tree_ops.get_some_leaf_id(frame_tree));
+
+    // Update state, so visible to UI
+    this.setState({ local_view_state: local });
+
+    // And save this new state to localStorage
+    this.save_local_view_state();
+
+    // Emit new-frame events for all leaf nodes
+    for (const id in this._get_leaf_ids()) {
+      const leaf = this._get_frame_node(id);
+      if (leaf != null) {
+        const type = leaf.get("type");
+        this.store.emit("new-frame", { id, type });
+      }
+    }
+  }
+
   check_for_fatal_error(): void {
     const build_logs: BuildLogs = this.store.get("build_logs");
     if (!build_logs) return;