[qState]: https://www.npmjs.com/package/@qundus/qstate
it feels absolutly bizzare how html forms have become framework dedicated solution over the years, and it becomes almost impossible to switch/jump between framework if a feature is not applicable somewhere or there's simply a library in another framework would make the job at hand go faster, this is what this library targets. Offering a fresh way to look at forms and how they're used without depending on any framework and offer framework dependant solutions wherever neccessary.
- Independant and straight forward form logic
- support for framework specific hooks through [qState]
- modify dom/vdom element right from any input
- global form options to control whole form behavior
- validator function or array of functions
- schema validation libraries converters, only Zod for now
- listen to form mount and change events and modify data accordingly
- ...and much more!
i don't have time rn to finish this but below are some helpful examples, this is still work in progress even though i'm testing it in production and it's working like a charm.
i appreciate any feedback, issues and/or PRs
```shell
pnpm install @qundus/qform @qundus/qstate
```
```ts
// login-form | any file type js, cjs, mjs or ts
import { form } from "@qundus/qform";
export const login = form(
{
name: null, // fallback input.type="text"
password: "text" // place the type
}
);
```
> Vanilla
```html
```
> Preact React Solid tsx jsx
```ts
import { login } from "./login-form";
interface Props extends IntrinsicElement<"input"> {}
export default function (props: Props) {
const atom = login.atoms("name");
// const $state = atom.$store.hooks.preact(); // use your hooks
return (
);
}
```
> Svelte
```html
```
converters are a way to use external schema validation libraries, converters work on forming the given schema object and flattening it and then creating the form fields.
> Zod
```ts
import { form, cZod } from "@qundus/qform";
import { cZod } from "@qundus/qform/converters";
import { z } from "zod";
// schema data
enum Questions {
first = "are you cool?",
second = "why are you gay?",
}
enum Colors {
red = "Red",
blue = "Blue",
}
const jobs = ["student", "employee"] as const;
const locations = ["saudi", "kuwait"] as const;
const schema = z.object({
// primitives
name: z.string(),
single: z.boolean(),
stringOrBoolean: z.string().nullable().or(z.boolean()), // not supported, fallsback to "text" field.type
huh: z.unknown().nullable(), // supports unknownTypes through unknownAsTextFields option
// objects
address: z.object({
street: z.string(),
zip: z.number(), // deep keys will be flattned address.zip
}),
// files
picture: z.instanceof(File),
documents: z.array(z.instanceof(File)),
// enums & nativeEnums
job: z.enum(jobs),
jobAndLocations: z.enum(jobs).and(z.enum(locations)), // collective enums
question: z.nativeEnum(Questions),
color: z.nativeEnum(Colors).nullable(),
questionOrColor: z.array(z.nativeEnum(Questions).and(z.nativeEnum(Colors))), // intersections and unions are treated the same for now
// arrays are not supported for now, you have to set the type yourself
// only enums, nativeEnums and files are supported for now
options: z.array(z.string()),
});
// now let's make our form fields
const fields = cZod.schemaToFields(schema, {
// override
override: {
huh: { valueNullable: false },
// for logically undefined types like array
options: {
type: "select",
processValue: (value) => {
// tell the form how to process the value before it's validated
return value
},
},
},
});
// now pass it and create the form object
export const zodForm = form(fields);
```
and then use it how you would use the login from before.
```tsx
import { login } from "../login-form";
// let's assume you're using preact hook
export function Page() {
const $button = login.button.$store.hooks.preact();
function submit() {
e.preventDefault();
login.actions.submit({
runner: async () => {
const data = login.actions.getValuesLowercase();
// if the data was flattened, you can unflatten it
const cdata = cObj.unflatten(data);
},
cannotSubmit: () => {
console.log("runner blocked");
},
});
}
return (
)
}
```
TODO: list options
- convert field value to accept primitives and also a function processor, allowing to shape value however user likes
- reduce number of states used per form
- optimize apis for processors and wherever possible
- adopt plugins/addons bahavior to use form actions, form button..etc and
- reduce main form object size through plugins/addons mentioned above
so much more examples and use cases are on the way once i get time, i'll just throw in these here randomly till i get back
```ts
import { form } from "@qundus/qform";
import { vFile } from "@qundus/qform/validators";
export const login = form(
{
name: null,
color: "color",
email: {
type: "email",
value: "wow@gmail.com",
validate(value) {
if (value == null) {
return "email is required";
}
if (!value.includes("@")) {
return "email must have @";
}
return null;
},
},
phone: {
type: "tel",
hidden: true,
// value: 5004625,
// validateOn: "change",
validate: (value) => {
if (typeof value === "number") {
if (value < 3) {
return "phone number must be at least 3";
}
}
if (typeof value === "string") {
if (value.length < 3) {
return "phone number must be at least 3";
}
}
return undefined;
},
// processValue: () => {
// console.log("process value phone :: ");
// },
// processCondition: ({ value, $condition, getValueOf }) => {
// const name = getValueOf("name");
// console.log("name from phone value is :: ", name);
// // if (name == null) {
// // $condition.hidden = true;
// // } else {
// // $condition.hidden = false;
// // }
// },
processElement: ({ key, isVdom, element }) => {
console.log("process element :: ", key);
},
},
cities: {
type: "select",
value: undefined,
// validateOn: "change",
// validate(value) {
// return null;
// },
options: () => [
{ label: "saudi", value: "sa" },
{ label: "kuwait", value: "kw" },
],
// multiple: true,
// processValue: ({ key, next }, { processors }) => {
// return processors.checkbox();
// },
},
picture: {
type: "file",
// value: null,
validate: (value: FileList) => {
const range = vFile.Ranges.kilo;
const size_limit = 2;
const t = vFile.isFileSizeLessThan(value[0], size_limit, range);
if (!t) {
return "File size limit is " + size_limit + range;
}
},
required: false,
// options: () => ([{label: "", value: ""}]),
// element: {
// multiple: true,
// },
},
isSingle: {
type: "checkbox",
// value: false,
// mandatory: true,
// options: () => [{ label: "", value: "" }],
},
gender: {
type: "radio",
value: null,
// required: false,
options: () => [
{ label: "male", value: "male" },
{ label: "female", value: "female" },
],
},
},
{
// incompleteListCount: 0,
onMount: ({ init }) => {
console.log("mounted form login :: ", init);
},
onChange: ({ newValue }) => {
console.log("changed form login :: ");
// newValue.conditions.phone.hidden = newValue.values.name == null || newValue.values.name === "";
},
},
);
```
- [@qundus/qstate][qState]
