@rangka/client 0.0.1

package/src/shell/app-sidebar/types.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+
+export interface AppSidebarModule {
+  name: string;
+  label: string;
+  icon?: ReactNode;
+}
+
+export interface AppSidebarNavItem {
+  title: string;
+  url: string;
+}
+
+export interface AppSidebarNavSection {
+  title: string;
+  icon?: ReactNode;
+  items: AppSidebarNavItem[];
+}
+
+export interface AppSidebarUser {
+  name: string;
+  email: string;
+  avatar?: string;
+}
+
+export interface AppSidebarProps {
+  modules: AppSidebarModule[];
+  activeModule?: string;
+  onModuleSwitch: (name: string) => void;
+  onAllModules?: () => void;
+  onSearch?: () => void;
+  navigation: AppSidebarNavSection[];
+  currentPath: string;
+  onNavigate: (url: string) => void;
+  user?: AppSidebarUser;
+  onLogout?: () => void;
+  onPreferences?: () => void;
+}

package/src/shell/types.ts

@@ -0,0 +1,6 @@
+export interface BreadcrumbItem {
+  label: string;
+  path?: string;
+}
+
+export type Size = 'sm' | 'md' | 'lg';

package/src/shell/useBreadcrumbs.ts

@@ -0,0 +1,42 @@
+import { useMemo } from 'react';
+import type { BreadcrumbItem } from './types.js';
+import type { NavigationTree, PageDefinition } from '@rangka/shared';
+
+export function useBreadcrumbs(
+  currentPath: string,
+  navigation: NavigationTree[],
+  pages: PageDefinition[],
+): BreadcrumbItem[] {
+  return useMemo((): BreadcrumbItem[] => {
+    const parts = currentPath.split('/').filter(Boolean);
+    if (parts.length === 0) return [];
+
+    const result: BreadcrumbItem[] = [];
+
+    const moduleName = parts[0];
+    const mod = navigation.find((n) => n.module === moduleName);
+    if (mod) {
+      result.push({
+        label: mod.label,
+        path: '/' + moduleName,
+      });
+    } else {
+      result.push({ label: moduleName, path: '/' + moduleName });
+    }
+
+    if (parts.length >= 2) {
+      const pageKey = `${parts[0]}.${parts[1]}`;
+      const page = pages.find((p) => p.key === pageKey);
+      result.push({
+        label: page?.label ?? parts[1],
+        path: '/' + parts.slice(0, 2).join('/'),
+      });
+    }
+
+    if (parts.length >= 3) {
+      result.push({ label: parts[2], path: currentPath });
+    }
+
+    return result;
+  }, [currentPath, navigation, pages]);
+}

package/src/studio/bridge.ts

@@ -0,0 +1,125 @@
+import type { ClientToStudioMessage, StudioToClientMessage } from './types.js';
+import { findWidgetElement, buildWidgetPath, findPageKey, extractMeta } from './walker.js';
+import { createOverlay, updateOverlay, showOverlay, hideOverlay } from './overlay.js';
+
+export function initBridge(): void {
+  if (window.parent === window) return;
+
+  createOverlay();
+  let inspecting = false;
+
+  function startInspect() {
+    inspecting = true;
+    document.body.style.cursor = 'crosshair';
+  }
+
+  function stopInspect() {
+    inspecting = false;
+    hideOverlay();
+    document.body.style.cursor = '';
+  }
+
+  // Expose for console debugging
+  (window as unknown as Record<string, unknown>).__rangkaStudio = {
+    startInspect,
+    stopInspect,
+    isInspecting: () => inspecting,
+  };
+
+  window.addEventListener('message', (event) => {
+    const msg = event.data as StudioToClientMessage;
+    if (!msg?.type?.startsWith('rangka-studio:')) return;
+
+    if (msg.type === 'rangka-studio:inspect-start') {
+      startInspect();
+    } else if (msg.type === 'rangka-studio:inspect-stop') {
+      stopInspect();
+    } else if (msg.type === 'rangka-studio:pong') {
+      if (msg.inspecting) {
+        startInspect();
+      }
+    }
+  });
+
+  document.addEventListener('mousemove', (e) => {
+    if (!inspecting) return;
+    const target = e.target as HTMLElement;
+    const widgetEl = findWidgetElement(target);
+    if (widgetEl) {
+      const rect = getMeasurableRect(widgetEl);
+      updateOverlay(rect);
+      showOverlay();
+      const widgetPath = buildWidgetPath(widgetEl);
+      const pageKey = findPageKey(widgetEl);
+      post({
+        type: 'rangka-client:hover',
+        widgetPath,
+        rect: { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
+        pageKey,
+      });
+    } else {
+      hideOverlay();
+      post({ type: 'rangka-client:hover-out' });
+    }
+  });
+
+  document.addEventListener(
+    'click',
+    (e) => {
+      if (!inspecting) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const target = e.target as HTMLElement;
+      const widgetEl = findWidgetElement(target);
+      if (widgetEl) {
+        const widgetPath = buildWidgetPath(widgetEl);
+        const meta = extractMeta(widgetEl);
+        const pageKey = findPageKey(widgetEl);
+        post({ type: 'rangka-client:select', widgetPath, meta, pageKey });
+      }
+    },
+    { capture: true },
+  );
+
+  patchNavigation();
+
+  post({ type: 'rangka-client:ready' });
+  post({ type: 'rangka-client:ping' });
+  post({ type: 'rangka-client:navigate', path: window.location.pathname });
+}
+
+function patchNavigation(): void {
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+
+  history.pushState = function (...args) {
+    originalPushState(...args);
+    notifyNavigation();
+  };
+
+  history.replaceState = function (...args) {
+    originalReplaceState(...args);
+    notifyNavigation();
+  };
+
+  window.addEventListener('popstate', () => {
+    notifyNavigation();
+  });
+}
+
+function notifyNavigation(): void {
+  post({ type: 'rangka-client:navigate', path: window.location.pathname });
+}
+
+function post(msg: ClientToStudioMessage): void {
+  window.parent.postMessage(msg, '*');
+}
+
+function getMeasurableRect(el: HTMLElement): DOMRect {
+  const rect = el.getBoundingClientRect();
+  if (rect.width > 0 && rect.height > 0) return rect;
+  // display:contents elements have no box — measure first child instead
+  const child = el.firstElementChild as HTMLElement | null;
+  if (child) return child.getBoundingClientRect();
+  return rect;
+}

package/src/studio/index.ts

@@ -0,0 +1,3 @@
+import { initBridge } from './bridge.js';
+
+initBridge();

package/src/studio/overlay.ts

@@ -0,0 +1,47 @@
+let overlay: HTMLElement | null = null;
+
+export function createOverlay(): HTMLElement {
+  if (overlay) return overlay;
+
+  overlay = document.createElement('div');
+  overlay.id = 'rangka-studio-overlay';
+  Object.assign(overlay.style, {
+    position: 'fixed',
+    pointerEvents: 'none',
+    zIndex: '99999',
+    border: '2px solid hsl(221 83% 53%)',
+    background: 'hsl(221 83% 53% / 0.08)',
+    borderRadius: '4px',
+    display: 'none',
+  });
+  document.body.appendChild(overlay);
+  return overlay;
+}
+
+export function updateOverlay(rect: {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}): void {
+  if (!overlay) return;
+  overlay.style.top = `${rect.top}px`;
+  overlay.style.left = `${rect.left}px`;
+  overlay.style.width = `${rect.width}px`;
+  overlay.style.height = `${rect.height}px`;
+}
+
+export function showOverlay(): void {
+  if (overlay) overlay.style.display = 'block';
+}
+
+export function hideOverlay(): void {
+  if (overlay) overlay.style.display = 'none';
+}
+
+export function destroyOverlay(): void {
+  if (overlay) {
+    overlay.remove();
+    overlay = null;
+  }
+}

package/src/studio/types.ts

@@ -0,0 +1,32 @@
+export type StudioToClientMessage =
+  | { type: 'rangka-studio:inspect-start' }
+  | { type: 'rangka-studio:inspect-stop' }
+  | { type: 'rangka-studio:pong'; inspecting: boolean };
+
+export type ClientToStudioMessage =
+  | { type: 'rangka-client:ready' }
+  | { type: 'rangka-client:ping' }
+  | { type: 'rangka-client:hover'; widgetPath: string[]; rect: WidgetRect; pageKey?: string }
+  | { type: 'rangka-client:hover-out' }
+  | {
+      type: 'rangka-client:select';
+      widgetPath: string[];
+      meta: WidgetInspectMeta;
+      pageKey?: string;
+    }
+  | { type: 'rangka-client:navigate'; path: string };
+
+export interface WidgetRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+export interface WidgetInspectMeta {
+  type: string;
+  id?: string;
+  model?: string;
+  field?: string;
+  mode?: string;
+}

package/src/studio/walker.ts

@@ -0,0 +1,48 @@
+import type { WidgetInspectMeta } from './types.js';
+
+export function findWidgetElement(el: HTMLElement): HTMLElement | null {
+  let current: HTMLElement | null = el;
+  while (current) {
+    if (current.hasAttribute('data-rangka-widget')) return current;
+    current = current.parentElement;
+  }
+  return null;
+}
+
+export function buildWidgetPath(el: HTMLElement): string[] {
+  const segments: string[] = [];
+  let current: HTMLElement | null = el;
+
+  while (current) {
+    if (current.hasAttribute('data-rangka-widget')) {
+      const id = current.getAttribute('data-rangka-id');
+      const type = current.getAttribute('data-rangka-widget')!;
+      segments.push(id || type);
+    }
+    current = current.parentElement;
+  }
+
+  segments.reverse();
+  return segments;
+}
+
+export function findPageKey(el: HTMLElement): string | undefined {
+  let current: HTMLElement | null = el;
+  while (current) {
+    if (current.hasAttribute('data-page-key')) {
+      return current.getAttribute('data-page-key') ?? undefined;
+    }
+    current = current.parentElement;
+  }
+  return undefined;
+}
+
+export function extractMeta(el: HTMLElement): WidgetInspectMeta {
+  return {
+    type: el.getAttribute('data-rangka-widget') ?? '',
+    id: el.getAttribute('data-rangka-id') ?? undefined,
+    model: el.getAttribute('data-rangka-model') ?? undefined,
+    field: el.getAttribute('data-rangka-field') ?? undefined,
+    mode: el.getAttribute('data-rangka-mode') ?? undefined,
+  };
+}

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/widgets/__tests__/action-edge-cases.test.ts

@@ -0,0 +1,281 @@
+import { describe, test, expect, vi } from 'vitest';
+import { dispatch } from '../action/dispatcher.js';
+import { StateStore } from '../state/store.js';
+import { createRootContext } from '../context/builder.js';
+import type { ActionContext, ActionHandlers } from '../action/dispatcher.js';
+
+function makeActionCtx(record: Record<string, unknown> = {}): ActionContext {
+  return {
+    widgetContext: createRootContext(record, 'sales.order', 'edit'),
+    state: new StateStore(),
+  };
+}
+
+describe('Action Edge Cases', () => {
+  describe('setValue edge cases', () => {
+    test('sets $state with expression referencing record', async () => {
+      const ctx = makeActionCtx({ total: 500 });
+      await dispatch(
+        { type: 'setValue', field: '$state.hasTotal', value: '{{total > 0}}' },
+        ctx,
+        {},
+      );
+      expect(ctx.state.get('hasTotal')).toBe(true);
+    });
+
+    test('sets literal boolean value without expression', async () => {
+      const ctx = makeActionCtx();
+      await dispatch({ type: 'setValue', field: '$state.loading', value: true }, ctx, {});
+      expect(ctx.state.get('loading')).toBe(true);
+    });
+
+    test('sets literal null value', async () => {
+      const sets: [string, unknown][] = [];
+      const handlers: ActionHandlers = { setRecordValue: (f, v) => sets.push([f, v]) };
+      await dispatch({ type: 'setValue', field: 'name', value: null }, makeActionCtx(), handlers);
+      expect(sets).toEqual([['name', null]]);
+    });
+
+    test('sets literal number value', async () => {
+      const sets: [string, unknown][] = [];
+      const handlers: ActionHandlers = { setRecordValue: (f, v) => sets.push([f, v]) };
+      await dispatch({ type: 'setValue', field: 'count', value: 0 }, makeActionCtx(), handlers);
+      expect(sets).toEqual([['count', 0]]);
+    });
+
+    test('string without expression is literal', async () => {
+      const sets: [string, unknown][] = [];
+      const handlers: ActionHandlers = { setRecordValue: (f, v) => sets.push([f, v]) };
+      await dispatch(
+        { type: 'setValue', field: 'status', value: 'draft' },
+        makeActionCtx(),
+        handlers,
+      );
+      expect(sets).toEqual([['status', 'draft']]);
+    });
+  });
+
+  describe('setValues edge cases', () => {
+    test('mix of $state and record with expressions', async () => {
+      const sets: [string, unknown][] = [];
+      const handlers: ActionHandlers = { setRecordValue: (f, v) => sets.push([f, v]) };
+      const ctx = makeActionCtx({ qty: 5, rate: 10 });
+      await dispatch(
+        {
+          type: 'setValues',
+          values: {
+            total: '{{qty * rate}}',
+            '$state.calculated': true,
+            status: 'calculated',
+          },
+        },
+        ctx,
+        handlers,
+      );
+      expect(sets).toEqual([
+        ['total', 50],
+        ['status', 'calculated'],
+      ]);
+      expect(ctx.state.get('calculated')).toBe(true);
+    });
+
+    test('empty values object does nothing', async () => {
+      const ctx = makeActionCtx();
+      await dispatch({ type: 'setValues', values: {} }, ctx, {});
+      expect(ctx.state.keys()).toEqual([]);
+    });
+  });
+
+  describe('navigate edge cases', () => {
+    test('static path without expression', async () => {
+      const paths: string[] = [];
+      const handlers: ActionHandlers = { navigate: (p) => paths.push(p) };
+      await dispatch({ type: 'navigate', path: '/dashboard' }, makeActionCtx(), handlers);
+      expect(paths).toEqual(['/dashboard']);
+    });
+
+    test('path with multiple expressions', async () => {
+      const paths: string[] = [];
+      const handlers: ActionHandlers = { navigate: (p) => paths.push(p) };
+      const ctx = makeActionCtx({ module: 'sales', id: '42' });
+      await dispatch({ type: 'navigate', path: '/{{module}}/orders/{{id}}' }, ctx, handlers);
+      expect(paths).toEqual(['/sales/orders/42']);
+    });
+  });
+
+  describe('service edge cases', () => {
+    test('service with no params', async () => {
+      const serviceCall = vi.fn().mockResolvedValue({});
+      const handlers: ActionHandlers = { service: serviceCall, refreshSource: vi.fn() };
+      await dispatch({ type: 'service', name: 'sales.refresh' }, makeActionCtx(), handlers);
+      expect(serviceCall).toHaveBeenCalledWith('sales.refresh', {});
+    });
+
+    test('$response is available in nested onSuccess actions', async () => {
+      const serviceCall = vi.fn().mockResolvedValue({ id: 'new-1', status: 'created' });
+      const paths: string[] = [];
+      const handlers: ActionHandlers = {
+        service: serviceCall,
+        navigate: (p) => paths.push(p),
+      };
+      await dispatch(
+        {
+          type: 'service',
+          name: 'sales.create',
+          onSuccess: { type: 'navigate', path: '/orders/{{$response.id}}' },
+        },
+        makeActionCtx(),
+        handlers,
+      );
+      expect(paths).toEqual(['/orders/new-1']);
+    });
+
+    test('service failure without onError does not throw', async () => {
+      const serviceCall = vi.fn().mockRejectedValue(new Error('fail'));
+      const handlers: ActionHandlers = { service: serviceCall };
+      await expect(
+        dispatch({ type: 'service', name: 'sales.fail' }, makeActionCtx(), handlers),
+      ).resolves.toBeUndefined();
+    });
+  });
+
+  describe('sequence edge cases', () => {
+    test('empty sequence does nothing', async () => {
+      await expect(
+        dispatch({ type: 'sequence', actions: [] }, makeActionCtx(), {}),
+      ).resolves.toBeUndefined();
+    });
+
+    test('sequence of $state writes accumulates', async () => {
+      const ctx = makeActionCtx();
+      await dispatch(
+        {
+          type: 'sequence',
+          actions: [
+            { type: 'setValue', field: '$state.a', value: 1 },
+            { type: 'setValue', field: '$state.b', value: 2 },
+            { type: 'setValue', field: '$state.c', value: 3 },
+          ],
+        },
+        ctx,
+        {},
+      );
+      expect(ctx.state.get('a')).toBe(1);
+      expect(ctx.state.get('b')).toBe(2);
+      expect(ctx.state.get('c')).toBe(3);
+    });
+
+    test('later actions in sequence see earlier state changes', async () => {
+      const ctx = makeActionCtx();
+      await dispatch(
+        {
+          type: 'sequence',
+          actions: [
+            { type: 'setValue', field: '$state.step', value: 1 },
+            {
+              type: 'conditional',
+              condition: { field: '$state.step', operator: 'eq', value: 1 },
+              then: { type: 'setValue', field: '$state.result', value: 'step1-done' },
+            },
+          ],
+        },
+        ctx,
+        {},
+      );
+      expect(ctx.state.get('result')).toBe('step1-done');
+    });
+  });
+
+  describe('conditional edge cases', () => {
+    test('conditional without else does nothing on false', async () => {
+      const ctx = makeActionCtx({ status: 'submitted' });
+      const sets: [string, unknown][] = [];
+      const handlers: ActionHandlers = { setRecordValue: (f, v) => sets.push([f, v]) };
+      await dispatch(
+        {
+          type: 'conditional',
+          condition: { field: 'status', operator: 'eq', value: 'draft' },
+          then: { type: 'setValue', field: 'x', value: 1 },
+        },
+        ctx,
+        handlers,
+      );
+      expect(sets).toEqual([]);
+    });
+
+    test('nested conditionals', async () => {
+      const ctx = makeActionCtx({ a: 1, b: 2 });
+      await dispatch(
+        {
+          type: 'conditional',
+          condition: { field: 'a', operator: 'eq', value: 1 },
+          then: {
+            type: 'conditional',
+            condition: { field: 'b', operator: 'eq', value: 2 },
+            then: { type: 'setValue', field: '$state.result', value: 'both' },
+            else: { type: 'setValue', field: '$state.result', value: 'only-a' },
+          },
+          else: { type: 'setValue', field: '$state.result', value: 'neither' },
+        },
+        ctx,
+        {},
+      );
+      expect(ctx.state.get('result')).toBe('both');
+    });
+  });
+
+  describe('model action edge cases', () => {
+    test('model.update with explicit model and id overrides context', async () => {
+      const modelUpdate = vi.fn().mockResolvedValue({});
+      const handlers: ActionHandlers = { modelUpdate };
+      const ctx = makeActionCtx({ id: '1' });
+      await dispatch(
+        {
+          type: 'model.update',
+          model: 'other.model',
+          id: '99',
+          data: { name: 'test' },
+        },
+        ctx,
+        handlers,
+      );
+      expect(modelUpdate).toHaveBeenCalledWith('other.model', '99', { name: 'test' });
+    });
+
+    test('model.delete with explicit id from expression', async () => {
+      const modelDelete = vi.fn().mockResolvedValue(undefined);
+      const handlers: ActionHandlers = { modelDelete };
+      const ctx = makeActionCtx({ selectedId: '55' });
+      await dispatch(
+        {
+          type: 'model.delete',
+          model: 'sales.order',
+          id: '{{selectedId}}',
+        },
+        ctx,
+        handlers,
+      );
+      expect(modelDelete).toHaveBeenCalledWith('sales.order', '55');
+    });
+  });
+
+  describe('handler missing gracefully', () => {
+    test('navigate without handler does not throw', async () => {
+      await expect(
+        dispatch({ type: 'navigate', path: '/test' }, makeActionCtx(), {}),
+      ).resolves.toBeUndefined();
+    });
+
+    test('refreshSource without handler does not throw', async () => {
+      await expect(
+        dispatch({ type: 'refreshSource' }, makeActionCtx(), {}),
+      ).resolves.toBeUndefined();
+    });
+
+    test('service without handler does not throw', async () => {
+      await expect(
+        dispatch({ type: 'service', name: 'test' }, makeActionCtx(), {}),
+      ).resolves.toBeUndefined();
+    });
+  });
+});