@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/client/components/common/shell-update-button/index.test.tsx

@@ -0,0 +1,251 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The footer control is a CONTROL; every word a run says is in the dialog.
+ *
+ * That split is the whole point of this suite. The footer is a 24px row of glyphs,
+ * and a status sentence pushed into it moved the neighbouring controls and read as
+ * a status line for the SIDEBAR rather than for the update the user just asked for.
+ * So the cases below assert the RENDERED tree in both states, not the module's
+ * constants: a table in a module would pass while the footer rendered something
+ * else.
+ *
+ * Three behaviours are load-bearing and each was a decision:
+ *
+ * 1. **A confirmation comes FIRST.** The click replaces the app and restarts it, so
+ *    a 24px glyph must not do that on a single press with no words.
+ * 2. **`done` and `error` print the SHELL's sentence**, inside the dialog. Nothing
+ *    here invents "Update failed": a shell that verified the download and declined
+ *    knows why, and that reason is the only thing a user can act on.
+ * 3. **A shell that cannot install it gets a LINK**, and the dialog never opens.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { ShellUpdateButton } from '@/client/components/common/shell-update-button';
+import type { ShellDownload } from '@/client/hooks/ui/updates/shell-download';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+const DESKTOP: ShellDownload = {
+  url: 'https://github.com/kabmo-labs/kabmo/releases/download/v0.3.2/Kabmo-0.3.2-mac-arm64.zip',
+  latest: '0.3.2',
+  releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.8.0',
+  direct: true,
+  kind: 'update',
+  platform: 'macos',
+};
+
+const PAGE: ShellDownload = { ...DESKTOP, url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.8.0', direct: false };
+
+let container: HTMLElement;
+
+/** Install (or remove) a bridge on the page. */
+function bridge(call: ((method: string, params?: Record<string, unknown>) => Promise<unknown>) | null): void {
+  const page = globalThis as unknown as { window: { __kabmoCall?: unknown } };
+  if (call) page.window.__kabmoCall = call;
+  else delete page.window.__kabmoCall;
+}
+
+async function mount(download: ShellDownload): Promise<void> {
+  await act(async () => {
+    render(h(ShellUpdateButton, { download, variant: 'icon' }), container);
+  });
+  for (let i = 0; i < 5; i += 1) await act(async () => {});
+}
+
+/**
+ * The dialog, by its role — the same locator a browser spec would use.
+ *
+ * Queried on `document.body`, not on the render container: the dialog is a PORTAL
+ * (see the component), which is what keeps it out of the footer row's own text.
+ */
+function dialog(): HTMLElement | null {
+  return document.body.querySelector('[role="dialog"]');
+}
+
+/**
+ * Both helpers search the whole body, because the dialog is a PORTAL: its controls
+ * live beside the render container, not inside it. The footer control is inside the
+ * container, which is itself in the body, so one query covers both.
+ */
+function byName(name: string): HTMLElement | null {
+  return document.body.querySelector(`[aria-label="${name}"]`);
+}
+
+function buttonByText(text: string): HTMLElement | null {
+  const buttons = [...document.body.querySelectorAll('button')];
+  return (buttons.find((button) => button.textContent?.trim() === text) as HTMLElement | undefined) ?? null;
+}
+
+async function click(element: HTMLElement | null): Promise<void> {
+  if (!element) throw new Error('nothing to click');
+  await act(async () => {
+    element.click();
+  });
+  for (let i = 0; i < 10; i += 1) await act(async () => {});
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  act(() => render(null, container));
+  bridge(null);
+});
+
+afterAll(() => {
+  container.remove();
+  restoreDomGlobals();
+});
+
+describe('a shell that can install its own update', () => {
+  test('the dialog is OUTSIDE the footer row, so the row says nothing about a run', async () => {
+    // A dialog rendered inside the footer would put its sentence into the row's own
+    // text content (measured in the browser before the portal: the row read as the
+    // dialog's body). It also has to be a portal for a second reason — the row is a
+    // 24px flex strip, and any `overflow`/`transform` added to it would clip a
+    // `fixed` overlay.
+    bridge(async () => ({ success: true, message: 'ok' }));
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+
+    const modal = document.body.querySelector('[role="dialog"]');
+    expect(modal).not.toBeNull();
+    expect(container.contains(modal)).toBe(false);
+    // The control itself carries no status text in any phase.
+    expect(byName('Update Kabmo 0.3.2 for macOS')?.textContent?.trim()).toBe('');
+  });
+
+  test('draws a button, and opens a CONFIRMATION rather than installing on the press', async () => {
+    const calls: string[] = [];
+    bridge(async (method) => {
+      calls.push(method);
+      return { success: true, version: '0.3.2', message: 'Kabmo 0.3.2 installed — restarting.', relaunching: true };
+    });
+    await mount(DESKTOP);
+
+    const control = byName('Update Kabmo 0.3.2 for macOS');
+    expect(control?.tagName).toBe('BUTTON');
+    // Nothing has been asked of the shell yet — that is the confirmation's job.
+    expect(calls).toEqual([]);
+
+    await click(control);
+    expect(dialog()).not.toBeNull();
+    expect(dialog()?.textContent).toContain('Version 0.3.2');
+    expect(dialog()?.textContent).toContain('replaces itself');
+    // Still nothing: the press opened a dialog, it did not install.
+    expect(calls).toEqual([]);
+  });
+
+  test('installing happens on the dialog’s own button, and the report stays IN the dialog', async () => {
+    const calls: { method: string; params?: Record<string, unknown> }[] = [];
+    bridge(async (method, params) => {
+      calls.push({ method, params });
+      return { success: true, version: '0.3.2', message: 'Kabmo 0.3.2 installed — restarting.', relaunching: true };
+    });
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Install update'));
+
+    expect(calls).toEqual([
+      { method: 'update_apply', params: { url: DESKTOP.url, version: '0.3.2' } },
+    ]);
+
+    // The sentence is the SHELL's, and it is inside the dialog.
+    expect(dialog()?.textContent).toContain('Kabmo 0.3.2 installed — restarting.');
+    // …and the footer carries no status line of its own: the control is still a
+    // control, with its own label.
+    expect(byName('Update Kabmo 0.3.2 for macOS')).not.toBeNull();
+  });
+
+  test('a refusal keeps the shell’s reason in the dialog, and offers another try', async () => {
+    bridge(async () => ({ success: false, message: 'The downloaded file is not a signed Kabmo build.' }));
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Install update'));
+
+    expect(dialog()?.textContent).toContain('The downloaded file is not a signed Kabmo build.');
+    expect(buttonByText('Try again')).not.toBeNull();
+    expect(buttonByText('Close')).not.toBeNull();
+  });
+
+  test('closing after a failure, then reopening, starts at the confirmation again', async () => {
+    // A dismissed run is not a run: the next press must not greet the user with the
+    // previous attempt's refusal.
+    bridge(async () => ({ success: false, message: 'The download could not be downloaded.' }));
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Install update'));
+    await click(buttonByText('Close'));
+    expect(dialog()).toBeNull();
+
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    expect(dialog()?.textContent).toContain('Version 0.3.2');
+    expect(dialog()?.textContent).not.toContain('could not be downloaded');
+  });
+
+  test('Cancel closes without asking the shell anything', async () => {
+    const calls: string[] = [];
+    bridge(async (method) => {
+      calls.push(method);
+      return { success: true, message: 'ok' };
+    });
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Cancel'));
+
+    expect(dialog()).toBeNull();
+    expect(calls).toEqual([]);
+  });
+});
+
+describe('the phone footer’s variant', () => {
+  test('draws the short label on the same button, and opens the same dialog', async () => {
+    // The two layouts pass different `variant`s because a 24px glyph and a word are
+    // different rows — but they must be the same CONTROL: a link on one layout and a
+    // button on the other is the drift this component exists to prevent.
+    bridge(async () => ({ success: true, version: '0.3.2', message: 'Kabmo 0.3.2 installed — restarting.' }));
+    await act(async () => {
+      render(h(ShellUpdateButton, { download: DESKTOP, variant: 'label' }), container);
+    });
+    for (let i = 0; i < 5; i += 1) await act(async () => {});
+
+    const control = byName('Update Kabmo 0.3.2 for macOS');
+    expect(control?.tagName).toBe('BUTTON');
+    expect(control?.textContent?.trim()).toBe('Update macOS');
+
+    await click(control);
+    expect(dialog()?.textContent).toContain('Version 0.3.2');
+  });
+});
+
+describe('a shell that cannot install it', () => {
+  test('draws a link to the release page, and no dialog', async () => {
+    bridge(async () => null);
+    await mount(PAGE);
+
+    const control = byName('Update Kabmo 0.3.2 for macOS');
+    expect(control?.tagName).toBe('A');
+    expect(control?.getAttribute('href')).toBe(PAGE.url);
+    expect(control?.getAttribute('target')).toBe('_blank');
+
+    await click(control);
+    expect(dialog()).toBeNull();
+  });
+
+  test('a browser draws the link too, because there is no shell to ask', async () => {
+    bridge(null);
+    await mount(DESKTOP);
+
+    expect(byName('Update Kabmo 0.3.2 for macOS')?.tagName).toBe('A');
+    expect(dialog()).toBeNull();
+  });
+});

package/src/client/components/common/shell-update-button/index.tsx

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The native shell's update/install control, shared by both sidebar layouts.
+ *
+ * ## Two controls, because there are two different jobs
+ *
+ * - **A link** when the console cannot name a file: a desktop shell that did not
+ *   report its architecture, or any offer whose artifact is not installable from
+ *   inside. Following it is the browser's (or the WebView's) job.
+ * - **A button** when the shell CAN install it: the click opens a CONFIRMATION, and
+ *   the confirmation asks the shell to download, verify and replace itself. That is
+ *   the desktop self-update, and it is the whole reason this component exists.
+ *
+ * The decision is `canSelfUpdate`, never a check on the platform at the call site:
+ * Android installs through `PackageInstaller` (its own path, unchanged), iOS cannot
+ * install at all, and a browser has no shell to ask.
+ *
+ * ## The control is ONLY a control
+ *
+ * Every word a run has to say — the confirmation, the progress, the shell's own
+ * refusal — is in `Modal.tsx`. The footer is a 24px row of glyphs, and a status
+ * sentence pushed into it moved the neighbouring controls and read as a status
+ * line for the SIDEBAR rather than for the update.
+ *
+ * ## The state lives here, not in either footer
+ *
+ * Both layouts draw this control and each unmounts at a different moment (a phone
+ * closes its drawer, a desktop swaps sessions). One hook, one vocabulary of
+ * phases, so the two cannot report the same run differently.
+ */
+
+import { useState } from 'preact/hooks';
+import { createPortal } from 'preact/compat';
+import { Download, Loader2 } from 'lucide-preact';
+import {
+  shellDownloadLabel,
+  shellDownloadShortLabel,
+  type ShellDownload,
+} from '@/client/hooks/ui/updates/shell-download';
+import { canSelfUpdate, useShellUpdate } from '@/client/hooks/ui/updates/shell-update';
+import { ShellUpdateModal } from '@/client/components/common/shell-update-button/Modal';
+
+interface ShellUpdateButtonProps {
+  download: ShellDownload;
+  /** `icon` for the desktop footer's glyph row, `label` for the phone's. */
+  variant: 'icon' | 'label';
+}
+
+const ICON_CLASS = 'p-1 rounded hover:text-ink hover:bg-ink/5 cursor-pointer transition-colors';
+
+export function ShellUpdateButton({ download, variant }: ShellUpdateButtonProps) {
+  const { phase, message, apply, reset, working } = useShellUpdate();
+  // The dialog is open from the CLICK until it is dismissed, and the run's phases
+  // are drawn inside it. A closed dialog whose run is still `working` is not a
+  // state this component can be in: `confirm` is what opens it.
+  const [open, setOpen] = useState(false);
+  const label = shellDownloadLabel(download);
+
+  if (!canSelfUpdate(download)) {
+    // A link, and `target="_blank"` hands it to the system browser so the console
+    // is not replaced by a file download.
+    return (
+      <a
+        href={download.url}
+        target="_blank"
+        rel="noopener noreferrer"
+        title={label}
+        aria-label={label}
+        className={ICON_CLASS}
+      >
+        {variant === 'icon' ? <Download size={16} /> : <span>{shellDownloadShortLabel(download)}</span>}
+      </a>
+    );
+  }
+
+  return (
+    <>
+      <button
+        type="button"
+        // A dismissed run is not a run: reopening starts from the confirmation, not
+        // from the previous attempt's refusal.
+        onClick={() => {
+          reset();
+          setOpen(true);
+        }}
+        disabled={working}
+        title={label}
+        aria-label={label}
+        className={`${ICON_CLASS} disabled:cursor-not-allowed disabled:opacity-60 inline-flex items-center gap-1`}
+      >
+        {working ? (
+          <Loader2 size={variant === 'icon' ? 16 : 13} className="animate-spin motion-reduce:animate-none" />
+        ) : (
+          <Download size={variant === 'icon' ? 16 : 13} />
+        )}
+        {variant === 'label' && <span>{shellDownloadShortLabel(download)}</span>}
+      </button>
+
+      {open &&
+        // A PORTAL, not a child of this row. The footer is a 24px flex row of
+        // glyphs, so a dialog rendered inside it is nested in a control strip: its
+        // text joins the row's own text content (measured in the browser — the row
+        // read as the dialog's body), and any `overflow`/`transform` added to that
+        // row later would clip a `fixed` overlay. The portal is what makes "the
+        // footer says nothing about a run" true rather than merely visually true.
+        createPortal(
+          <ShellUpdateModal
+            download={download}
+            phase={phase === 'idle' ? 'confirm' : phase}
+            message={message}
+            onConfirm={() => void apply(download)}
+            // Closing mid-run hides the dialog but does not cancel the shell: it is
+            // already replacing itself, and a Cancel that could not stop it would be
+            // a button that lies. The control stays disabled until the run answers.
+            onClose={() => setOpen(false)}
+          />,
+          document.body,
+        )}
+    </>
+  );
+}

package/src/client/components/common/toolbar-row/index.test.tsx

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The toolbar stays ONE row, and what does not fit is one click away.
+ *
+ * The failure this pins is a row that becomes two: the editor panel is 320px
+ * wide on a 1440px screen, and the width-mode buttons pushed ten controls past
+ * it. Wrapping moved the document down by the toolbar's own height and read as
+ * a second toolbar; a horizontal scroll clipped the tail invisibly. Neither is
+ * visible to a state-only assertion, so the cases below are about what is
+ * RENDERED and what the `⋯` menu offers.
+ *
+ * happy-dom lays nothing out, so `getBoundingClientRect` and `clientWidth` are
+ * stubbed at the PROTOTYPE level — the rule reads exactly those two values, and
+ * stubbing them before the first render is what lets the component's own layout
+ * effect measure a real row instead of a row of zeros.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { Save, Search, WrapText } from 'lucide-preact';
+import { ToolbarRow, type ToolbarCluster } from '@/client/components/common/toolbar-row';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+let container: HTMLElement;
+/** What the stubbed layout reports for the row, and for each cluster in order. */
+let rowWidth = 0;
+let clusterWidths: number[] = [];
+
+/** Captured inside `beforeAll`: the DOM globals do not exist at module load. */
+let originalRect: typeof Element.prototype.getBoundingClientRect;
+let originalClientWidth: PropertyDescriptor | undefined;
+
+/** The row is the flex container the component renders; clusters carry a marker. */
+function isRow(el: HTMLElement): boolean {
+  return el.className.includes('flex-nowrap');
+}
+
+function rectOf(width: number): DOMRect {
+  return { width, height: 0, top: 0, left: 0, right: width, bottom: 0, x: 0, y: 0, toJSON: () => ({}) } as DOMRect;
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+  originalRect = Element.prototype.getBoundingClientRect;
+  originalClientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientWidth');
+  Element.prototype.getBoundingClientRect = function (this: Element) {
+    const el = this as HTMLElement;
+    if (el.hasAttribute?.('data-toolbar-cluster')) {
+      const siblings = [...(el.parentElement?.querySelectorAll('[data-toolbar-cluster]') ?? [])];
+      return rectOf(clusterWidths[siblings.indexOf(el)] ?? 0);
+    }
+    if (isRow(el)) return rectOf(rowWidth);
+    return originalRect.call(this);
+  };
+  Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+    configurable: true,
+    get(this: HTMLElement) {
+      if (isRow(this)) return rowWidth;
+      return originalClientWidth?.get?.call(this) ?? 0;
+    },
+  });
+});
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+  }
+  rowWidth = 0;
+  clusterWidths = [];
+});
+
+afterAll(() => {
+  Element.prototype.getBoundingClientRect = originalRect;
+  if (originalClientWidth) Object.defineProperty(HTMLElement.prototype, 'clientWidth', originalClientWidth);
+  restoreDomGlobals();
+});
+
+/** Three clusters, the first pinned — the editor toolbar in miniature. */
+function clusters(onSelect: string[] = []): ToolbarCluster[] {
+  const make = (id: string, label: string, icon: typeof Save, pinned?: boolean): ToolbarCluster => ({
+    id,
+    pinned,
+    actions: [{ label, icon, onSelect: () => onSelect.push(label) }],
+    children: h('button', { type: 'button', 'aria-label': label }, label),
+  });
+  return [
+    make('save', 'Save file', Save, true),
+    make('find', 'Find and replace', Search),
+    make('wrap', 'Word wrap on', WrapText),
+  ];
+}
+
+async function mount(width: number, widths: number[], onSelect: string[] = []): Promise<void> {
+  rowWidth = width;
+  clusterWidths = widths;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(h(ToolbarRow, { clusters: clusters(onSelect) }), container);
+  });
+  // The layout effect commits its measurement in a second pass, the way the
+  // browser gives one before paint.
+  await act(async () => {});
+}
+
+function rowButtons(): HTMLButtonElement[] {
+  const host = container.firstElementChild as HTMLElement;
+  return [...host.querySelectorAll<HTMLButtonElement>(':scope > div > button')];
+}
+
+async function openMenu(): Promise<void> {
+  const trigger = rowButtons().find((button) => button.getAttribute('aria-label') === 'More actions');
+  if (!trigger) throw new Error('no overflow trigger rendered');
+  await act(async () => {
+    trigger.dispatchEvent(new window.MouseEvent('click', { bubbles: true }) as never);
+  });
+}
+
+describe('ToolbarRow overflow', () => {
+  test('a wide row draws every cluster and no trigger', async () => {
+    await mount(400, [60, 60, 60]);
+    expect(rowButtons().map((button) => button.getAttribute('aria-label'))).toEqual([
+      'Save file',
+      'Find and replace',
+      'Word wrap on',
+    ]);
+  });
+
+  test('a narrow row keeps the pinned cluster and moves the rest into `⋯`', async () => {
+    await mount(120, [60, 60, 60]);
+    const labels = rowButtons().map((button) => button.getAttribute('aria-label'));
+    expect(labels).toContain('Save file');
+    expect(labels).toContain('More actions');
+    expect(labels).not.toContain('Word wrap on');
+  });
+
+  test('the menu offers the hidden controls, named in words', async () => {
+    await mount(120, [60, 60, 60]);
+    await openMenu();
+    const items = [...container.querySelectorAll('[role="menuitem"]')].map((item) => item.textContent?.trim());
+    expect(items).toContain('Word wrap on');
+    // The pinned control is on the row, so it is NOT in the menu.
+    expect(items).not.toContain('Save file');
+  });
+
+  test('a menu row runs the same action the button would', async () => {
+    const ran: string[] = [];
+    await mount(120, [60, 60, 60], ran);
+    await openMenu();
+    const item = [...container.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')].find(
+      (row) => row.textContent?.trim() === 'Word wrap on',
+    );
+    if (!item) throw new Error('the wrap row is missing from the menu');
+    await act(async () => {
+      item.dispatchEvent(new window.MouseEvent('click', { bubbles: true }) as never);
+    });
+    expect(ran).toEqual(['Word wrap on']);
+  });
+});