API.md

API Reference

See README.md for the consolidated API. This file contains additional detail.

form.New — Widget Resolution Detail

f, err := form.New("content", data) // data implements model.Fielder
// -> f.GetID() == "content." + resolveStructName(data)
// -> f.String() renders all fields that have a Widget in data.Schema()

For each field in data.Schema():

1. field.IsPK() && field.IsAutoInc() → skip (auto-increment PKs not editable).
2. field.Widget == nil → skip (no UI binding).
3. field.Widget.Clone(formID, fieldName).(input.Input) → positioned input.
4. field.NotNull → SetRequired(true) on the input.
5. Current value bound via fmt.ReadValues() + SetValues().

(*Form).Validate() — Validation Detail

• Skips fields with SkipValidation set to true in the input.
• Pulls values from reactive signals.
• Calls inp.Validate(val) (promoted from model.Kind).
• Returns the first error encountered.

(*Form).SyncValues(data model.Fielder) — Binding Detail

Synchronizes input values back to the struct pointers provided by data.Pointers(). Supports model.FieldText, model.FieldInt, model.FieldFloat, and model.FieldBool.

(*Form).ValidateData(action byte, data model.Fielder) — Server-side Validation

Validates the provided data using the form's input rules. Satisfies crudp.DataValidator.

(*Form).Submit()

Runs the full submit pipeline programmatically:

1. SyncValues(f.data): copies values from signals to struct.
2. Validate(): final validation check.
3. If valid and OnSubmit is set:
   • Sets submitting signal to true.
   • Calls the OnSubmit callback.
   • When the callback's done function is called:
     • Sets submitting signal back to false.
     • Resets the form (unless NoResetOnSuccess was called).

Returns the first validation error, or nil if the submission was dispatched. The DOM submit event handler delegates to this method.

form.Renderer

Optional capability interface for custom inputs that own their markup.

type Renderer interface {
    RenderInput(value *dom.SignalString, onInput func(string)) *dom.Element
}

• Markup ownership: The form still owns the field wrapper (div.tw-field), the error span, and the field ID. The widget provides the inner control.
• Contract: The widget must call onInput with the new value on user input. The form updates the value signal and runs live validation.
• Location: Lives in package form because it references *dom.Element (the input package is dom-free).

fmt.Permitted — Validation Engine

type Permitted struct {
	Letters    bool     // a-z, A-Z (and ñ/Ñ)
	Tilde      bool     // á, é, í, ó, ú
	Numbers    bool     // 0-9
	Spaces     bool     // ' '
	BreakLine  bool     // '\n'
	Tab        bool     // '\t'
	Extra      []rune   // additional allowed characters
	NotAllowed []string // disallowed substrings
	Minimum    int      // minimum length
	Maximum    int      // maximum length
}

Error messages from Permitted.Validate(name, text):

• "{name} minimum {min} chars" — value shorter than Minimum
• "{name} maximum {max} chars" — value longer than Maximum
• "space not allowed" — space when Spaces=false
• "character {X} not allowed" — disallowed character

Namer Interface

Fielder types can optionally implement Namer to provide a custom form name:

type Namer interface {
    FormName() string
}

If not implemented, defaults to "form".