@rangka/client 0.0.1

package/src/widgets/expression/parser.ts

@@ -0,0 +1,229 @@
+import type { AstNode, BinaryOperator } from './types.js';
+
+const BINARY_OPS: Record<string, { prec: number; op: BinaryOperator }> = {
+  '||': { prec: 1, op: '||' },
+  '&&': { prec: 2, op: '&&' },
+  '==': { prec: 3, op: '==' },
+  '!=': { prec: 3, op: '!=' },
+  '>': { prec: 4, op: '>' },
+  '<': { prec: 4, op: '<' },
+  '>=': { prec: 4, op: '>=' },
+  '<=': { prec: 4, op: '<=' },
+  '+': { prec: 5, op: '+' },
+  '-': { prec: 5, op: '-' },
+  '*': { prec: 6, op: '*' },
+  '/': { prec: 6, op: '/' },
+  '%': { prec: 6, op: '%' },
+};
+
+export function parse(input: string): AstNode {
+  const trimmed = input.trim();
+  if (trimmed.startsWith('{{') && trimmed.endsWith('}}')) {
+    input = trimmed.slice(2, -2).trim();
+  }
+  const parser = new Parser(input);
+  const ast = parser.parseExpression(0);
+  parser.skipWhitespace();
+  if (parser.pos < parser.input.length) {
+    throw new Error(
+      `Unexpected character: '${parser.input[parser.pos]}' at position ${parser.pos}`,
+    );
+  }
+  return ast;
+}
+
+class Parser {
+  input: string;
+  pos: number;
+
+  constructor(input: string) {
+    this.input = input;
+    this.pos = 0;
+  }
+
+  parseExpression(minPrec: number): AstNode {
+    let left = this.parseUnary();
+
+    while (true) {
+      this.skipWhitespace();
+      const op = this.peekOperator();
+      if (!op) break;
+      const info = BINARY_OPS[op];
+      if (!info || info.prec < minPrec) break;
+      this.pos += op.length;
+      this.skipWhitespace();
+      const right = this.parseExpression(info.prec + 1);
+      left = { type: 'binary', operator: info.op, left, right };
+    }
+
+    return left;
+  }
+
+  parseUnary(): AstNode {
+    this.skipWhitespace();
+    const ch = this.input[this.pos];
+
+    if (ch === '!') {
+      this.pos++;
+      const operand = this.parseUnary();
+      return { type: 'unary', operator: '!', operand };
+    }
+
+    if (ch === '-' && !this.isAfterValue()) {
+      this.pos++;
+      const operand = this.parseUnary();
+      return { type: 'unary', operator: '-', operand };
+    }
+
+    return this.parsePrimary();
+  }
+
+  parsePrimary(): AstNode {
+    this.skipWhitespace();
+    const ch = this.input[this.pos];
+
+    if (ch === '(') {
+      this.pos++;
+      const expr = this.parseExpression(0);
+      this.skipWhitespace();
+      this.expect(')');
+      return expr;
+    }
+
+    if (ch === '"' || ch === "'") {
+      return this.parseString();
+    }
+
+    if (this.isDigit(ch)) {
+      return this.parseNumber();
+    }
+
+    if (this.isIdentStart(ch)) {
+      return this.parseIdentifierOrCall();
+    }
+
+    throw new Error(`Unexpected character: '${ch}' at position ${this.pos}`);
+  }
+
+  parseString(): AstNode {
+    const quote = this.input[this.pos];
+    this.pos++;
+    let value = '';
+    while (this.pos < this.input.length && this.input[this.pos] !== quote) {
+      if (this.input[this.pos] === '\\') {
+        this.pos++;
+        const esc = this.input[this.pos];
+        if (esc === 'n') value += '\n';
+        else if (esc === 't') value += '\t';
+        else value += esc;
+      } else {
+        value += this.input[this.pos];
+      }
+      this.pos++;
+    }
+    this.expect(quote);
+    return { type: 'literal', value };
+  }
+
+  parseNumber(): AstNode {
+    const start = this.pos;
+    while (this.pos < this.input.length && this.isDigit(this.input[this.pos])) {
+      this.pos++;
+    }
+    if (this.pos < this.input.length && this.input[this.pos] === '.') {
+      this.pos++;
+      while (this.pos < this.input.length && this.isDigit(this.input[this.pos])) {
+        this.pos++;
+      }
+    }
+    return { type: 'literal', value: Number(this.input.slice(start, this.pos)) };
+  }
+
+  parseIdentifierOrCall(): AstNode {
+    const name = this.readIdentifier();
+
+    if (name === 'true') return { type: 'literal', value: true };
+    if (name === 'false') return { type: 'literal', value: false };
+    if (name === 'null') return { type: 'literal', value: null };
+
+    this.skipWhitespace();
+
+    if (this.input[this.pos] === '(') {
+      this.pos++;
+      const args: AstNode[] = [];
+      this.skipWhitespace();
+      if (this.input[this.pos] !== ')') {
+        args.push(this.parseExpression(0));
+        while (this.input[this.pos] === ',') {
+          this.pos++;
+          this.skipWhitespace();
+          args.push(this.parseExpression(0));
+        }
+      }
+      this.skipWhitespace();
+      this.expect(')');
+      return { type: 'call', name, args };
+    }
+
+    const path = [name];
+    while (this.pos < this.input.length && this.input[this.pos] === '.') {
+      this.pos++;
+      path.push(this.readIdentifier());
+    }
+
+    return { type: 'field', path };
+  }
+
+  readIdentifier(): string {
+    const start = this.pos;
+    while (this.pos < this.input.length && this.isIdentChar(this.input[this.pos])) {
+      this.pos++;
+    }
+    if (this.pos === start) {
+      throw new Error(`Expected identifier at position ${this.pos}`);
+    }
+    return this.input.slice(start, this.pos);
+  }
+
+  peekOperator(): string | null {
+    for (const op of ['||', '&&', '==', '!=', '>=', '<=', '>', '<', '+', '-', '*', '/', '%']) {
+      if (this.input.startsWith(op, this.pos)) {
+        return op;
+      }
+    }
+    return null;
+  }
+
+  skipWhitespace(): void {
+    while (this.pos < this.input.length && /\s/.test(this.input[this.pos])) {
+      this.pos++;
+    }
+  }
+
+  expect(ch: string): void {
+    if (this.input[this.pos] !== ch) {
+      throw new Error(
+        `Expected '${ch}' at position ${this.pos}, got '${this.input[this.pos] ?? 'EOF'}'`,
+      );
+    }
+    this.pos++;
+  }
+
+  isDigit(ch: string | undefined): boolean {
+    return ch !== undefined && ch >= '0' && ch <= '9';
+  }
+
+  isIdentStart(ch: string | undefined): boolean {
+    return ch !== undefined && /[a-zA-Z_$]/.test(ch);
+  }
+
+  isIdentChar(ch: string | undefined): boolean {
+    return ch !== undefined && /[a-zA-Z0-9_$]/.test(ch);
+  }
+
+  isAfterValue(): boolean {
+    if (this.pos === 0) return false;
+    const prev = this.input[this.pos - 1];
+    return prev === ')' || this.isDigit(prev) || this.isIdentChar(prev);
+  }
+}

package/src/widgets/expression/types.ts

@@ -0,0 +1,45 @@
+export type AstNode = LiteralNode | FieldRefNode | UnaryNode | BinaryNode | CallNode;
+
+export interface LiteralNode {
+  type: 'literal';
+  value: string | number | boolean | null;
+}
+
+export interface FieldRefNode {
+  type: 'field';
+  path: string[];
+}
+
+export interface UnaryNode {
+  type: 'unary';
+  operator: '!' | '-';
+  operand: AstNode;
+}
+
+export interface BinaryNode {
+  type: 'binary';
+  operator: BinaryOperator;
+  left: AstNode;
+  right: AstNode;
+}
+
+export interface CallNode {
+  type: 'call';
+  name: string;
+  args: AstNode[];
+}
+
+export type BinaryOperator =
+  | '+'
+  | '-'
+  | '*'
+  | '/'
+  | '%'
+  | '=='
+  | '!='
+  | '>'
+  | '<'
+  | '>='
+  | '<='
+  | '&&'
+  | '||';

package/src/widgets/form/FormContext.ts

@@ -0,0 +1,29 @@
+import { createContext, useContext } from 'react';
+import type { FieldMeta } from '../binding/resolver.js';
+
+export interface FormContextValue {
+  mode: 'create' | 'edit' | 'view';
+  values: Record<string, unknown>;
+  errors: Record<string, string>;
+  dirty: Set<string>;
+  touched: Set<string>;
+  submitting: boolean;
+
+  getValue(field: string): unknown;
+  setValue(field: string, value: unknown): void;
+  getError(field: string): string | undefined;
+  getFieldMeta(field: string): FieldMeta | undefined;
+  setTouched(field: string): void;
+
+  submit(): Promise<void>;
+  reset(): void;
+  isDirty(): boolean;
+}
+
+const FormContextReact = createContext<FormContextValue | null>(null);
+
+export const FormContextProvider = FormContextReact.Provider;
+
+export function useFormContext(): FormContextValue | null {
+  return useContext(FormContextReact);
+}

package/src/widgets/form/FormProvider.tsx

@@ -0,0 +1,84 @@
+import React, { useCallback, useEffect, useMemo } from 'react';
+import { useModelRecord } from '../data/useModelRecord.js';
+import { useModelMeta } from '../../data/useModelMeta.js';
+import { FormContextProvider } from './FormContext.js';
+import { useFormState } from './useFormState.js';
+import { useFormValidation } from './useFormValidation.js';
+import { useFormSubmit } from './useFormSubmit.js';
+import type { FormContextValue } from './FormContext.js';
+import type { FieldMeta } from '../binding/resolver.js';
+
+export interface FormProviderProps {
+  model: string;
+  id?: string | null;
+  onSuccess?: (record: Record<string, unknown>, mode: 'create' | 'edit') => void;
+  onError?: (errors: Record<string, string>, message: string) => void;
+  children: React.ReactNode;
+}
+
+export function FormProvider({ model, id, onSuccess, onError, children }: FormProviderProps) {
+  const mode: 'create' | 'edit' | 'view' = id ? 'edit' : 'create';
+
+  const { modelMeta } = useModelMeta(model);
+  const { data: record } = useModelRecord({ model, id, enabled: mode === 'edit' });
+
+  const validation = useFormValidation(model);
+  const formState = useFormState(validation.validateField);
+  const { submit } = useFormSubmit({
+    model,
+    mode,
+    id,
+    formState,
+    validation,
+    onSuccess,
+    onError,
+  });
+
+  useEffect(() => {
+    if (mode === 'edit' && record) {
+      formState.initValues(record);
+    }
+  }, [record, mode]);
+
+  const reset = useCallback(() => {
+    formState.reset(mode);
+  }, [formState, mode]);
+
+  const getFieldMeta = useCallback(
+    (field: string): FieldMeta | undefined => {
+      if (!modelMeta) return undefined;
+      const fieldDef = modelMeta.fields.find((f) => f.name === field);
+      if (!fieldDef) return undefined;
+      return {
+        type: fieldDef.type,
+        label: fieldDef.label ?? field,
+        required: fieldDef.required ?? false,
+        readOnly: false,
+        options: fieldDef.options as unknown[] | undefined,
+      };
+    },
+    [modelMeta, mode],
+  );
+
+  const contextValue: FormContextValue = useMemo(
+    () => ({
+      mode,
+      values: formState.state.values,
+      errors: formState.state.errors,
+      dirty: formState.getDirtyFields(),
+      touched: formState.state.touched,
+      submitting: formState.state.submitting,
+      getValue: formState.getValue,
+      setValue: formState.setValue,
+      getError: formState.getError,
+      getFieldMeta,
+      setTouched: formState.setTouched,
+      submit,
+      reset,
+      isDirty: formState.isDirty,
+    }),
+    [formState.state, formState, getFieldMeta, submit, reset, mode],
+  );
+
+  return <FormContextProvider value={contextValue}>{children}</FormContextProvider>;
+}

package/src/widgets/form/FormWidget.tsx

@@ -0,0 +1,42 @@
+import React, { useCallback } from 'react';
+import type { WidgetProps } from '../types.js';
+import { useWidgetContext } from '../hooks/useWidgetContext.js';
+import { FormProvider } from './FormProvider.js';
+
+export function FormWidget({ bind, on, children }: WidgetProps) {
+  const ctx = useWidgetContext();
+  const modelName = ctx.model;
+  const id = bind.id ?? undefined;
+
+  const handleSuccess = useCallback(
+    (record: Record<string, unknown>, mode: 'create' | 'edit') => {
+      on.success?.({ record, mode });
+    },
+    [on],
+  );
+
+  const handleError = useCallback(
+    (errors: Record<string, string>, message: string) => {
+      on.error?.({ errors, message });
+    },
+    [on],
+  );
+
+  if (!modelName) return null;
+
+  return (
+    <FormProvider model={modelName} id={id} onSuccess={handleSuccess} onError={handleError}>
+      {children}
+    </FormProvider>
+  );
+}
+
+FormWidget.widgetMeta = {
+  name: 'form',
+  label: 'Form',
+  category: 'data' as const,
+  schema: {},
+  binding: 'model' as const,
+  triggers: ['success', 'error'],
+  container: true,
+};

package/src/widgets/form/index.ts

@@ -0,0 +1,4 @@
+export { FormWidget } from './FormWidget.js';
+export { FormProvider } from './FormProvider.js';
+export { useFormContext, FormContextProvider } from './FormContext.js';
+export type { FormContextValue } from './FormContext.js';

package/src/widgets/form/useFormState.ts

@@ -0,0 +1,127 @@
+import { useCallback, useRef, useState } from 'react';
+
+export interface FormState {
+  values: Record<string, unknown>;
+  original: Record<string, unknown>;
+  errors: Record<string, string>;
+  touched: Set<string>;
+  submitting: boolean;
+}
+
+export interface UseFormStateResult {
+  state: FormState;
+  getValue(field: string): unknown;
+  setValue(field: string, value: unknown): void;
+  getError(field: string): string | undefined;
+  setTouched(field: string): void;
+  setErrors(errors: Record<string, string>): void;
+  setSubmitting(submitting: boolean): void;
+  isDirty(): boolean;
+  getDirtyFields(): Set<string>;
+  reset(mode: 'create' | 'edit'): void;
+  initValues(record: Record<string, unknown>): void;
+}
+
+export function useFormState(
+  onValidateField?: (field: string, value: unknown) => string | undefined,
+): UseFormStateResult {
+  const [values, setValues] = useState<Record<string, unknown>>({});
+  const [original, setOriginal] = useState<Record<string, unknown>>({});
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [touched, setTouched] = useState<Set<string>>(new Set());
+  const [submitting, setSubmitting] = useState(false);
+
+  const valuesRef = useRef(values);
+  valuesRef.current = values;
+  const originalRef = useRef(original);
+  originalRef.current = original;
+
+  const getValue = useCallback((field: string): unknown => {
+    return valuesRef.current[field];
+  }, []);
+
+  const setValue = useCallback(
+    (field: string, value: unknown) => {
+      setValues((prev) => ({ ...prev, [field]: value }));
+
+      if (onValidateField) {
+        const error = onValidateField(field, value);
+        setErrors((prev) => {
+          if (error) return { ...prev, [field]: error };
+          const next = { ...prev };
+          delete next[field];
+          return next;
+        });
+      }
+    },
+    [onValidateField],
+  );
+
+  const getError = useCallback(
+    (field: string): string | undefined => {
+      return errors[field];
+    },
+    [errors],
+  );
+
+  const markTouched = useCallback((field: string) => {
+    setTouched((prev) => {
+      if (prev.has(field)) return prev;
+      const next = new Set(prev);
+      next.add(field);
+      return next;
+    });
+  }, []);
+
+  const setErrorsBatch = useCallback((errs: Record<string, string>) => {
+    setErrors(errs);
+  }, []);
+
+  const isDirty = useCallback((): boolean => {
+    for (const key of Object.keys(valuesRef.current)) {
+      if (valuesRef.current[key] !== originalRef.current[key]) return true;
+    }
+    return false;
+  }, []);
+
+  const getDirtyFields = useCallback((): Set<string> => {
+    const dirty = new Set<string>();
+    for (const key of Object.keys(valuesRef.current)) {
+      if (valuesRef.current[key] !== originalRef.current[key]) {
+        dirty.add(key);
+      }
+    }
+    return dirty;
+  }, []);
+
+  const reset = useCallback((mode: 'create' | 'edit') => {
+    if (mode === 'edit') {
+      setValues({ ...originalRef.current });
+    } else {
+      setValues({});
+    }
+    setErrors({});
+    setTouched(new Set());
+  }, []);
+
+  const initValues = useCallback((record: Record<string, unknown>) => {
+    setValues({ ...record });
+    setOriginal({ ...record });
+    setErrors({});
+    setTouched(new Set());
+  }, []);
+
+  return {
+    state: { values, original, errors, touched, submitting },
+    getValue,
+    setValue,
+    getError,
+    setTouched: markTouched,
+    setErrors: setErrorsBatch,
+    setSubmitting,
+    isDirty,
+    getDirtyFields,
+    reset,
+    initValues,
+  };
+}

package/src/widgets/form/useFormSubmit.ts

@@ -0,0 +1,90 @@
+import { useCallback } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { apiClient } from '../../api/client.js';
+import { modelToPath } from '../../api/paths.js';
+import type { UseFormStateResult } from './useFormState.js';
+import type { UseFormValidationResult } from './useFormValidation.js';
+
+export interface UseFormSubmitOptions {
+  model: string;
+  mode: 'create' | 'edit' | 'view';
+  id: string | null | undefined;
+  formState: UseFormStateResult;
+  validation: UseFormValidationResult;
+  onSuccess?: (record: Record<string, unknown>, mode: 'create' | 'edit') => void;
+  onError?: (errors: Record<string, string>, message: string) => void;
+}
+
+export interface UseFormSubmitResult {
+  submit(): Promise<void>;
+}
+
+export function useFormSubmit(options: UseFormSubmitOptions): UseFormSubmitResult {
+  const { model, mode, id, formState, validation, onSuccess, onError } = options;
+  const queryClient = useQueryClient();
+
+  const submit = useCallback(async () => {
+    if (mode === 'view') return;
+
+    const { state, setErrors, setSubmitting, getDirtyFields, initValues } = formState;
+    const { values } = state;
+
+    const errors = validation.validateAll(values);
+    if (Object.keys(errors).length > 0) {
+      setErrors(errors);
+      // Mark all fields as touched so errors display
+      for (const field of Object.keys(errors)) {
+        formState.setTouched(field);
+      }
+      return;
+    }
+
+    setSubmitting(true);
+
+    try {
+      const basePath = modelToPath(model);
+      let payload: Record<string, unknown>;
+
+      if (mode === 'edit') {
+        const dirty = getDirtyFields();
+        payload = {};
+        for (const field of dirty) {
+          payload[field] = values[field];
+        }
+      } else {
+        payload = {};
+        for (const [key, value] of Object.entries(values)) {
+          if (value !== null && value !== undefined && value !== '') {
+            payload[key] = value;
+          }
+        }
+      }
+
+      const url = mode === 'edit' ? `${basePath}/${id}` : basePath;
+      const method = mode === 'edit' ? 'PATCH' : 'POST';
+
+      const response = await apiClient(url, {
+        method,
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({ message: 'Submit failed' }));
+        const serverErrors: Record<string, string> = body.errors ?? {};
+        const message: string = body.message ?? 'Submit failed';
+        setErrors(serverErrors);
+        onError?.(serverErrors, message);
+        return;
+      }
+
+      const record = await response.json();
+      queryClient.invalidateQueries({ queryKey: ['model', model] });
+      initValues(record);
+      onSuccess?.(record, mode);
+    } finally {
+      setSubmitting(false);
+    }
+  }, [model, mode, id, formState, validation, onSuccess, onError, queryClient]);
+
+  return { submit };
+}