@casualoffice/sheets 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casualoffice/sheets",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Casual Sheets SDK — signing pipeline, iframe postMessage protocol, and CasualSheets React wrapper around Univer.",
   "type": "module",
   "license": "Apache-2.0",

package/src/chrome/MenuBar.feature-gate.unit.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Unit tests for the MenuBar feature-gating contract — specifically the
+ * embed-mode gates that let a host hide the editor's branding surfaces:
+ *
+ *   features={{ help: false }}     → the whole Help menu is dropped.
+ *   features={{ branding: false }} → the "View on GitHub" + "About" links are
+ *                                    dropped (from both Help and File), so an
+ *                                    embedded sheet shows no editor branding,
+ *                                    while Keyboard shortcuts stays in Help.
+ *
+ * Exercises the pure `computeVisibleMenus` resolver (no DOM needed). The
+ * `MENUS` array itself lives in `MenuBar.tsx`, which statically imports
+ * `@univerjs/core` values the vendored ESM can't expose as named exports to
+ * node's loader — so it can't be imported here. Instead this pins the resolver
+ * against a fixture that mirrors the real Help/File branding subtree (kept in
+ * sync with MenuBar.tsx: Help menu `feature: 'help'`; About + View-on-GitHub +
+ * their separator `feature: 'branding'`; File > About `feature: 'branding'`).
+ *
+ * Run with: `pnpm test:unit`
+ */
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import { computeVisibleMenus, type MenuDef } from './menu-model';
+
+// A faithful copy of the branding-relevant subtree of `MENUS` in MenuBar.tsx.
+const MENUS_FIXTURE: MenuDef[] = [
+  {
+    id: 'file',
+    label: 'File',
+    feature: 'file',
+    items: [
+      { kind: 'item', id: 'properties', label: 'Properties…', dialog: 'properties' },
+      {
+        kind: 'item',
+        id: 'about',
+        label: 'About casual sheets',
+        dialog: 'about',
+        feature: 'branding',
+      },
+    ],
+  },
+  {
+    id: 'help',
+    label: 'Help',
+    feature: 'help',
+    items: [
+      {
+        kind: 'item',
+        id: 'keyboard-shortcuts',
+        label: 'Keyboard shortcuts',
+        dialog: 'keyboard-shortcuts',
+      },
+      { kind: 'separator', id: 'sep-help', feature: 'branding' },
+      {
+        kind: 'item',
+        id: 'about',
+        label: 'About casual sheets',
+        dialog: 'about',
+        feature: 'branding',
+      },
+      {
+        kind: 'item',
+        id: 'github',
+        label: 'View on GitHub',
+        run: () => {},
+        feature: 'branding',
+      },
+    ],
+  },
+];
+
+// All SDK-built-in dialogs openable — matches standalone chrome (the SDK ships
+// the About / Keyboard-shortcuts modals), so branding items are not
+// latent-dropped and the feature gate is the only thing that can hide them.
+const canOpenAll = () => true;
+
+function findMenu(menus: MenuDef[], id: string) {
+  return menus.find((m) => m.id === id);
+}
+
+function itemIds(items: { id: string }[]): string[] {
+  return items.map((i) => i.id);
+}
+
+test('default (features unset): Help menu, About and View-on-GitHub all render', () => {
+  const menus = computeVisibleMenus(MENUS_FIXTURE, {}, canOpenAll);
+  const help = findMenu(menus, 'help');
+  assert.ok(help, 'Help menu should render by default');
+  const ids = itemIds(help.items);
+  assert.ok(ids.includes('github'), 'View on GitHub should render by default');
+  assert.ok(ids.includes('about'), 'Help > About should render by default');
+  assert.ok(ids.includes('keyboard-shortcuts'), 'Keyboard shortcuts should render');
+
+  const file = findMenu(menus, 'file');
+  assert.ok(file, 'File menu should render by default');
+  assert.ok(itemIds(file.items).includes('about'), 'File > About should render by default');
+});
+
+test('features={{ help: false }}: the whole Help menu is dropped', () => {
+  const menus = computeVisibleMenus(MENUS_FIXTURE, { help: false }, canOpenAll);
+  assert.equal(findMenu(menus, 'help'), undefined, 'Help menu must not render when help:false');
+  // File menu is unaffected by the help gate.
+  assert.ok(findMenu(menus, 'file'), 'File menu still renders when only help is disabled');
+});
+
+test('features={{ branding: false }}: GitHub + About vanish, Help stays for shortcuts', () => {
+  const menus = computeVisibleMenus(MENUS_FIXTURE, { branding: false }, canOpenAll);
+
+  const help = findMenu(menus, 'help');
+  assert.ok(help, 'Help menu still renders (keyboard shortcuts is not branding)');
+  const helpIds = itemIds(help.items);
+  assert.ok(!helpIds.includes('github'), 'View on GitHub must be hidden when branding:false');
+  assert.ok(!helpIds.includes('about'), 'Help > About must be hidden when branding:false');
+  assert.ok(helpIds.includes('keyboard-shortcuts'), 'Keyboard shortcuts stays');
+  // Trailing separator before the (now removed) branding items must be collapsed.
+  assert.ok(!helpIds.includes('sep-help'), 'dangling separator collapses once branding items go');
+
+  const file = findMenu(menus, 'file');
+  assert.ok(file, 'File menu still renders');
+  assert.ok(
+    !itemIds(file.items).includes('about'),
+    'File > About must be hidden when branding:false',
+  );
+});
+
+test('features={{ help: false, branding: false }}: no editor-branded surface at all', () => {
+  const menus = computeVisibleMenus(MENUS_FIXTURE, { help: false, branding: false }, canOpenAll);
+  assert.equal(findMenu(menus, 'help'), undefined, 'Help menu gone');
+  const file = findMenu(menus, 'file');
+  assert.ok(file && !itemIds(file.items).includes('about'), 'File > About gone');
+  // No visible menu anywhere links to GitHub.
+  for (const m of menus) {
+    assert.ok(!itemIds(m.items).includes('github'), `menu ${m.id} has no GitHub link`);
+  }
+});

package/src/chrome/MenuBar.tsx

@@ -54,52 +54,24 @@ import type { CasualSheetsAPI } from '../sheets/api';
 import { ensurePluginByName } from '../univer';
 import { Icon } from './Icon';
 import { ensureChromeFonts } from './fonts';
-import { useDialogs, type DialogKind } from './dialog-context';
-import type { ChromeExtensions, MenuExtension } from './extensions';
-
-type MenuId = 'file' | 'edit' | 'view' | 'insert' | 'format' | 'data' | 'help';
+import { useDialogs } from './dialog-context';
+import type { ChromeExtensions } from './extensions';
+import {
+  computeVisibleMenus,
+  type MenuDef,
+  type MenuId,
+  type MenuItemDef,
+  type RunFn,
+} from './menu-model';
+
+export type { MenuDialogKind } from './menu-model';
 
 /**
- * Dialog kinds the host can choose to render via `onDialogRequest`. These are
- * the actions the SDK chrome can't fulfil on its own (no built-in modal). The
- * string is passed straight to the host hook; the `context` (when present)
- * carries the pre-resolved A1 selection so the host doesn't have to re-read it.
+ * The menu data model + pure gating engine live in `./menu-model` (univer-free,
+ * so unit-testable). `RunFn` / `MenuItemDef` / `MenuDef` / `MenuId` /
+ * `MenuDialogKind` are re-imported above; the `run` handlers that populate
+ * `MENUS` are defined inline below against the `@univerjs/core` facade.
  */
-export type MenuDialogKind = DialogKind;
-
-type RunFn = (api: CasualSheetsAPI) => void;
-
-type MenuItemDef =
-  | {
-      kind: 'item';
-      id: string;
-      label: string;
-      icon?: string;
-      shortcut?: string;
-      /** Dispatch a command / facade call directly. */
-      run?: RunFn;
-      /** Route through the host's `onDialogRequest`. Omitted if no host hook. */
-      dialog?: MenuDialogKind;
-      /** Feature gate — item hidden when `features[feature] === false`. */
-      feature?: string;
-    }
-  | { kind: 'separator'; id: string; feature?: string }
-  | {
-      kind: 'submenu';
-      id: string;
-      label: string;
-      icon?: string;
-      items: MenuItemDef[];
-      feature?: string;
-    };
-
-interface MenuDef {
-  id: MenuId;
-  label: string;
-  /** Feature gate for the whole menu. */
-  feature?: string;
-  items: MenuItemDef[];
-}
 
 /**
  * Pretty-print a `Ctrl+Shift+X` shortcut for the current platform. The SDK
@@ -559,6 +531,7 @@ const MENUS: MenuDef[] = [
         label: 'About casual sheets',
         icon: 'help_outline',
         dialog: 'about',
+        feature: 'branding',
       },
     ],
   },
@@ -1106,6 +1079,12 @@ const MENUS: MenuDef[] = [
   {
     id: 'help',
     label: 'Help',
+    // Whole-menu gate: an embedded host passes `features={{ help: false }}` to
+    // drop the Help menu entirely (no editor-branded surface). Individual
+    // branding links below also carry `feature: 'branding'` so a host that
+    // keeps Help (for keyboard shortcuts) can still hide the About / GitHub
+    // links with `features={{ branding: false }}`.
+    feature: 'help',
     items: [
       {
         kind: 'item',
@@ -1115,14 +1094,22 @@ const MENUS: MenuDef[] = [
         shortcut: 'Ctrl+/',
         dialog: 'keyboard-shortcuts',
       },
-      { kind: 'separator', id: 'sep-help' },
-      { kind: 'item', id: 'about', label: 'About casual sheets', icon: 'info', dialog: 'about' },
+      { kind: 'separator', id: 'sep-help', feature: 'branding' },
+      {
+        kind: 'item',
+        id: 'about',
+        label: 'About casual sheets',
+        icon: 'info',
+        dialog: 'about',
+        feature: 'branding',
+      },
       {
         kind: 'item',
         id: 'github',
         label: 'View on GitHub',
         icon: 'open_in_new',
         run: () => openExternal('https://github.com/CasualOffice/sheets'),
+        feature: 'branding',
       },
     ],
   },
@@ -1219,93 +1206,6 @@ const SUBMENU_PANEL_STYLE: CSSProperties = {
   zIndex: 1001,
 };
 
-/* ───────────────────────────── filtering ──────────────────────────────── */
-
-/** True when the feature gate (if any) is enabled (default: enabled). */
-function featureOn(feature: string | undefined, features: Record<string, boolean>): boolean {
-  if (!feature) return true;
-  return features[feature] !== false;
-}
-
-/**
- * Keep an item if its feature is on AND — for a dialog item — the chrome can
- * open it (built-in dialog, host override, or `onDialogRequest`). Dialog items
- * with no way to open are dropped (the SDK never fakes a dialog). Submenus are
- * filtered recursively and dropped when empty.
- */
-function keepItem(
-  item: MenuItemDef,
-  features: Record<string, boolean>,
-  canOpen: (kind: DialogKind) => boolean,
-): MenuItemDef | null {
-  if (!featureOn(item.feature, features)) return null;
-  if (item.kind === 'separator') return item;
-  if (item.kind === 'submenu') {
-    const items = filterItems(item.items, features, canOpen);
-    if (items.length === 0) return null;
-    return { ...item, items };
-  }
-  if (item.dialog && !canOpen(item.dialog)) return null;
-  return item;
-}
-
-/** Filter a list and collapse leading/trailing/double separators. */
-function filterItems(
-  items: MenuItemDef[],
-  features: Record<string, boolean>,
-  canOpen: (kind: DialogKind) => boolean,
-): MenuItemDef[] {
-  const kept = items
-    .map((i) => keepItem(i, features, canOpen))
-    .filter((i): i is MenuItemDef => i !== null);
-  // Collapse separators: drop leading, trailing, and runs.
-  const out: MenuItemDef[] = [];
-  for (const item of kept) {
-    if (item.kind === 'separator') {
-      if (out.length === 0) continue;
-      if (out[out.length - 1].kind === 'separator') continue;
-    }
-    out.push(item);
-  }
-  while (out.length > 0 && out[out.length - 1].kind === 'separator') out.pop();
-  return out;
-}
-
-/* ─────────────────────────── host extensions ──────────────────────────── */
-
-/**
- * Append host menu extensions to their target top-level menu. Each extension
- * becomes a normal `item` (with a leading separator before the first host item
- * in that menu so it's visually grouped). Host items dispatch via `onClick` or
- * route a `dialog` kind through the dialog host, exactly like built-ins.
- */
-function withMenuExtensions(menus: MenuDef[], ext?: MenuExtension[]): MenuDef[] {
-  if (!ext || ext.length === 0) return menus;
-  const byMenu = new Map<MenuId, MenuExtension[]>();
-  for (const e of ext) {
-    const list = byMenu.get(e.menu) ?? [];
-    list.push(e);
-    byMenu.set(e.menu, list);
-  }
-  return menus.map((menu) => {
-    const extras = byMenu.get(menu.id);
-    if (!extras || extras.length === 0) return menu;
-    const items: MenuItemDef[] = [...menu.items, { kind: 'separator', id: `ext-sep-${menu.id}` }];
-    for (const e of extras) {
-      items.push({
-        kind: 'item',
-        id: `ext-${e.id}`,
-        label: e.label,
-        icon: e.icon,
-        shortcut: e.shortcut,
-        dialog: e.dialog,
-        run: e.onClick ? (api) => e.onClick?.(api) : undefined,
-      });
-    }
-    return { ...menu, items };
-  });
-}
-
 /* ───────────────────────────── component ──────────────────────────────── */
 
 export interface MenuBarProps {
@@ -1381,15 +1281,10 @@ export function MenuBar({ api, features = {}, extensions }: MenuBarProps) {
     item.run?.(api);
   };
 
-  // Compute the visible menus once per render (feature + dialog-open gating),
-  // then append host menu extensions to their target menu.
-  const baseMenus = withMenuExtensions(MENUS, extensions?.menu);
-  const visibleMenus = baseMenus
-    .map((menu) => ({
-      ...menu,
-      items: filterItems(menu.items, features, dialogs.canOpen),
-    }))
-    .filter((menu) => featureOn(menu.feature, features) && menu.items.length > 0);
+  // Compute the visible menus once per render (feature + dialog-open gating +
+  // host menu extensions). Extracted to `computeVisibleMenus` so the gating
+  // contract is unit-testable without a DOM.
+  const visibleMenus = computeVisibleMenus(MENUS, features, dialogs.canOpen, extensions?.menu);
 
   const renderItems = (items: MenuItemDef[]): ReactNode =>
     items.map((item) => {

package/src/chrome/menu-model.ts

@@ -0,0 +1,191 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * MenuBar data model + pure gating engine.
+ *
+ * Split out of `MenuBar.tsx` so the feature-gating contract is unit-testable
+ * under `node --test`: `MenuBar.tsx` statically imports `@univerjs/core` values
+ * (which the vendored typeless-package ESM can't expose as named exports to
+ * node), so it can't be imported in a DOM-less test. This module has only
+ * type-only imports (all erased at build), so `computeVisibleMenus` — the code
+ * that decides which menus/items a host actually sees — can be exercised
+ * directly.
+ *
+ * Feature gates: pass `features` to hide a control or whole menu group when its
+ * feature is disabled. Defaults to all-enabled. A control whose feature is
+ * `false` does not render. An entire top-level menu whose own `feature` is
+ * `false`, or that ends up with no runnable items, is dropped.
+ */
+
+import type { DialogKind } from './dialog-context';
+import type { CasualSheetsAPI } from '../sheets/api';
+import type { MenuExtension } from './extensions';
+
+export type MenuId = 'file' | 'edit' | 'view' | 'insert' | 'format' | 'data' | 'help';
+
+/**
+ * Dialog kinds the host can choose to render via `onDialogRequest`. These are
+ * the actions the SDK chrome can't fulfil on its own (no built-in modal). The
+ * string is passed straight to the host hook; the `context` (when present)
+ * carries the pre-resolved A1 selection so the host doesn't have to re-read it.
+ */
+export type MenuDialogKind = DialogKind;
+
+export type RunFn = (api: CasualSheetsAPI) => void;
+
+export type MenuItemDef =
+  | {
+      kind: 'item';
+      id: string;
+      label: string;
+      icon?: string;
+      shortcut?: string;
+      /** Dispatch a command / facade call directly. */
+      run?: RunFn;
+      /** Route through the host's `onDialogRequest`. Omitted if no host hook. */
+      dialog?: MenuDialogKind;
+      /** Feature gate — item hidden when `features[feature] === false`. */
+      feature?: string;
+    }
+  | { kind: 'separator'; id: string; feature?: string }
+  | {
+      kind: 'submenu';
+      id: string;
+      label: string;
+      icon?: string;
+      items: MenuItemDef[];
+      feature?: string;
+    };
+
+export interface MenuDef {
+  id: MenuId;
+  label: string;
+  /** Feature gate for the whole menu. */
+  feature?: string;
+  items: MenuItemDef[];
+}
+
+/* ───────────────────────────── filtering ──────────────────────────────── */
+
+/** True when the feature gate (if any) is enabled (default: enabled). */
+export function featureOn(feature: string | undefined, features: Record<string, boolean>): boolean {
+  if (!feature) return true;
+  return features[feature] !== false;
+}
+
+/**
+ * Keep an item if its feature is on AND — for a dialog item — the chrome can
+ * open it (built-in dialog, host override, or `onDialogRequest`). Dialog items
+ * with no way to open are dropped (the SDK never fakes a dialog). Submenus are
+ * filtered recursively and dropped when empty.
+ */
+export function keepItem(
+  item: MenuItemDef,
+  features: Record<string, boolean>,
+  canOpen: (kind: DialogKind) => boolean,
+): MenuItemDef | null {
+  if (!featureOn(item.feature, features)) return null;
+  if (item.kind === 'separator') return item;
+  if (item.kind === 'submenu') {
+    const items = filterItems(item.items, features, canOpen);
+    if (items.length === 0) return null;
+    return { ...item, items };
+  }
+  if (item.dialog && !canOpen(item.dialog)) return null;
+  return item;
+}
+
+/** Filter a list and collapse leading/trailing/double separators. */
+export function filterItems(
+  items: MenuItemDef[],
+  features: Record<string, boolean>,
+  canOpen: (kind: DialogKind) => boolean,
+): MenuItemDef[] {
+  const kept = items
+    .map((i) => keepItem(i, features, canOpen))
+    .filter((i): i is MenuItemDef => i !== null);
+  // Collapse separators: drop leading, trailing, and runs.
+  const out: MenuItemDef[] = [];
+  for (const item of kept) {
+    if (item.kind === 'separator') {
+      if (out.length === 0) continue;
+      if (out[out.length - 1].kind === 'separator') continue;
+    }
+    out.push(item);
+  }
+  while (out.length > 0 && out[out.length - 1].kind === 'separator') out.pop();
+  return out;
+}
+
+/* ─────────────────────────── host extensions ──────────────────────────── */
+
+/**
+ * Append host menu extensions to their target top-level menu. Each extension
+ * becomes a normal `item` (with a leading separator before the first host item
+ * in that menu so it's visually grouped). Host items dispatch via `onClick` or
+ * route a `dialog` kind through the dialog host, exactly like built-ins.
+ */
+export function withMenuExtensions(menus: MenuDef[], ext?: MenuExtension[]): MenuDef[] {
+  if (!ext || ext.length === 0) return menus;
+  const byMenu = new Map<MenuId, MenuExtension[]>();
+  for (const e of ext) {
+    const list = byMenu.get(e.menu) ?? [];
+    list.push(e);
+    byMenu.set(e.menu, list);
+  }
+  return menus.map((menu) => {
+    const extras = byMenu.get(menu.id);
+    if (!extras || extras.length === 0) return menu;
+    const items: MenuItemDef[] = [...menu.items, { kind: 'separator', id: `ext-sep-${menu.id}` }];
+    for (const e of extras) {
+      items.push({
+        kind: 'item',
+        id: `ext-${e.id}`,
+        label: e.label,
+        icon: e.icon,
+        shortcut: e.shortcut,
+        dialog: e.dialog,
+        run: e.onClick ? (api) => e.onClick?.(api) : undefined,
+      });
+    }
+    return { ...menu, items };
+  });
+}
+
+/**
+ * Resolve the menus a host actually sees: append menu extensions, filter every
+ * item by its `feature` gate + dialog-openability, then drop any top-level menu
+ * whose own `feature` is off or that ends up empty.
+ *
+ * Exported (not inlined in the component) so the feature-gating contract — e.g.
+ * `features={{ help: false }}` drops the Help menu and
+ * `features={{ branding: false }}` drops the "View on GitHub" / "About" links —
+ * is unit-testable without a DOM.
+ */
+export function computeVisibleMenus(
+  menus: MenuDef[],
+  features: Record<string, boolean>,
+  canOpen: (kind: DialogKind) => boolean,
+  ext?: MenuExtension[],
+): MenuDef[] {
+  return withMenuExtensions(menus, ext)
+    .map((menu) => ({
+      ...menu,
+      items: filterItems(menu.items, features, canOpen),
+    }))
+    .filter((menu) => featureOn(menu.feature, features) && menu.items.length > 0);
+}