SugarCraft — CandyForms

🍬 CandyForms

Foundation lib for form and input primitives

foundation forms inputs leaf-package

Foundation lib for form and input primitives — the raw component implementations that sugar-bits and sugar-prompt re-export. Extracted out of those two leaf libs so the form/prompt engine can ship as a single standalone dependency.

Install

composer require sugarcraft/candy-forms

Quickstart

use SugarCraft\Forms\Field\Input;
use SugarCraft\Forms\Form;
use SugarCraft\Forms\Validator\Required;

$form = Form::new(
    Input::new('name')
        ->withTitle('What is your name?')
        ->withValidator(new Required())
);

echo $form->view();

What's in the box

Input primitivesTextInput, TextArea, ItemList, Viewport, FilePicker, Cursor, Scrollbar, Spinner.

Form engineField interface + Field{Input, Text, Confirm, Select, MultiSelect, Note, FilePicker, Date, Slider, Color}, Form, Group, KeyMap, Theme.

Hidden fields & groupsForm honours Field::isHidden() in values, errors, validation, navigation, submit and view; focus never rests on a hidden field and fully hidden groups are skipped. A Group::withHideFunc() predicate sees the same view values() returns — the visible fields of every visible earlier group.

Bounded editingTextInput / TextArea clip a paste or insert to the remaining charLimit budget (newlines count), and TextArea pans to keep the cursor row visible.

ValidatorsRequired, Email, MinLength, MaxLength, Pattern — pluggable validator interface.

Fuzzy matchingFuzzy\FuzzyMatcher with Smith-Waterman algorithm for filter-as-you-type in Select/MultiSelect.

Use it for

Standalone form primitives — when you want the raw inputs without sugar-bits or sugar-prompt overhead.
Custom form engines — build your own form system on top of the Field interface.
Spinner and progress components — standalone spinner now lives here, was previously in sugar-bits.

Source & demos

Try the quickstart →

API

Class	Method	Description
Form	new(Field ...$fields)	Create a single-group form with fields
Form	groups(Group ...$groups)	Create a multi-page form
Form	values() / getString() / getInt() / getBool() / getArray()	Submitted values of visible fields; hidden fields and hidden groups are excluded
Group	new(Field ...$fields) / withHideFunc(?\Closure(array): bool)	A page of fields; the predicate receives the visible values collected before this group
Field\Input	new(string)	Create a text input field
Field\Confirm	new(string)	Create a confirmation field
Field\Select	new(string)->withOptions(string ...)	Create a select field
Validator\Required	validate(mixed)	Check value is not empty
Validator\Email	validate(mixed)	Check valid email format
Spinner\Spinner	new(?Style)	Create a spinner with style