@rangka/client 0.0.1

package/src/widgets/__tests__/validator.test.ts

@@ -0,0 +1,208 @@
+import { describe, test, expect } from 'vitest';
+import { validateWidgetTree } from '../validation/validator.js';
+import type { WidgetDefinitionMeta, WidgetNode } from '@rangka/shared';
+
+function makeRegistry(defs: WidgetDefinitionMeta[]): Map<string, WidgetDefinitionMeta> {
+  return new Map(defs.map((d) => [d.name, d]));
+}
+
+const buttonDef: WidgetDefinitionMeta = {
+  name: 'button',
+  label: 'Button',
+  category: 'action',
+  schema: {
+    label: { type: 'string', required: true },
+    variant: {
+      type: 'enum',
+      options: ['primary', 'secondary', 'ghost', 'danger'],
+      default: 'secondary',
+    },
+    size: { type: 'enum', options: ['sm', 'md', 'lg'], default: 'md' },
+  },
+  binding: 'none',
+  triggers: ['click'],
+  container: false,
+};
+
+const inputDef: WidgetDefinitionMeta = {
+  name: 'input',
+  label: 'Input',
+  category: 'input',
+  schema: {
+    label: { type: 'string' },
+    placeholder: { type: 'string' },
+    readOnly: { type: 'boolean' },
+  },
+  binding: 'field',
+  triggers: ['change', 'focus', 'blur'],
+  container: false,
+};
+
+const groupDef: WidgetDefinitionMeta = {
+  name: 'group',
+  label: 'Group',
+  category: 'layout',
+  schema: {
+    direction: { type: 'enum', options: ['row', 'column'], default: 'column' },
+    gap: { type: 'enum', options: ['sm', 'md', 'lg'], default: 'md' },
+  },
+  binding: 'none',
+  triggers: [],
+  container: true,
+};
+
+const tableDef: WidgetDefinitionMeta = {
+  name: 'table',
+  label: 'Table',
+  category: 'layout',
+  schema: {
+    selectable: { type: 'boolean' },
+    pageSize: { type: 'number' },
+  },
+  binding: 'model',
+  triggers: ['rowClick', 'select', 'pageChange'],
+  container: true,
+  accepts: ['column'],
+};
+
+const columnDef: WidgetDefinitionMeta = {
+  name: 'column',
+  label: 'Column',
+  category: 'layout',
+  schema: {
+    label: { type: 'string', required: true },
+    width: { type: 'string' },
+  },
+  binding: 'none',
+  triggers: [],
+  container: true,
+};
+
+const registry = makeRegistry([buttonDef, inputDef, groupDef, tableDef, columnDef]);
+
+describe('Widget Tree Validator', () => {
+  test('valid tree produces no errors', () => {
+    const nodes: WidgetNode[] = [
+      { type: 'button', props: { label: 'Click me' } },
+      { type: 'input', bind: { field: 'name' } },
+    ];
+    expect(validateWidgetTree(nodes, registry)).toEqual([]);
+  });
+
+  test('rejects unknown widget type', () => {
+    const nodes: WidgetNode[] = [{ type: 'unknown_widget' }];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Unknown widget type: 'unknown_widget'");
+  });
+
+  test('rejects children on non-container', () => {
+    const nodes: WidgetNode[] = [
+      { type: 'button', props: { label: 'test' }, children: [{ type: 'input' }] },
+    ];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes('not a container'))).toBe(true);
+  });
+
+  test('rejects disallowed child types (accepts list)', () => {
+    const nodes: WidgetNode[] = [
+      {
+        type: 'table',
+        bind: { model: { name: 'test' } },
+        children: [{ type: 'button', props: { label: 'bad' } }],
+      },
+    ];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes('does not accept child type'))).toBe(true);
+  });
+
+  test('allows valid child types', () => {
+    const nodes: WidgetNode[] = [
+      {
+        type: 'table',
+        bind: { model: { name: 'test' } },
+        children: [{ type: 'column', props: { label: 'Name' } }],
+      },
+    ];
+    expect(validateWidgetTree(nodes, registry)).toEqual([]);
+  });
+
+  test('rejects unknown prop', () => {
+    const nodes: WidgetNode[] = [{ type: 'button', props: { label: 'test', unknownProp: true } }];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes("Unknown prop 'unknownProp'"))).toBe(true);
+  });
+
+  test('rejects invalid prop type', () => {
+    const nodes: WidgetNode[] = [{ type: 'button', props: { label: 123 } }];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes("Invalid value for prop 'label'"))).toBe(true);
+  });
+
+  test('rejects invalid enum value', () => {
+    const nodes: WidgetNode[] = [{ type: 'button', props: { label: 'test', variant: 'invalid' } }];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes("Invalid value for prop 'variant'"))).toBe(true);
+  });
+
+  test('allows expression strings in props', () => {
+    const nodes: WidgetNode[] = [
+      { type: 'button', props: { label: '{{$state.label}}', variant: 'primary' } },
+    ];
+    expect(validateWidgetTree(nodes, registry)).toEqual([]);
+  });
+
+  test('reports missing required prop', () => {
+    const nodes: WidgetNode[] = [{ type: 'button', props: { variant: 'primary' } }];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes("Missing required prop 'label'"))).toBe(true);
+  });
+
+  test('reports missing required prop when no props at all', () => {
+    const nodes: WidgetNode[] = [{ type: 'button' }];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes("Missing required prop 'label'"))).toBe(true);
+  });
+
+  test('rejects unknown trigger in on', () => {
+    const nodes: WidgetNode[] = [
+      { type: 'button', props: { label: 'test' }, on: { hover: { type: 'navigate', path: '/' } } },
+    ];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes("Unknown trigger 'hover'"))).toBe(true);
+  });
+
+  test('allows valid trigger', () => {
+    const nodes: WidgetNode[] = [
+      { type: 'button', props: { label: 'test' }, on: { click: { type: 'navigate', path: '/' } } },
+    ];
+    expect(validateWidgetTree(nodes, registry)).toEqual([]);
+  });
+
+  test('rejects binding on widget that does not support it', () => {
+    const nodes: WidgetNode[] = [
+      { type: 'button', props: { label: 'test' }, bind: { field: 'name' } },
+    ];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors.some((e) => e.message.includes('does not support data binding'))).toBe(true);
+  });
+
+  test('rejects wrong binding mode', () => {
+    const nodes: WidgetNode[] = [{ type: 'input', bind: { model: { name: 'sales.order' } } }];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(
+      errors.some((e) => e.message.includes("expects binding mode 'field' but got 'model'")),
+    ).toBe(true);
+  });
+
+  test('reports error path correctly for nested widgets', () => {
+    const nodes: WidgetNode[] = [
+      {
+        type: 'group',
+        children: [{ type: 'button', props: { label: 'ok' } }, { type: 'unknown_type' }],
+      },
+    ];
+    const errors = validateWidgetTree(nodes, registry);
+    expect(errors[0].path).toBe('[0].children[1]');
+  });
+});

package/src/widgets/action/dispatcher.ts

@@ -0,0 +1,334 @@
+import type { WidgetAction } from '@rangka/shared';
+import type { WidgetContext } from '../context/types.js';
+import type { StateStore } from '../state/store.js';
+import { parse, evaluate } from '../expression/index.js';
+import { flattenContext } from '../context/types.js';
+
+export interface ActionContext {
+  widgetContext: WidgetContext;
+  state: StateStore;
+  response?: Record<string, unknown>;
+  selected?: Record<string, unknown>;
+}
+
+export interface ActionHandlers {
+  navigate?: (path: string) => void;
+  service?: (name: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  refreshSource?: () => void;
+  focus?: (field: string) => void;
+  fetchOptions?: (field: string, depends: string[]) => void;
+  validate?: (fields?: string[]) => Promise<boolean>;
+  modelCreate?: (model: string, data: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  modelUpdate?: (
+    model: string,
+    id: string,
+    data: Record<string, unknown>,
+  ) => Promise<Record<string, unknown>>;
+  modelDelete?: (model: string, id: string) => Promise<void>;
+  modelFetch?: (model: string, id: string) => Promise<Record<string, unknown>>;
+  modelList?: (
+    model: string,
+    filters?: Record<string, unknown>,
+  ) => Promise<Record<string, unknown>[]>;
+  setRecordValue?: (field: string, value: unknown) => void;
+  addRow?: (field: string) => void;
+  removeRow?: (field: string) => void;
+  duplicateRow?: (field: string) => void;
+  formSubmit?: () => Promise<void>;
+  formReset?: () => void;
+}
+
+export async function dispatch(
+  action: WidgetAction,
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  switch (action.type) {
+    case 'setValue':
+      return handleSetValue(action.field, action.value, actionCtx, handlers);
+    case 'clearValue':
+      return handleSetValue(action.field, null, actionCtx, handlers);
+    case 'setValues':
+      return handleSetValues(action.values, actionCtx, handlers);
+    case 'navigate':
+      return handleNavigate(action.path, actionCtx, handlers);
+    case 'service':
+      return handleService(action, actionCtx, handlers);
+    case 'refreshSource':
+      handlers.refreshSource?.();
+      return;
+    case 'focus':
+      handlers.focus?.(action.field);
+      return;
+    case 'fetchOptions':
+      handlers.fetchOptions?.(action.field, action.depends);
+      return;
+    case 'validate':
+      await handlers.validate?.(action.fields);
+      return;
+    case 'model.create':
+      return handleModelCreate(action, actionCtx, handlers);
+    case 'model.update':
+      return handleModelUpdate(action, actionCtx, handlers);
+    case 'model.delete':
+      return handleModelDelete(action, actionCtx, handlers);
+    case 'model.fetch':
+      return handleModelFetch(action, actionCtx, handlers);
+    case 'model.list':
+      return handleModelList(action, actionCtx, handlers);
+    case 'addRow':
+      handlers.addRow?.(action.field);
+      return;
+    case 'removeRow':
+      handlers.removeRow?.(action.field);
+      return;
+    case 'duplicateRow':
+      handlers.duplicateRow?.(action.field);
+      return;
+    case 'form.submit':
+      await handlers.formSubmit?.();
+      return;
+    case 'form.reset':
+      handlers.formReset?.();
+      return;
+    case 'sequence':
+      return handleSequence(action.actions, actionCtx, handlers);
+    case 'conditional':
+      return handleConditional(action, actionCtx, handlers);
+  }
+}
+
+function handleSetValue(
+  field: string,
+  value: unknown,
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): void {
+  const resolved = resolveExpressionValue(value, actionCtx);
+
+  if (field.startsWith('$state.')) {
+    const key = field.slice(7);
+    actionCtx.state.set(key, resolved);
+  } else if (
+    field.startsWith('$filter.') ||
+    field.startsWith('$sort.') ||
+    field.startsWith('$page.')
+  ) {
+    // Reactive query variables are stored with their full key (including prefix)
+    actionCtx.state.set(field, resolved);
+  } else if (field.startsWith('$parent.')) {
+    const realField = field.slice(8);
+    handlers.setRecordValue?.(realField, resolved);
+  } else {
+    actionCtx.widgetContext.record[field] = resolved;
+    handlers.setRecordValue?.(field, resolved);
+  }
+}
+
+function handleSetValues(
+  values: Record<string, unknown>,
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): void {
+  const stateUpdates: Record<string, unknown> = {};
+
+  for (const [field, value] of Object.entries(values)) {
+    const resolved = resolveExpressionValue(value, actionCtx);
+    if (field.startsWith('$state.')) {
+      stateUpdates[field.slice(7)] = resolved;
+    } else if (
+      field.startsWith('$filter.') ||
+      field.startsWith('$sort.') ||
+      field.startsWith('$page.')
+    ) {
+      // Reactive query variables stored with full key
+      stateUpdates[field] = resolved;
+    } else {
+      handlers.setRecordValue?.(field, resolved);
+    }
+  }
+
+  if (Object.keys(stateUpdates).length > 0) {
+    actionCtx.state.setMany(stateUpdates);
+  }
+}
+
+function handleNavigate(path: string, actionCtx: ActionContext, handlers: ActionHandlers): void {
+  const resolved = String(resolveExpressionValue(path, actionCtx) ?? path);
+  handlers.navigate?.(resolved);
+}
+
+async function handleService(
+  action: {
+    type: 'service';
+    name: string;
+    params?: Record<string, unknown>;
+    context?: string;
+    onSuccess?: WidgetAction;
+    onError?: WidgetAction;
+  },
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  const params: Record<string, unknown> = {};
+  if (action.params) {
+    for (const [key, value] of Object.entries(action.params)) {
+      params[key] = resolveExpressionValue(value, actionCtx);
+    }
+  }
+
+  try {
+    const response = await handlers.service?.(action.name, params);
+    if (action.onSuccess) {
+      const successCtx: ActionContext = {
+        ...actionCtx,
+        response: response ?? {},
+      };
+      await dispatch(action.onSuccess, successCtx, handlers);
+    } else {
+      handlers.refreshSource?.();
+    }
+  } catch (err) {
+    if (action.onError) {
+      const errorCtx: ActionContext = {
+        ...actionCtx,
+        response: err instanceof Error ? { message: err.message } : { message: String(err) },
+      };
+      await dispatch(action.onError, errorCtx, handlers);
+    }
+  }
+}
+
+async function handleModelCreate(
+  action: { type: 'model.create'; model: string; data: Record<string, unknown> },
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  const data: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(action.data)) {
+    data[key] = resolveExpressionValue(value, actionCtx);
+  }
+  await handlers.modelCreate?.(action.model, data);
+}
+
+async function handleModelUpdate(
+  action: { type: 'model.update'; model?: string; id?: string; data: Record<string, unknown> },
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  const model = action.model ?? actionCtx.widgetContext.model;
+  const id = action.id
+    ? String(resolveExpressionValue(action.id, actionCtx))
+    : String(actionCtx.widgetContext.record['id'] ?? '');
+  const data: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(action.data)) {
+    data[key] = resolveExpressionValue(value, actionCtx);
+  }
+  await handlers.modelUpdate?.(model, id, data);
+}
+
+async function handleModelDelete(
+  action: { type: 'model.delete'; model?: string; id?: string },
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  const model = action.model ?? actionCtx.widgetContext.model;
+  const id = action.id
+    ? String(resolveExpressionValue(action.id, actionCtx))
+    : String(actionCtx.widgetContext.record['id'] ?? '');
+  await handlers.modelDelete?.(model, id);
+}
+
+async function handleModelFetch(
+  action: { type: 'model.fetch'; model: string; id: string; into: string },
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  const id = String(resolveExpressionValue(action.id, actionCtx));
+  const result = await handlers.modelFetch?.(action.model, id);
+  if (result && action.into === '$record') {
+    for (const [key, value] of Object.entries(result)) {
+      handlers.setRecordValue?.(key, value);
+    }
+  }
+}
+
+async function handleModelList(
+  action: { type: 'model.list'; model: string; filters?: Record<string, unknown>; into: string },
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  const filters: Record<string, unknown> = {};
+  if (action.filters) {
+    for (const [key, value] of Object.entries(action.filters)) {
+      filters[key] = resolveExpressionValue(value, actionCtx);
+    }
+  }
+  await handlers.modelList?.(action.model, filters);
+}
+
+async function handleSequence(
+  actions: WidgetAction[],
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  for (const action of actions) {
+    await dispatch(action, actionCtx, handlers);
+  }
+}
+
+async function handleConditional(
+  action: {
+    type: 'conditional';
+    condition: { field: string; operator: string; value?: unknown };
+    then: WidgetAction;
+    else?: WidgetAction;
+  },
+  actionCtx: ActionContext,
+  handlers: ActionHandlers,
+): Promise<void> {
+  const { evaluateCondition } = await import('../condition/evaluator.js');
+  const flat = flattenContext(actionCtx.widgetContext);
+  const merged = {
+    ...flat,
+    $state: Object.fromEntries(actionCtx.state.keys().map((k) => [k, actionCtx.state.get(k)])),
+  };
+  const result = evaluateCondition(
+    action.condition as Parameters<typeof evaluateCondition>[0],
+    merged,
+  );
+  if (result) {
+    await dispatch(action.then, actionCtx, handlers);
+  } else if (action.else) {
+    await dispatch(action.else, actionCtx, handlers);
+  }
+}
+
+export function resolveExpressionValue(value: unknown, actionCtx: ActionContext): unknown {
+  if (typeof value !== 'string') return value;
+  if (!value.includes('{{')) return value;
+
+  const flat = flattenContext(actionCtx.widgetContext);
+  const merged: Record<string, unknown> = {
+    ...flat,
+    $state: Object.fromEntries(actionCtx.state.keys().map((k) => [k, actionCtx.state.get(k)])),
+  };
+  if (actionCtx.response) {
+    merged['$response'] = actionCtx.response;
+  }
+  if (actionCtx.selected) {
+    merged['$selected'] = actionCtx.selected;
+  }
+
+  const trimmed = value.trim();
+  if (trimmed.startsWith('{{') && trimmed.endsWith('}}') && !trimmed.slice(2, -2).includes('{{')) {
+    const ast = parse(trimmed);
+    return evaluate(ast, merged);
+  }
+
+  return value.replace(/\{\{(.+?)\}\}/g, (_match, expr: string) => {
+    const ast = parse(expr.trim());
+    const result = evaluate(ast, merged);
+    return String(result ?? '');
+  });
+}

package/src/widgets/action/index.ts

@@ -0,0 +1,2 @@
+export { dispatch, resolveExpressionValue } from './dispatcher.js';
+export type { ActionContext, ActionHandlers } from './dispatcher.js';

package/src/widgets/binding/index.ts

@@ -0,0 +1,2 @@
+export { resolveBinding } from './resolver.js';
+export type { BindingResult, FieldMeta } from './resolver.js';

package/src/widgets/binding/resolver.ts

@@ -0,0 +1,61 @@
+import type { WidgetBinding } from '@rangka/shared';
+import type { WidgetContext } from '../context/types.js';
+import type { StateStore } from '../state/store.js';
+import { parse, evaluate } from '../expression/index.js';
+import { flattenContext } from '../context/types.js';
+
+export interface FieldMeta {
+  type: string;
+  label: string;
+  required: boolean;
+  options?: unknown[];
+  readOnly: boolean;
+}
+
+export interface BindingResult {
+  value: unknown;
+  setValue?: (val: unknown) => void;
+  meta?: FieldMeta;
+  error?: string;
+  query?: { name: string; filters?: Record<string, unknown>; limit?: number };
+}
+
+export function resolveBinding(
+  bind: WidgetBinding | undefined,
+  context: WidgetContext,
+  fieldMeta?: Record<string, FieldMeta>,
+  setValue?: (field: string, val: unknown) => void,
+  state?: StateStore,
+): BindingResult | null {
+  if (!bind) return null;
+
+  if (bind.field) {
+    const value = context.record[bind.field];
+    const meta = fieldMeta?.[bind.field];
+    return {
+      value,
+      setValue: setValue ? (val: unknown) => setValue(bind.field!, val) : undefined,
+      meta,
+    };
+  }
+
+  if (bind.expression) {
+    const flat = flattenContext(context);
+    const merged: Record<string, unknown> = { ...flat };
+    if (state) {
+      merged['$state'] = Object.fromEntries(state.keys().map((k) => [k, state.get(k)]));
+    }
+    const ast = parse(bind.expression);
+    const value = evaluate(ast, merged);
+    return { value };
+  }
+
+  if (bind.model) {
+    return {
+      value: null,
+      query: bind.model,
+    };
+  }
+
+  return null;
+}