@kabmo-labs/kabmo 0.4.0 → 0.5.1

package/src/client/hooks/ui/toasts.ts

@@ -1,7 +1,18 @@
 import { useRef, useState } from 'preact/hooks';
 import type { ToastData } from '@/client/components/common/Toast';
 
-export function useToasts() {
+/** What `useToasts` hands back — named, so a component takes the contract rather than `ReturnType`. */
+export interface ToastsHandle {
+  toasts: ToastData[];
+  pushToast: (
+    message: string,
+    type?: 'success' | 'error',
+    options?: { action?: ToastData['action']; duration?: number },
+  ) => void;
+  dismissToast: (id: number) => void;
+}
+
+export function useToasts(): ToastsHandle {
   const [toasts, setToasts] = useState<ToastData[]>([]);
   const toastIdRef = useRef(0);
 

package/src/shared/lib/ui/titlebar.test.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The PWA titlebar insets, evaluated against the two platform geometries.
+ *
+ * The bug this pins is arithmetic, so asserting the STRING would pass while the
+ * wrong edge was reserved. The expressions are therefore substituted with real
+ * env values and evaluated:
+ *
+ *   - macOS puts the window controls on the LEFT: `titlebar-area-x` is ~76px and
+ *     `titlebar-area-width` is the rest of the window. The right inset must be
+ *     the BASE padding — the old form `100vw - width` reserved 76px of dead
+ *     space between the last navbar control and the window's right edge.
+ *   - Windows/Linux put them on the RIGHT: `x` is 0, so both forms agree and the
+ *     right inset is the overlay's own width.
+ *   - A browser tab has neither: both env variables fall back, and the base
+ *     padding is all that is left.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  TITLEBAR_OVERLAY_RIGHT,
+  titlebarPaddingLeft,
+  titlebarPaddingRight,
+} from '@/shared/lib/ui/titlebar';
+
+const REM = 16;
+const VIEWPORT = 1440;
+
+interface Geometry {
+  /** `titlebar-area-x`; absent means the browser tab's fallback. */
+  x?: number;
+  /** `titlebar-area-width`; absent means the fallback. */
+  width?: number;
+  safeLeft?: number;
+  safeRight?: number;
+}
+
+/**
+ * Evaluate one of the returned declarations.
+ *
+ * `env(name, fallback)` resolves to the geometry's value or its fallback, `vw`
+ * resolves to the viewport, and `max()`/`calc()` become their JS equivalents —
+ * which is exactly what a browser computes, minus unit conversion.
+ */
+function evaluate(expression: string, geometry: Geometry): number {
+  const values: Record<string, number | undefined> = {
+    'titlebar-area-x': geometry.x,
+    'titlebar-area-width': geometry.width,
+    'safe-area-inset-left': geometry.safeLeft,
+    'safe-area-inset-right': geometry.safeRight,
+  };
+  const substituted = expression
+    // `vw` first: the fallback inside an `env()` can itself be a viewport unit
+    // (`env(titlebar-area-width, 100vw)`), and resolving it afterwards would
+    // hand `parseLength` a unit it cannot read.
+    .replace(/([\d.]+)vw/g, (_match, value: string) => `${(Number(value) / 100) * VIEWPORT}px`)
+    .replace(
+      /env\(\s*([a-z-]+)\s*,\s*([^)]+)\)/g,
+      (_match, name: string, fallback: string) => `${values[name] ?? parseLength(fallback)}px`,
+    )
+    .replace(/max\(/g, 'Math.max(')
+    .replace(/calc\(/g, '(');
+  const js = substituted.replace(/([\d.]+)(px|rem)/g, (_match, value: string, unit: string) =>
+    unit === 'rem' ? String(Number(value) * REM) : value,
+  );
+  return Function(`return (${js})`)() as number;
+}
+
+function parseLength(value: string): number {
+  const match = /^([\d.]+)(px|rem)?$/.exec(value.trim());
+  if (!match) throw new Error(`Unsupported length: ${value}`);
+  return match[2] === 'rem' ? Number(match[1]) * REM : Number(match[1]);
+}
+
+/** macOS: traffic lights on the left, ~76px of them. */
+const MACOS: Geometry = { x: 76, width: VIEWPORT - 76 };
+/** Windows: controls and the app menu on the right, ~138px of them. */
+const WINDOWS: Geometry = { x: 0, width: VIEWPORT - 138 };
+/** A browser tab: no WCO at all, so both variables take their fallbacks. */
+const TAB: Geometry = {};
+
+describe('titlebar insets', () => {
+  test('the right inset is the space AFTER the title bar area, not before it', () => {
+    // The overlay sits between the area's far edge and the window's right edge.
+    expect(TITLEBAR_OVERLAY_RIGHT).toContain('env(titlebar-area-x');
+    expect(TITLEBAR_OVERLAY_RIGHT).toContain('env(titlebar-area-width');
+
+    // macOS: the traffic lights are on the LEFT, so nothing may be reserved on
+    // the right. This is the reported gap.
+    expect(evaluate(titlebarPaddingRight('1rem'), MACOS)).toBe(REM);
+    // Windows: the overlay is on the right, and its width is what clears it.
+    expect(evaluate(titlebarPaddingRight('1rem'), WINDOWS)).toBe(138);
+    // No WCO: the base padding, unchanged.
+    expect(evaluate(titlebarPaddingRight('1rem'), TAB)).toBe(REM);
+  });
+
+  test('the left inset is the title bar area origin', () => {
+    expect(evaluate(titlebarPaddingLeft('1rem'), MACOS)).toBe(76);
+    expect(evaluate(titlebarPaddingLeft('1rem'), WINDOWS)).toBe(REM);
+    expect(evaluate(titlebarPaddingLeft('1rem'), TAB)).toBe(REM);
+  });
+
+  test('the phone variants keep the notch insets', () => {
+    expect(evaluate(titlebarPaddingLeft('0.75rem', true), { ...MACOS, safeLeft: 44 })).toBe(76);
+    expect(evaluate(titlebarPaddingLeft('0.75rem', true), { x: 0, safeLeft: 44 })).toBe(44);
+    // A landscape phone's right notch clears the edge on its own, and the
+    // overlay's width is still honoured when it is the larger of the two.
+    expect(evaluate(titlebarPaddingRight('0.75rem', true), { x: 0, width: VIEWPORT - 138, safeRight: 44 })).toBe(138);
+    expect(evaluate(titlebarPaddingRight('0.75rem', true), { ...MACOS, safeRight: 44 })).toBe(44);
+  });
+
+  test('the old form is the bug, stated as a control', () => {
+    // `100vw - titlebar-area-width` on macOS: the traffic lights' 76px charged
+    // to the wrong edge, which is the strip the report showed.
+    const buggy = `max(1rem, calc(100vw - env(titlebar-area-width, 100vw)))`;
+    expect(evaluate(buggy, MACOS)).toBe(76);
+    expect(evaluate(buggy, WINDOWS)).toBe(138);
+  });
+});

package/src/shared/lib/ui/titlebar.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The insets that keep a header's controls clear of the PWA window controls
+ * (Window Controls Overlay), stated ONCE because four headers draw them.
+ *
+ * The `titlebar-area-*` env variables describe the area the page may use: it
+ * runs from the frame edge to the innermost edge of the overlay that houses the
+ * window controls. Which SIDE that overlay is on is the platform's choice, and
+ * `titlebar-area-x` is the answer:
+ *
+ *   - macOS puts the traffic lights on the LEFT, so `x` is ~76px and
+ *     `titlebar-area-width` is `viewport - 76`;
+ *   - Windows and Linux put the controls (and Chrome's `⋮` app menu) on the
+ *     RIGHT, so `x` is `0` and `titlebar-area-width` is `viewport - overlay`.
+ *
+ * So the LEFT inset is `x`, and the RIGHT inset is whatever is left over after
+ * the area ENDS — `viewport - (x + width)` — never `viewport - width`. The
+ * second form is what the headers used to compute, and on macOS it reserved the
+ * traffic lights' width on the wrong edge: a 76px dead strip between the last
+ * navbar control and the window's right edge, with no control anywhere near it.
+ * On Windows the two forms agree, which is why the bug only showed on one
+ * platform.
+ *
+ * `safeArea` adds the iOS/Android notch insets, which the phone headers carry.
+ * A desktop PWA has them at 0, so one helper serves both.
+ */
+
+/**
+ * The width of the overlay that sits to the RIGHT of the title bar area.
+ *
+ * Both env variables are read with a fallback, so this is `0px` in a browser
+ * tab (where WCO is not active) and on macOS, and the platform's real control
+ * width on Windows/Linux.
+ */
+export const TITLEBAR_OVERLAY_RIGHT =
+  'calc(100vw - env(titlebar-area-x, 0px) - env(titlebar-area-width, 100vw))';
+
+/** `base`-sized padding that also clears the window controls on the left. */
+export function titlebarPaddingLeft(base: string, safeArea = false): string {
+  return safeArea
+    ? `max(${base}, env(safe-area-inset-left, 0px), env(titlebar-area-x, 0px))`
+    : `max(${base}, env(titlebar-area-x, 0px))`;
+}
+
+/** `base`-sized padding that also clears the window controls on the right. */
+export function titlebarPaddingRight(base: string, safeArea = false): string {
+  return safeArea
+    ? `max(${base}, env(safe-area-inset-right, 0px), ${TITLEBAR_OVERLAY_RIGHT})`
+    : `max(${base}, ${TITLEBAR_OVERLAY_RIGHT})`;
+}

package/src/shared/lib/workspace/mobile-dock.test.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which panels each phone drawer offers.
+ *
+ * Both rules are silent failures when wrong, which is why they are pinned:
+ * a panel on BOTH strips is one panel with two chips (and one of them is a
+ * second place to be), while a panel on NEITHER is a placement that looks like
+ * an uninstall.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { phoneLeftStripVisible, phoneRightPanels } from '@/shared/lib/workspace/mobile-dock';
+import type { PanelSide } from '@/shared/lib/workspace/left-dock';
+
+const SESSIONS = 'sessions';
+
+function panels(...rows: [string, PanelSide][]) {
+  return rows.map(([id, side]) => ({ id, side }));
+}
+
+describe('phoneRightPanels', () => {
+  test('drops the session list, which the phone draws as its own screen', () => {
+    const all = panels([SESSIONS, 'left'], ['files', 'right']);
+    expect(phoneRightPanels(all, SESSIONS, false).map((p) => p.id)).toEqual(['files']);
+  });
+
+  test('with the rail OFF a left-placed panel stays here — the left drawer cannot reach it', () => {
+    const all = panels([SESSIONS, 'left'], ['files', 'right'], ['plugin:demo:rightPanel', 'left']);
+    expect(phoneRightPanels(all, SESSIONS, false).map((p) => p.id)).toEqual(['files', 'plugin:demo:rightPanel']);
+  });
+
+  test('with the rail ON the left drawer owns it, so this one must not draw it twice', () => {
+    const all = panels([SESSIONS, 'left'], ['files', 'right'], ['plugin:demo:rightPanel', 'left']);
+    expect(phoneRightPanels(all, SESSIONS, true).map((p) => p.id)).toEqual(['files']);
+  });
+
+  test('the rail being on never hides a RIGHT-column view', () => {
+    const all = panels(['git', 'right'], ['todo', 'right']);
+    expect(phoneRightPanels(all, SESSIONS, true).map((p) => p.id)).toEqual(['git', 'todo']);
+  });
+});
+
+describe('phoneLeftStripVisible', () => {
+  test('no rail, no strip', () => {
+    expect(phoneLeftStripVisible(false, 2, true)).toBe(false);
+  });
+
+  test('a strip holding only Sessions is chrome that never changes', () => {
+    expect(phoneLeftStripVisible(true, 0, true)).toBe(false);
+  });
+
+  test('a placed panel is a second destination, so the strip appears', () => {
+    expect(phoneLeftStripVisible(true, 1, true)).toBe(true);
+  });
+
+  test('a stored view that no longer resolves still gets the strip — its body is a notice', () => {
+    // Without this the drawer would be stuck on a notice with no way back to
+    // the session list: the body has no chips of its own.
+    expect(phoneLeftStripVisible(true, 0, false)).toBe(true);
+  });
+});

package/src/shared/lib/workspace/mobile-dock.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which panels each phone drawer offers.
+ *
+ * The phone has TWO drawers and one catalog, so the split is a rule rather
+ * than a per-component filter. It used to be one rule for the right drawer
+ * (`all`, minus the session list), because a panel placed on the left had
+ * nowhere else to be reached — the left drawer was a plain session list. Now
+ * the left drawer draws the dock too, so leaving `all` in the right one puts a
+ * single panel on two strips of one phone.
+ *
+ * Pure, and separate from both components, so the two drawers cannot drift and
+ * the rule can be tested without mounting either.
+ */
+
+import type { PanelSide } from '@/shared/lib/workspace/left-dock';
+
+/** The parts of a catalog entry these rules read. */
+interface SidedPanel {
+  id: string;
+  side: PanelSide;
+}
+
+/**
+ * The right drawer's chips.
+ *
+ * `all` while the left rail is OFF: a placed panel is then unreachable from the
+ * left drawer (it has no strip), and hiding it from both would make the
+ * placement look like an uninstall. With the rail on the left drawer owns them.
+ */
+export function phoneRightPanels<T extends SidedPanel>(
+  panels: readonly T[],
+  sessionsViewId: string,
+  dockEnabled: boolean,
+): T[] {
+  return panels.filter(
+    (panel) => panel.id !== sessionsViewId && !(dockEnabled && panel.side === 'left'),
+  );
+}
+
+/**
+ * Whether the left drawer draws its chip strip.
+ *
+ * A strip holding one chip is chrome that never changes, so it needs a second
+ * destination — either a placed panel, or a stored view that no longer
+ * resolves. The second half is the escape hatch: that body is a notice, and
+ * without the strip the session list would be unreachable.
+ */
+export function phoneLeftStripVisible(dockEnabled: boolean, placedCount: number, showingSessions: boolean): boolean {
+  return dockEnabled && (placedCount > 0 || !showingSessions);
+}

package/src/test-support/silent-socket.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A `WebSocket` that never dials, and the teardown pair that goes with it.
+ *
+ * A suite that mounts a component reading a realtime topic subscribes to the
+ * unified channel on mount, and `dial()` then constructs a real socket from
+ * `window.location`. Two failure shapes follow, and both are reported against
+ * whichever file runs NEXT rather than the one that caused them:
+ *
+ * - a happy-dom window created with no URL reports `about:blank`, whose origin
+ *   is `null`, so `realtimeSocketUrl()` produces `ws:///api/realtime/ws`. Bun
+ *   constructs that object without complaint and fails it ASYNCHRONOUSLY, after
+ *   the suite has already restored the DOM globals — measured as
+ *   `Unhandled error. (ErrorEvent { isTrusted: [Getter] })` between tests, and
+ *   then as `Cannot call beforeAll() after the test run has completed` in the
+ *   next file, because the error tears the run down mid-file.
+ * - a window WITH an origin dials a port nothing listens on, which fails the
+ *   same way (a refused connection is also asynchronous).
+ *
+ * `resetRealtimeClient()` in `afterEach` is not enough on its own: it closes a
+ * socket that already exists, and the dial's own failure has not been delivered
+ * yet. Silencing the CONSTRUCTOR is what removes the failure at its source.
+ *
+ * The subject of such a suite is its own markup, never the channel, so this
+ * stub sends nothing and reports nothing. A suite that really drives the
+ * channel uses `startRealtimeTestServer` instead, which injects the runner's
+ * own `WebSocket` (see `pristineWebSocket`).
+ */
+
+import { realtimeClient, resetRealtimeClient } from '@/shared/lib/realtime/client';
+
+/** `WebSocket.CLOSING` / `CLOSED`, spelled out: the client reads them off the
+ *  instance, and this object need not carry the statics. */
+class SilentSocket {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+  readyState = SilentSocket.CLOSED;
+  onopen: (() => void) | null = null;
+  onclose: (() => void) | null = null;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  onerror: (() => void) | null = null;
+  send(): void {}
+  close(): void {}
+}
+
+/**
+ * Point the channel at `SilentSocket`. Call it BEFORE mounting anything that
+ * subscribes — a dial that already happened is not retracted by this.
+ */
+export function silenceRealtime(): void {
+  realtimeClient.setSocketConstructor(SilentSocket as unknown as typeof WebSocket);
+}
+
+/**
+ * Undo `silenceRealtime` and drop the channel's state. This is the `afterEach`
+ * half: the constructor goes back to `null` (the real global) so the next file
+ * is not left silenced, and the reset clears the topic cache the stubbed
+ * channel accumulated.
+ */
+export function restoreRealtime(): void {
+  resetRealtimeClient();
+  realtimeClient.setSocketConstructor(null);
+}