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.

1  cargo install wasm-pack

Installing Lutie

Assuming Lutie is published as an npm package

1npm install @adriftdev/lutie

Or, if using Yarn:

1yarn 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

1{
2    field_name @directive1(arg: value) @directive2(arg: value) ...
3    another_field(type: Type) @directive1(arg: value) ...
4    ...
5}

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.

1{
2    name @required 
3         @label(value: "Name") 
4         @input_group(value: "Personal")
5
6    age(type: Int)
7         @required 
8         @label(value: "Age") 
9         @input_group(value: "Personal") 
10         @equation(value: "current_year - dob") 
11         @condition(value: "current_year > dob")
12
13    dob(type: Int) 
14         @required 
15         @label(value: "Date of Birth") 
16         @input_group(value: "Personal")
17
18    current_year(type: Int) 
19         @required 
20         @label(value: "Current Year") 
21         @input_group(value: "Personal")
22}

---

API Reference

lutie

Description:

Parses the provided schema and extracts form field definitions.

Signature:

1function 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:

1function 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:

1
2import { should_render } from "@adriftdev/lutie";
3
4const shouldShow = should_render(currentValues, node, schema);

---

evaluate_graph

Description:

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

Signature:

1function 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:

1
2import { evaluate_graph } from "@adriftdev/lutie";
3
4const updatedValues = evaluate_graph(currentValues, schema);

---

Usage Examples

Basic Form Generation

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

1
2import { lutie, evaluate_graph, should_render } from "@adriftdev/lutie";
3
4// Define your schema
5const schema = `
6{
7    name @required @label(value: "Name")
8    age(type: Int) @required @label(value: "Age")
9}
10`;
11
12// Initialize the form
13const nodes = lutie(schema);
14
15// Initialize form values
16let values = {
17  name: "Jane Doe",
18  age: 30,
19};
20
21// Evaluate the graph to compute any equations (if present)
22values = evaluate_graph(values, schema);
23
24// Determine visibility of fields
25nodes.forEach((node) => {
26  const isVisible = should_render(values, node, schema);
27  console.log(`${node.label} is ${isVisible ? "visible" : "hidden"}`);
28});

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:

1
2{
3    name @required 
4         @label(value: "Name") 
5         @input_group(value: "Personal")
6
7    age(type: Int)
8         @required 
9         @label(value: "Age") 
10         @input_group(value: "Personal") 
11         @equation(value: "current_year - dob") 
12         @condition(value: "current_year > dob")
13
14    dob(type: Int) 
15         @required 
16         @label(value: "Date of Birth") 
17         @input_group(value: "Personal")
18
19    current_year(type: Int) 
20         @required 
21         @label(value: "Current Year") 
22         @input_group(value: "Personal")
23}

Usage Example:

1
2import { lutie, evaluate_graph, should_render } from "@adriftdev/lutie";
3
4// Define your schema with conditional rendering and equations
5const schema = `
6{
7    name @required 
8         @label(value: "Name") 
9         @input_group(value: "Personal")
10
11    age(type: Int)
12         @required 
13         @label(value: "Age") 
14         @input_group(value: "Personal") 
15         @equation(value: "current_year - dob") 
16         @condition(value: "current_year > dob")
17
18    dob(type: Int) 
19         @required 
20         @label(value: "Date of Birth") 
21         @input_group(value: "Personal")
22
23    current_year(type: Int) 
24         @required 
25         @label(value: "Current Year") 
26         @input_group(value: "Personal")
27}
28`;
29
30// Initialize the form
31const nodes = lutie(schema);
32
33// Initialize form values
34let values = {
35  name: "Jane Doe",
36  dob: 1990,
37  current_year: 2024,
38};
39
40// Evaluate the graph to compute equations
41values = evaluate_graph(values, schema);
42
43// Determine visibility of fields
44nodes.forEach((node) => {
45  const isVisible = should_render(values, node, schema);
46  console.log(`${node.label} is ${isVisible ? "visible" : "hidden"}`);
47});

Output:

1Name is visible
2Age is visible
3Date of Birth is visible
4Current 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.