@rangka/client 0.0.1

package/src/widgets/reactivity/tracker.ts

@@ -0,0 +1,139 @@
+import type { WidgetNode, Condition } from '@rangka/shared';
+import { parse } from '../expression/parser.js';
+import type { AstNode } from '../expression/types.js';
+
+export interface DependencyMap {
+  fields: Map<string, Set<string>>;
+  state: Map<string, Set<string>>;
+}
+
+export function buildDependencyMap(nodes: WidgetNode[], parentPath: string = ''): DependencyMap {
+  const fields = new Map<string, Set<string>>();
+  const state = new Map<string, Set<string>>();
+
+  function addDep(map: Map<string, Set<string>>, key: string, widgetId: string): void {
+    let set = map.get(key);
+    if (!set) {
+      set = new Set();
+      map.set(key, set);
+    }
+    set.add(widgetId);
+  }
+
+  function walkNodes(nodes: WidgetNode[], path: string): void {
+    nodes.forEach((node, index) => {
+      const widgetId = node.id ?? `${path}[${index}]`;
+
+      if (node.bind?.field) {
+        addDep(fields, node.bind.field, widgetId);
+      }
+
+      if (node.bind?.expression) {
+        const deps = extractDepsFromExpression(node.bind.expression);
+        for (const dep of deps.fields) addDep(fields, dep, widgetId);
+        for (const dep of deps.state) addDep(state, dep, widgetId);
+      }
+
+      if (node.visible) {
+        const conditions = Array.isArray(node.visible) ? node.visible : [node.visible];
+        for (const condition of conditions) {
+          const deps = extractDepsFromCondition(condition);
+          for (const dep of deps.fields) addDep(fields, dep, widgetId);
+          for (const dep of deps.state) addDep(state, dep, widgetId);
+        }
+      }
+
+      if (node.props) {
+        for (const value of Object.values(node.props)) {
+          if (typeof value === 'string' && value.includes('{{')) {
+            const deps = extractDepsFromExpression(value);
+            for (const dep of deps.fields) addDep(fields, dep, widgetId);
+            for (const dep of deps.state) addDep(state, dep, widgetId);
+          }
+        }
+      }
+
+      if (node.children) {
+        walkNodes(node.children, `${widgetId}.children`);
+      }
+    });
+  }
+
+  walkNodes(nodes, parentPath);
+  return { fields, state };
+}
+
+export function getAffectedWidgets(
+  depMap: DependencyMap,
+  key: string,
+  isState: boolean,
+): Set<string> {
+  const map = isState ? depMap.state : depMap.fields;
+  return map.get(key) ?? new Set();
+}
+
+interface ExtractedDeps {
+  fields: string[];
+  state: string[];
+}
+
+function extractDepsFromExpression(expr: string): ExtractedDeps {
+  const fields: string[] = [];
+  const state: string[] = [];
+
+  try {
+    const ast = parse(expr);
+    walkAst(ast, fields, state);
+  } catch {
+    // skip unparseable expressions
+  }
+
+  return { fields, state };
+}
+
+function extractDepsFromCondition(condition: Condition): ExtractedDeps {
+  const fields: string[] = [];
+  const state: string[] = [];
+
+  const field = condition.field;
+  if (field.startsWith('$state.')) {
+    state.push(field.slice(7));
+  } else if (!field.startsWith('$')) {
+    fields.push(field.split('.')[0]);
+  }
+
+  if (typeof condition.value === 'string' && condition.value.includes('{{')) {
+    const deps = extractDepsFromExpression(condition.value);
+    fields.push(...deps.fields);
+    state.push(...deps.state);
+  }
+
+  return { fields, state };
+}
+
+function walkAst(node: AstNode, fields: string[], state: string[]): void {
+  switch (node.type) {
+    case 'field': {
+      if (node.path[0] === '$state' && node.path.length > 1) {
+        state.push(node.path[1]);
+      } else if (!node.path[0].startsWith('$')) {
+        fields.push(node.path[0]);
+      }
+      break;
+    }
+    case 'binary':
+      walkAst(node.left, fields, state);
+      walkAst(node.right, fields, state);
+      break;
+    case 'unary':
+      walkAst(node.operand, fields, state);
+      break;
+    case 'call':
+      for (const arg of node.args) {
+        walkAst(arg, fields, state);
+      }
+      break;
+    case 'literal':
+      break;
+  }
+}

package/src/widgets/reactivity/variables.ts

@@ -0,0 +1,213 @@
+/**
+ * Reactive variable parsing helpers for $filter, $sort, $page namespaces.
+ *
+ * These variables are stored in the same flat StateStore as $state keys.
+ * The store keys use the full prefix (e.g. "$filter.sales.order.status__gt").
+ * These helpers parse those keys into structured query parameters.
+ */
+
+export type FilterOperator =
+  | 'eq'
+  | 'in'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'like'
+  | 'empty'
+  | 'not_empty';
+
+export interface ParsedFilterKey {
+  model: string;
+  field: string;
+  operator: FilterOperator;
+}
+
+export interface ParsedFilter {
+  model: string;
+  field: string;
+  operator: FilterOperator;
+  value: unknown;
+}
+
+export interface SortEntry {
+  field: string;
+  direction: 'asc' | 'desc';
+}
+
+const OPERATOR_SUFFIXES: Record<string, FilterOperator> = {
+  __gt: 'gt',
+  __gte: 'gte',
+  __lt: 'lt',
+  __lte: 'lte',
+  __like: 'like',
+  __empty: 'empty',
+  __not_empty: 'not_empty',
+};
+
+const FILTER_PREFIX = '$filter.';
+const SORT_PREFIX = '$sort.';
+const PAGE_PREFIX = '$page.';
+const SEARCH_PREFIX = '$search.';
+
+/**
+ * Parse a $filter key into its model, field, and operator components.
+ *
+ * Key format: $filter.{module}.{model}.{field}[__{op}]
+ * The model is the first two dot-separated segments after $filter (module.model).
+ * The field is the remaining segment, optionally with an operator suffix.
+ *
+ * Examples:
+ *   "$filter.sales.order.status"       -> { model: "sales.order", field: "status", operator: "eq" }
+ *   "$filter.sales.order.total__gt"    -> { model: "sales.order", field: "total", operator: "gt" }
+ *   "$filter.sales.order.deleted_at__empty" -> { model: "sales.order", field: "deleted_at", operator: "empty" }
+ */
+export function parseFilterKey(key: string): ParsedFilterKey | null {
+  if (!key.startsWith(FILTER_PREFIX)) return null;
+
+  const rest = key.slice(FILTER_PREFIX.length);
+  // Need at least module.model.field = 3 dot-separated segments
+  const parts = rest.split('.');
+  if (parts.length < 3) return null;
+
+  // Model is first two segments (module.model)
+  const model = `${parts[0]}.${parts[1]}`;
+
+  // Field is the remaining segments joined (supports dotted field names, though unusual)
+  let fieldPart = parts.slice(2).join('.');
+
+  // Check for operator suffix (longest match first)
+  let operator: FilterOperator = 'eq';
+  for (const [suffix, op] of Object.entries(OPERATOR_SUFFIXES)) {
+    if (fieldPart.endsWith(suffix)) {
+      operator = op;
+      fieldPart = fieldPart.slice(0, -suffix.length);
+      break;
+    }
+  }
+
+  if (!fieldPart) return null;
+
+  return { model, field: fieldPart, operator };
+}
+
+/**
+ * Get all active filters for a given model from the state store.
+ * Reads all keys starting with $filter.{model}. and parses them.
+ */
+export function getFiltersForModel(state: Map<string, unknown>, model: string): ParsedFilter[] {
+  const prefix = `${FILTER_PREFIX}${model}.`;
+  const filters: ParsedFilter[] = [];
+
+  for (const [key, value] of state) {
+    if (!key.startsWith(prefix)) continue;
+    // Skip null/undefined values (cleared filters)
+    if (value === null || value === undefined) continue;
+
+    const parsed = parseFilterKey(key);
+    if (!parsed) continue;
+
+    // Determine operator: if no suffix but value is an array, use 'in'
+    let operator = parsed.operator;
+    if (operator === 'eq' && Array.isArray(value)) {
+      operator = 'in';
+    }
+
+    filters.push({
+      model: parsed.model,
+      field: parsed.field,
+      operator,
+      value,
+    });
+  }
+
+  return filters;
+}
+
+/**
+ * Get the sort configuration for a model.
+ * The sort value is a comma-separated string. Prefix '-' means descending.
+ *
+ * Examples:
+ *   "-date"       -> [{ field: "date", direction: "desc" }]
+ *   "-date,name"  -> [{ field: "date", direction: "desc" }, { field: "name", direction: "asc" }]
+ *   null          -> null (use model default)
+ */
+export function getSortForModel(state: Map<string, unknown>, model: string): SortEntry[] | null {
+  const key = `${SORT_PREFIX}${model}`;
+  const value = state.get(key);
+
+  if (value === null || value === undefined) return null;
+  if (typeof value !== 'string' || value.trim() === '') return null;
+
+  const entries: SortEntry[] = [];
+  const parts = value.split(',');
+
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.startsWith('-')) {
+      entries.push({ field: trimmed.slice(1), direction: 'desc' });
+    } else {
+      entries.push({ field: trimmed, direction: 'asc' });
+    }
+  }
+
+  return entries.length > 0 ? entries : null;
+}
+
+/**
+ * Get the current page number for a model.
+ * Returns null if not set (use default page 1).
+ */
+export function getPageForModel(state: Map<string, unknown>, model: string): number | null {
+  const key = `${PAGE_PREFIX}${model}`;
+  const value = state.get(key);
+
+  if (value === null || value === undefined) return null;
+  const num = Number(value);
+  return Number.isFinite(num) && num >= 1 ? Math.floor(num) : null;
+}
+
+/**
+ * Get the current search term for a model.
+ * Returns null if not set.
+ */
+export function getSearchForModel(state: Map<string, unknown>, model: string): string | null {
+  const key = `${SEARCH_PREFIX}${model}`;
+  const value = state.get(key);
+  if (value === null || value === undefined) return null;
+  const str = String(value).trim();
+  return str.length > 0 ? str : null;
+}
+
+/**
+ * Check whether a store key belongs to one of the reactive variable namespaces.
+ */
+export function isReactiveVariableKey(key: string): 'filter' | 'sort' | 'page' | 'state' | null {
+  if (key.startsWith(FILTER_PREFIX)) return 'filter';
+  if (key.startsWith(SORT_PREFIX)) return 'sort';
+  if (key.startsWith(PAGE_PREFIX)) return 'page';
+  if (key.startsWith('$state.')) return 'state';
+  return null;
+}
+
+/**
+ * Extract the model name from a $filter, $sort, or $page key.
+ * Returns null for $state or unrecognized keys.
+ */
+export function getModelFromKey(key: string): string | null {
+  if (key.startsWith(FILTER_PREFIX)) {
+    const rest = key.slice(FILTER_PREFIX.length);
+    const parts = rest.split('.');
+    return parts.length >= 2 ? `${parts[0]}.${parts[1]}` : null;
+  }
+  if (key.startsWith(SORT_PREFIX)) {
+    return key.slice(SORT_PREFIX.length) || null;
+  }
+  if (key.startsWith(PAGE_PREFIX)) {
+    return key.slice(PAGE_PREFIX.length) || null;
+  }
+  return null;
+}

package/src/widgets/registry.ts

@@ -0,0 +1,41 @@
+import type { WidgetDefinitionMeta } from '@rangka/shared';
+import type { ComponentType } from 'react';
+import type { WidgetProps } from './types.js';
+
+export interface WidgetRegistryEntry {
+  meta: WidgetDefinitionMeta;
+  component: ComponentType<WidgetProps>;
+}
+
+const widgets = new Map<string, WidgetRegistryEntry>();
+
+export function registerWidget(
+  meta: WidgetDefinitionMeta,
+  component: ComponentType<WidgetProps>,
+): void {
+  widgets.set(meta.name, { meta, component });
+}
+
+export function getWidget(name: string): WidgetRegistryEntry | undefined {
+  return widgets.get(name);
+}
+
+export function getWidgetMeta(name: string): WidgetDefinitionMeta | undefined {
+  return widgets.get(name)?.meta;
+}
+
+export function getAllWidgetMeta(): WidgetDefinitionMeta[] {
+  return [...widgets.values()].map((e) => e.meta);
+}
+
+export function getWidgetRegistry(): Map<string, WidgetDefinitionMeta> {
+  const map = new Map<string, WidgetDefinitionMeta>();
+  for (const [name, entry] of widgets) {
+    map.set(name, entry.meta);
+  }
+  return map;
+}
+
+export function clearWidgetRegistry(): void {
+  widgets.clear();
+}

package/src/widgets/renderer/SlotRenderer.tsx

@@ -0,0 +1,47 @@
+import React, { useMemo } from 'react';
+import type { WidgetNode } from '@rangka/shared';
+import type { ActionHandlers } from '../action/dispatcher.js';
+import { WidgetContextProvider } from '../hooks/useWidgetContext.js';
+import { PageStateProvider } from '../hooks/usePageState.js';
+import { StateStore } from '../state/store.js';
+import type { WidgetContext } from '../context/types.js';
+import { createRootContext } from '../context/builder.js';
+import { WidgetRenderer } from './WidgetRenderer.js';
+import type { FieldMeta } from '../binding/resolver.js';
+
+export interface SlotRendererProps {
+  nodes: WidgetNode[];
+  context?: WidgetContext;
+  state?: StateStore;
+  handlers?: ActionHandlers;
+  fieldMeta?: Record<string, FieldMeta>;
+  setValue?: (field: string, val: unknown) => void;
+}
+
+export function SlotRenderer({
+  nodes,
+  context,
+  state,
+  handlers = {},
+  fieldMeta,
+  setValue,
+}: SlotRendererProps) {
+  const ctx = context ?? createRootContext({}, '', 'view');
+  const store = useMemo(() => state ?? new StateStore(), [state]);
+
+  return (
+    <PageStateProvider value={store}>
+      <WidgetContextProvider value={ctx}>
+        {nodes.map((node, index) => (
+          <WidgetRenderer
+            key={node.id ?? index}
+            node={node}
+            handlers={handlers}
+            fieldMeta={fieldMeta}
+            setValue={setValue}
+          />
+        ))}
+      </WidgetContextProvider>
+    </PageStateProvider>
+  );
+}

package/src/widgets/renderer/WidgetRenderer.tsx

@@ -0,0 +1,191 @@
+import React, { useMemo } from 'react';
+import type { WidgetNode } from '@rangka/shared';
+import type { ActionHandlers } from '../action/dispatcher.js';
+import { getWidget } from '../registry.js';
+import { useCondition } from '../hooks/useCondition.js';
+import { useBind } from '../hooks/useBind.js';
+import { useTriggerHandlers } from '../hooks/useAction.js';
+import { useWidgetContext } from '../hooks/useWidgetContext.js';
+import { WidgetContextProvider } from '../hooks/useWidgetContext.js';
+import { buildContext } from '../context/builder.js';
+import { flattenContext } from '../context/types.js';
+import { parse, evaluate } from '../expression/index.js';
+import { extractLayoutProps, hasLayoutProps, resolveLayoutClasses } from '../lib/layout-props.js';
+import { useParams } from '../../router/hooks.js';
+import type { FieldMeta } from '../binding/resolver.js';
+import type { WidgetProps } from '../types.js';
+
+function useRouteParams(): Record<string, string> {
+  try {
+    return useParams();
+  } catch {
+    return {};
+  }
+}
+
+export interface WidgetRendererProps {
+  node: WidgetNode;
+  handlers?: ActionHandlers;
+  fieldMeta?: Record<string, FieldMeta>;
+  setValue?: (field: string, val: unknown) => void;
+}
+
+export function WidgetRenderer({ node, handlers = {}, fieldMeta, setValue }: WidgetRendererProps) {
+  const visible = useCondition(node.visible);
+  const parentCtx = useWidgetContext();
+  const routeParams = useRouteParams();
+  const binding = useBind(node.bind, fieldMeta, setValue);
+  const triggerHandlers = useTriggerHandlers(node.on, handlers, node.bind?.field);
+
+  const resolvedProps = useResolvedProps(node.props);
+
+  const propsWithVisibleField = useMemo(() => {
+    if (node.visible && !Array.isArray(node.visible) && node.visible.field) {
+      return { ...resolvedProps, _visibleField: node.visible.field };
+    }
+    if (Array.isArray(node.visible) && node.visible.length === 1 && node.visible[0].field) {
+      return { ...resolvedProps, _visibleField: node.visible[0].field };
+    }
+    return resolvedProps;
+  }, [resolvedProps, node.visible]);
+
+  const childContext = useMemo(() => buildContext(node, parentCtx), [node, parentCtx]);
+
+  const { layoutProps, widgetProps: extractedWidgetProps } = useMemo(
+    () => extractLayoutProps(propsWithVisibleField),
+    [propsWithVisibleField],
+  );
+  const layoutClassName = useMemo(
+    () => (hasLayoutProps(propsWithVisibleField) ? resolveLayoutClasses(layoutProps) : ''),
+    [propsWithVisibleField, layoutProps],
+  );
+
+  if (!visible) return null;
+
+  const widgetEntry = getWidget(node.type);
+
+  if (!widgetEntry) {
+    return <div data-widget-error={`Unknown widget: ${node.type}`} />;
+  }
+
+  const Component = widgetEntry.component;
+
+  const widgetProps: WidgetProps = {
+    props: extractedWidgetProps,
+    bind: {
+      value: binding?.value ?? null,
+      setValue: binding?.setValue,
+      meta: binding?.meta,
+      error: binding?.error,
+      id: resolveBindId(node.bind?.id, parentCtx, routeParams),
+    },
+    on: triggerHandlers,
+    context: {
+      record: parentCtx.record,
+      model: parentCtx.model,
+      mode: parentCtx.mode,
+      index: parentCtx.index,
+    },
+    childNodes: node.children,
+    children: node.children ? (
+      <WidgetContextProvider value={childContext}>
+        {node.children.map((child, i) => (
+          <WidgetRenderer
+            key={child.id ?? i}
+            node={child}
+            handlers={handlers}
+            fieldMeta={fieldMeta}
+            setValue={setValue}
+          />
+        ))}
+      </WidgetContextProvider>
+    ) : undefined,
+  };
+
+  const dataAttrs: Record<string, string | undefined> = {
+    'data-rangka-widget': node.type,
+    'data-rangka-id': node.id ?? undefined,
+    'data-rangka-model': parentCtx.model || undefined,
+    'data-rangka-field': node.bind?.field ?? undefined,
+    'data-rangka-mode': parentCtx.mode,
+  };
+
+  let rendered: React.ReactNode;
+
+  if (node.bind?.model || node.source) {
+    rendered = (
+      <WidgetContextProvider value={childContext}>
+        <Component {...widgetProps} />
+      </WidgetContextProvider>
+    );
+  } else {
+    rendered = <Component {...widgetProps} />;
+  }
+
+  if (layoutClassName) {
+    return (
+      <div className={layoutClassName} {...dataAttrs}>
+        {rendered}
+      </div>
+    );
+  }
+
+  return (
+    <div className="contents" {...dataAttrs}>
+      {rendered}
+    </div>
+  );
+}
+
+function useResolvedProps(props: Record<string, unknown> | undefined): Record<string, unknown> {
+  const ctx = useWidgetContext();
+  const routeParams = useRouteParams();
+  return useMemo(() => {
+    if (!props) return {};
+    const resolved: Record<string, unknown> = {};
+    const flat = flattenContext(ctx);
+    const merged: Record<string, unknown> = { ...flat, $route: routeParams };
+    for (const [key, value] of Object.entries(props)) {
+      if (typeof value === 'string' && value.includes('{{')) {
+        const trimmed = value.trim();
+        if (
+          trimmed.startsWith('{{') &&
+          trimmed.endsWith('}}') &&
+          !trimmed.slice(2, -2).includes('{{')
+        ) {
+          const ast = parse(trimmed);
+          resolved[key] = evaluate(ast, merged);
+        } else {
+          resolved[key] = value.replace(/\{\{(.+?)\}\}/g, (_m, expr: string) => {
+            const ast = parse(expr.trim());
+            return String(evaluate(ast, merged) ?? '');
+          });
+        }
+      } else {
+        resolved[key] = value;
+      }
+    }
+    return resolved;
+  }, [props, ctx, routeParams]);
+}
+
+function resolveBindId(
+  id: string | undefined,
+  ctx: import('../context/types.js').WidgetContext,
+  routeParams: Record<string, string>,
+): string | undefined {
+  if (!id) return undefined;
+  if (!id.includes('{{')) return id;
+  const flat = flattenContext(ctx);
+  const merged: Record<string, unknown> = { ...flat, $route: routeParams };
+  const trimmed = id.trim();
+  if (trimmed.startsWith('{{') && trimmed.endsWith('}}') && !trimmed.slice(2, -2).includes('{{')) {
+    const ast = parse(trimmed);
+    const result = evaluate(ast, merged);
+    return result != null ? String(result) : undefined;
+  }
+  return id.replace(/\{\{(.+?)\}\}/g, (_m, expr: string) => {
+    const ast = parse(expr.trim());
+    return String(evaluate(ast, merged) ?? '');
+  });
+}

package/src/widgets/renderer/index.ts

@@ -0,0 +1,4 @@
+export { WidgetRenderer } from './WidgetRenderer.js';
+export type { WidgetRendererProps } from './WidgetRenderer.js';
+export { SlotRenderer } from './SlotRenderer.js';
+export type { SlotRendererProps } from './SlotRenderer.js';