Lutie Library Documentation

Welcome to the Lutie library documentation! Lutie is a robust Rust-based WebAssembly (WASM) library designed to dynamically generate and manage forms based on a provided schema. It seamlessly integrates with frontend frameworks like SolidJS, enabling developers to create dynamic, responsive, and conditionally-rendered forms with ease.

Table of Contents

1. Introduction
2. Features
3. Installation
4. Schema Specification
5. API Reference
   • lutie
   • should_render
   • evaluate_graph
6. Usage Examples
   • Basic Form Generation
   • Conditional Rendering and Computed Fields
7. Integration with SolidJS
8. Error Handling
9. Advanced Configuration
10. Contributing
11. License

Introduction

Lutie is a Rust-powered library that leverages WebAssembly to provide high-performance form generation and management capabilities. By defining a schema with specific directives and field types, Lutie can parse this schema, evaluate conditions and equations, and render dynamic forms that respond in real-time to user interactions.

Key Benefits:

• Performance: Leveraging Rust and WASM ensures fast and efficient form processing.
• Flexibility: Define complex forms with conditional logic and computed fields.
• Integration: Easily integrates with modern frontend frameworks like SolidJS, React, Vue, and more.
• Safety: Rust's strong type system and memory safety guarantees reduce runtime errors.

Features

• Schema-Based Form Generation: Define forms using a declarative schema with directives for labels, validation, grouping, conditions, and equations.
• Conditional Rendering: Show or hide form fields based on user input or computed values.
• Computed Fields: Automatically calculate field values based on equations defined in the schema.
• Grouping: Organize form fields into logical groups for better UX.
• Theming Support: Customize the appearance of forms to match your application's theme.
• Error Handling: Gracefully handle schema parsing and evaluation errors.

Installation

Prerequisites

• Rust and Cargo: Ensure you have Rust and Cargo installed. If not, install them from rustup.rs.
• wasm-pack: Tool to build Rust-generated WebAssembly packages.

  cargo install wasm-pack

Installing Lutie

Assuming Lutie is published as an npm package

npm install @adriftdev/lutie

Or, if using Yarn:

yarn add @adriftdev/lutie

Schema Specification

Lutie uses a GraphQL-like schema syntax to define form fields, their types, labels, validation rules, grouping, conditions, and computed values. Schema Structure

{
    field_name @directive1(arg: value) @directive2(arg: value) ...
    another_field(type: Type) @directive1(arg: value) ...
    ...
}

Directives

• @required: Marks a field as mandatory.
• @label(value: "Label Text"): Specifies a human-readable label for the field.
• @input_group(value: "Group Name"): Assigns the field to a specific group for organized layout.
• @condition(value: "expression"): Determines the visibility of the field based on a condition.
• @equation(value: "expression"): Computes the field's value based on an equation.

Field Types

• String: Single-line text input.
• Int: Integer number input.
• Float: Floating-point number input.
• Boolean: Checkbox input.
• Select: Dropdown selection input.
• TextArea: Multi-line text input.

{
    name @required 
         @label(value: "Name") 
         @input_group(value: "Personal")

    age(type: Int)
         @required 
         @label(value: "Age") 
         @input_group(value: "Personal") 
         @equation(value: "current_year - dob") 
         @condition(value: "current_year > dob")

    dob(type: Int) 
         @required 
         @label(value: "Date of Birth") 
         @input_group(value: "Personal")

    current_year(type: Int) 
         @required 
         @label(value: "Current Year") 
         @input_group(value: "Personal")
}

API Reference

lutie

Description:

Parses the provided schema and extracts form field definitions.

Signature:

function lutie(schema: string): Box<[JsValue]>

Parameters:

• schema (string): The GraphQL-like schema defining the form structure.

Returns:

• Box<[JsValue]>: An array of serialized SchemaNode objects representing each form field.

should_render

Description:

Determines whether a particular field should be rendered based on the current context and schema conditions.

Signature:

function should_render(ctx: JsValue, node: JsValue, schema: string): JsValue

Parameters:

• ctx (JsValue): The current context containing form values.
• node (JsValue): The SchemaNode representing the field.
• schema (string): The original schema string.

Returns:

• JsValue: A boolean indicating whether the field should be rendered.

Usage Example:

import { should_render } from "@adriftdev/lutie";

const shouldShow = should_render(currentValues, node, schema);

evaluate_graph

Description:

Evaluates the entire form context, computing any equations and updating form values accordingly.

Signature:

function evaluate_graph(ctx: JsValue, schema: string): JsValue

Parameters:

• ctx (JsValue): The current context containing form values.
• schema (string): The original schema string.

Returns:

• JsValue: An updated context with computed fields.

Usage Example:

import { evaluate_graph } from "@adriftdev/lutie";

const updatedValues = evaluate_graph(currentValues, schema);

Usage Examples

Basic Form Generation

Here's a simple example of how to use Lutie to generate a form:

import { lutie, evaluate_graph, should_render } from "@adriftdev/lutie";

// Define your schema
const schema = `
{
    name @required @label(value: "Name")
    age(type: Int) @required @label(value: "Age")
}
`;

// Initialize the form
const nodes = lutie(schema);

// Initialize form values
let values = {
  name: "Jane Doe",
  age: 30,
};

// Evaluate the graph to compute any equations (if present)
values = evaluate_graph(values, schema);

// Determine visibility of fields
nodes.forEach((node) => {
  const isVisible = should_render(values, node, schema);
  console.log(`${node.label} is ${isVisible ? "visible" : "hidden"}`);
});

Conditional Rendering and Computed Fields

Lutie allows you to define fields that are conditionally rendered and/or have computed values based on other fields.

Example Schema:

{
    name @required 
         @label(value: "Name") 
         @input_group(value: "Personal")

    age(type: Int)
         @required 
         @label(value: "Age") 
         @input_group(value: "Personal") 
         @equation(value: "current_year - dob") 
         @condition(value: "current_year > dob")

    dob(type: Int) 
         @required 
         @label(value: "Date of Birth") 
         @input_group(value: "Personal")

    current_year(type: Int) 
         @required 
         @label(value: "Current Year") 
         @input_group(value: "Personal")
}

Usage Example:

import { lutie, evaluate_graph, should_render } from "@adriftdev/lutie";

// Define your schema with conditional rendering and equations
const schema = `
{
    name @required 
         @label(value: "Name") 
         @input_group(value: "Personal")

    age(type: Int)
         @required 
         @label(value: "Age") 
         @input_group(value: "Personal") 
         @equation(value: "current_year - dob") 
         @condition(value: "current_year > dob")

    dob(type: Int) 
         @required 
         @label(value: "Date of Birth") 
         @input_group(value: "Personal")

    current_year(type: Int) 
         @required 
         @label(value: "Current Year") 
         @input_group(value: "Personal")
}
`;

// Initialize the form
const nodes = lutie(schema);

// Initialize form values
let values = {
  name: "Jane Doe",
  dob: 1990,
  current_year: 2024,
};

// Evaluate the graph to compute equations
values = evaluate_graph(values, schema);

// Determine visibility of fields
nodes.forEach((node) => {
  const isVisible = should_render(values, node, schema);
  console.log(`${node.label} is ${isVisible ? "visible" : "hidden"}`);
});

Output:

Name is visible
Age is visible
Date of Birth is visible
Current Year is visible

Explanation:

• The age field is computed as current_year - dob. Given dob = 1990 and current_year = 2024, age = 34.
• The age field is only visible if current_year > dob, which is true in this case.
• If current_year <= dob, the age field would be hidden.