@whatsaaaa/form-builder-vue 0.3.0 → 0.3.1

package/README.md

@@ -1,20 +1,26 @@
 # @whatsaaaa/form-builder-vue
 
-[![npm](https://img.shields.io/npm/v/@whatsaaaa/form-builder-vue)](https://www.npmjs.com/package/@whatsaaaa/form-builder-vue)
-
 Render JSON form definitions with [Formisch](https://formisch.dev) and your own Vue components.
 
-It's headless: it reads the definition, connects every field to Formisch and turns input into the values the schema expects, but it renders nothing of its own. You give it a component per field type, so it works with plain HTML, Nuxt UI or any other UI library.
+[![npm version](https://img.shields.io/npm/v/@whatsaaaa/form-builder-vue)](https://www.npmjs.com/package/@whatsaaaa/form-builder-vue)
+[![npm downloads](https://img.shields.io/npm/dm/@whatsaaaa/form-builder-vue)](https://www.npmjs.com/package/@whatsaaaa/form-builder-vue)
+[![CI](https://img.shields.io/github/actions/workflow/status/whatsaaaa/form-builder/ci.yml?branch=main&label=CI)](https://github.com/whatsaaaa/form-builder/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/whatsaaaa/form-builder/graph/badge.svg?flag=vue)](https://codecov.io/gh/whatsaaaa/form-builder)
+[![Vue](https://img.shields.io/npm/dependency-version/@whatsaaaa/form-builder-vue/peer/vue?logo=vuedotjs)](https://vuejs.org)
+[![Types](https://img.shields.io/npm/types/@whatsaaaa/form-builder-vue)](https://www.npmjs.com/package/@whatsaaaa/form-builder-vue)
+[![License](https://img.shields.io/npm/l/@whatsaaaa/form-builder-vue)](https://github.com/whatsaaaa/form-builder/blob/main/LICENSE)
+
+This is the Vue adapter of [form-builder](https://github.com/whatsaaaa/form-builder). It is headless: it reads the definition, connects every field to Formisch and turns input into the values the schema expects, but renders nothing of its own. You give it a component per field type, so it works with plain HTML, Nuxt UI or any other UI library.
 
 ## Install
 
 ```sh
-pnpm add @whatsaaaa/form-builder-vue @formisch/vue valibot
+pnpm add @whatsaaaa/form-builder-vue @whatsaaaa/form-builder-schema @formisch/vue valibot
 ```
 
-Vue 3.5, `@formisch/vue` 1.1 and Valibot 1.3 or later are required. `@whatsaaaa/form-builder-schema` comes with it.
+Vue 3.5, `@formisch/vue` 1.1 and Valibot 1.3 or later are required. Install `@whatsaaaa/form-builder-schema` too: the examples import its types, such as `JsonForm`.
 
-## Usage
+## Example
 
 ```vue
 <script setup lang="ts">
@@ -40,58 +46,7 @@ function save(output: unknown) {
 </template>
 ```
 
-- `useJsonForm(definition, options?)` builds the schema and the initial input, and creates the Formisch form. `jsonForm.form` is a normal Formisch form, so every Formisch method works on it.
-- `<JsonFields>` renders the fields inside your `<Form>`. The form element, the submit button and anything around them are yours.
-- A definition with issues throws the builder's `DefinitionError`. Run `validate()` first when the definition comes from outside your code.
-- The definition is read once. To show another one, give the component that calls `useJsonForm` a new `:key`.
-
-### Options
-
-```ts
-useJsonForm(definition, {
-  builder: createSchemaBuilder({ fieldTypes: { money } }), // your own types, rules and messages
-  components, // your component per field type, see below
-  layoutComponents, // your component per layout type, see Layout
-  validate: 'blur', // when a field is validated the first time, as in Formisch
-  revalidate: 'input', // when it is validated again
-})
-```
-
-## Components
-
-`components` has one component per field type, by type name. Pass it to `useJsonForm`, or to `<JsonFields>` and `<JsonField>` as a prop, which wins. Several types can share one:
-
-```ts
-import type { FieldComponents } from '@whatsaaaa/form-builder-vue'
-
-export const components: FieldComponents = {
-  text: TextInput,
-  email: TextInput,
-  number: TextInput,
-  select: SelectInput,
-  group: Fieldset,
-  array: Repeater,
-  heading: Heading,
-  // …one for every type your definitions use
-}
-```
-
-A type that a definition uses but `components` doesn't have throws a `TypeError` that names every missing type, when `<JsonFields>` or `<JsonField>` sets up. Only the fields it renders count.
-
-What a component gets depends on the field's role:
-
-| Role    | Which fields                   | Props                                                                            | Slot                                         |
-| ------- | ------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------- |
-| value   | every field with a value       | `field`, `path`, `kind`, `required`, `input`, `errors`, `inputProps`, `setInput` | —                                            |
-| group   | a container of kind `object`   | `field`, `path`                                                                  | default: the group's fields                  |
-| array   | a container of kind `array`    | `field`, `path`, `items`, `errors`, `add`, `remove`, `move`                      | default, with `{ index }`: one item's fields |
-| display | a display element, kind `none` | `field`                                                                          | —                                            |
-
-The props are typed as `ValueFieldProps`, `GroupFieldProps`, `ArrayFieldProps` and `DisplayFieldProps`, and the slots as `GroupFieldSlots` and `ArrayFieldSlots`. `defineProps<ValueFieldProps>()` works in `<script setup>`.
-
-Your own container types render through the group or array role too, by their kind.
-
-### A value field
+`components` maps each field type to a component of yours. A text input looks like this:
 
 ```vue
 <script setup lang="ts">
@@ -115,275 +70,28 @@ defineProps<ValueFieldProps>()
 </template>
 ```
 
-- `field` is the field from the definition, with its `label`, `placeholder`, `options` and `ui`.
-- `path` is its Formisch path with real indexes, like `['lines', 0, 'quantity']`.
-- `inputProps` are Formisch's element props: the field's name, a ref, and focus, change and blur handlers. Bind them to the input element, so Formisch knows when the field is touched and can focus it after a failed submit.
-- `required` is true when the definition makes the field required.
-
-### setInput
-
-`setInput` sets the field's input after turning what an input element gives into what the schema expects, by the field's kind:
-
-| Kind                | Input                   | Value set                      |
-| ------------------- | ----------------------- | ------------------------------ |
-| `number`            | `''` or only spaces     | `undefined`                    |
-| `number`            | a numeric string, `'5'` | `5`                            |
-| `file`              | a `FileList`            | its first file, or `undefined` |
-| `array` of `file`   | a `FileList`            | an array of its files          |
-| `array` of `number` | numeric strings         | numbers                        |
-
-Anything else is set as it is, and the schema reports it. For a choice, like a radio or a select, set the option's value from `field.options` rather than the element's value: that keeps `2` a number and `true` a boolean.
-
-### A group
-
-```vue
-<script setup lang="ts">
-import type { GroupFieldProps, GroupFieldSlots } from '@whatsaaaa/form-builder-vue'
-
-defineProps<GroupFieldProps>()
-defineSlots<GroupFieldSlots>()
-</script>
-
-<template>
-  <fieldset>
-    <legend>{{ field.label }}</legend>
-    <slot />
-  </fieldset>
-</template>
-```
-
-### An array
-
-```vue
-<script setup lang="ts">
-import type { ArrayFieldProps, ArrayFieldSlots } from '@whatsaaaa/form-builder-vue'
-
-defineProps<ArrayFieldProps>()
-defineSlots<ArrayFieldSlots>()
-</script>
-
-<template>
-  <fieldset>
-    <legend>{{ field.label }}</legend>
-    <div v-for="(item, index) in items" :key="item">
-      <slot :index="index" />
-      <button type="button" @click="remove(index)">Remove</button>
-    </div>
-    <button type="button" @click="add()">Add</button>
-    <small v-if="errors">{{ errors[0] }}</small>
-  </fieldset>
-</template>
-```
-
-- `items` has one id per item. Use it as the `key`, so each item keeps its inputs when one is removed or moved.
-- `add()` adds an item at the end, with the defaults its fields have in the definition.
-- `errors` are the array's own messages, like a required array's or `maxLength`'s. Its items' fields show their own.
-
-### A display element
-
-```vue
-<script setup lang="ts">
-import type { DisplayFieldProps } from '@whatsaaaa/form-builder-vue'
-
-defineProps<DisplayFieldProps>()
-</script>
-
-<template>
-  <h2>{{ field.text }}</h2>
-</template>
-```
-
-Declare the props even when a component doesn't use them, like a divider, or Vue adds `field` to its element as an attribute.
-
-## Layout
-
-A definition's [`layout`](https://github.com/whatsaaaa/form-builder/tree/main/packages/schema#layout) puts its fields in sections, rows of a 12-column grid and steps, and leaves slots for content of yours. `<JsonFields>` renders the current step of it. Give `useJsonForm` a component for each layout type the definition uses, and `<JsonFields>` a named slot for each of its slots:
-
-```vue
-<!-- Row.vue: one line of a 12-column grid. On a narrow screen, give each cell the whole row. -->
-<script setup lang="ts">
-import type { RowProps, RowSlots } from '@whatsaaaa/form-builder-vue'
-
-defineProps<RowProps>()
-defineSlots<RowSlots>()
-</script>
-
-<template>
-  <div class="row">
-    <div v-for="(span, index) in spans" :key="index" :style="{ gridColumn: `span ${span}` }">
-      <slot :index="index" />
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.row {
-  display: grid;
-  grid-template-columns: repeat(12, 1fr);
-  gap: 1rem;
-}
-</style>
-```
-
-```vue
-<!-- Section.vue -->
-<script setup lang="ts">
-import type { SectionProps, SectionSlots } from '@whatsaaaa/form-builder-vue'
+`jsonForm.form` is a normal Formisch form, so every Formisch method works on it.
 
-defineProps<SectionProps>()
-defineSlots<SectionSlots>()
-</script>
+## Highlights
 
-<template>
-  <fieldset>
-    <legend>{{ section.label }}</legend>
-    <slot />
-  </fieldset>
-</template>
-```
+- Headless: one component of yours per field type, and per layout type
+- `setInput` turns what an element gives into the value the schema expects
+- Groups, arrays and display elements, with stable keys for array items
+- Sections, 12-column rows, slots and multi-step forms from the definition's layout
+- Steps that validate on Next and only show errors the user has seen
+- Conditions from the affects package, with hidden steps skipped by Next and Back
+- Fields placed in your own markup with `<JsonField>`, `only` and `except`
 
-```vue
-<script setup lang="ts">
-const jsonForm = useJsonForm(definition, {
-  components,
-  layoutComponents: { section: Section, row: Row },
-})
-</script>
+## Documentation
 
-<template>
-  <Form :of="jsonForm.form" @submit="save">
-    <JsonFields :of="jsonForm">
-      <template #submit><button type="submit">Place order</button></template>
-    </JsonFields>
-  </Form>
-</template>
-```
-
-| Layout type | Props                                                                     | Slot                                           |
-| ----------- | ------------------------------------------------------------------------- | ---------------------------------------------- |
-| `section`   | `section`, as written, with its `id`, `label`, `description` and `ui`     | default: the section's items                   |
-| `row`       | `row`, as written, with its `id` and `ui`; `spans`, the span of each cell | default, with `{ index }`: the cell at `index` |
-
-The props are typed as `SectionProps` and `RowProps`, and the slots as `SectionSlots` and `RowSlots`.
-
-- `layoutComponents` goes to `useJsonForm`, or to `<JsonFields>` as a prop, which wins. A definition without sections or rows needs none, and one without a `layout` renders as it always did.
-- A layout type the layout uses without a component, or a slot without content, throws a `TypeError` naming each one when `<JsonFields>` sets up, on every step.
-- Display elements written in the layout render with your field components, like the ones in `fields`.
-- `except` leaves fields out of the layout too, and a section or a row left without fields drops out. The other cells of a row keep their spans. `only` renders the fields it names without the layout.
-- The spans are for a wide screen: the layout says nothing about narrow ones, so your row component decides, e.g. with a media query.
+The [guide](https://github.com/whatsaaaa/form-builder/blob/main/frameworks/vue/docs/guide.md) covers options, components for every role, layout, steps, conditions, placing fields yourself and typing the form.
 
-### Steps
-
-`jsonForm.steps` is where the form is, and how to move. It is reactive, so templates follow it:
-
-```vue
-<template>
-  <Form :of="jsonForm.form" @submit="save">
-    <ol>
-      <li
-        v-for="(step, i) in jsonForm.steps.list"
-        :key="step.step.id ?? i"
-        :aria-current="i === jsonForm.steps.index ? 'step' : undefined"
-      >
-        {{ step.step.label }}
-      </li>
-    </ol>
-    <JsonFields :of="jsonForm" />
-    <button v-if="!jsonForm.steps.isFirst" type="button" @click="jsonForm.steps.back()">
-      Back
-    </button>
-    <button v-if="!jsonForm.steps.isLast" type="button" @click="jsonForm.steps.next()">Next</button>
-    <button v-else type="submit">Sign up</button>
-  </Form>
-</template>
-```
-
-| Member              |                                                                                                                                                                                                    |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `list`              | the steps on show, each with its `step` as written (`id`, `label`, `description`, `ui`), `children` and `fields`: a step that [conditions](#conditions) hide is left out, unless the user is on it |
-| `index`, `current`  | the step `<JsonFields>` renders                                                                                                                                                                    |
-| `isFirst`, `isLast` |                                                                                                                                                                                                    |
-| `next()`            | validates, and moves on when the step's fields have no issues. Resolves to whether it moved                                                                                                        |
-| `back()`            | moves back, without validating                                                                                                                                                                     |
-| `goTo(index)`       | back freely; forward through each step on the way, stopping at the first with issues                                                                                                               |
-
-The form is one Formisch form, so Formisch validates all of it at once. The steps make that work:
-
-- **Next** validates the whole form, and only the issues on the current step's fields keep the user there. It focuses the first one, in layout order.
-- **A step shows what the user left**: the errors it had when they left it, and none the first time they get to it, so the issues of steps nobody saw yet stay out of sight.
-- **A step that failed Next revalidates** as the user fixes it, on the `revalidate` event, like a form after a failed submit.
-- **A submit before the last step is a Next**, so Enter in a step with a single text input doesn't submit the form early. On the last step, Formisch submits as usual.
-- **A submit that fails because of an earlier step**, like a form rule that reads fields of two steps, goes back to that step.
-- `<JsonFields :step="2" />` renders a given step instead of the current one, e.g. on a review page. A form without steps has one, and nothing changes for it.
-
-## Conditions
-
-With the [affects package](https://github.com/whatsaaaa/form-builder/tree/main/packages/affects), fields, sections and steps show and hide by the values of other fields. Pass `useJsonForm` a builder with the extension:
-
-```ts
-import { affects } from '@whatsaaaa/form-builder-affects'
-
-const builder = createSchemaBuilder({ extensions: [affects()] })
-const jsonForm = useJsonForm(definition, { builder, components, layoutComponents })
-```
-
-- **`<JsonFields>` and `<JsonField>` leave out what the conditions hide**: a hidden field, a hidden section, and a group, section or row whose fields are all hidden. A field hidden in a row drops out of it, and the others keep their spans.
-- **Steps skip the hidden ones.** `steps.list` holds the steps on show, so a step whose fields are all hidden is left out, and Next and Back go past it. The step the user is on stays, until they leave it.
-- **`useJsonForm` clears what `hideAndClear` clears**, with Formisch's `setInput`, as soon as it is cleared, wherever the field renders: in `<JsonFields>`, with `<JsonField>`, or by your own code. A field that starts hidden this way starts blank.
-- **The schema skips hidden fields**, so they never block the form, and submits what the affects package says.
-- **`jsonForm.visibility`** is the state for the form's input now, for your own renderers: `isHidden(node, indexes)`, `isStepHidden(step)`, `shownNodes(nodes, indexes)`. It is a new object only when what is hidden changes.
-
-Without conditions, nothing is hidden, and nothing changes.
-
-## Placing fields yourself
-
-Without a `layout`, `<JsonFields>` renders every field in the order of the definition. To put some of them somewhere else, in code rather than in the definition, place them with `<JsonField>` and leave them out of `<JsonFields>` with `except`:
-
-```vue
-<template>
-  <Form :of="jsonForm.form" @submit="save">
-    <main>
-      <JsonFields :of="jsonForm" :except="['coupon', 'acceptTerms']" />
-    </main>
-    <aside>
-      <JsonField :of="jsonForm" path="coupon" />
-      <JsonField :of="jsonForm" path="acceptTerms" />
-      <button type="submit">Place order</button>
-    </aside>
-  </Form>
-</template>
-```
-
-- A path is the field's names joined with dots: `'email'`, or `'address.city'` for a field of a group. A placed field validates, focuses and submits like any other, because it is still part of the one Formisch form.
-- A group or an array comes with all its fields. A field of an array's items can't be placed on its own, because it has no index outside its item, so place the array. To leave such a field out of every item, use `'*'` for the index: `except: ['lines.*.note']`.
-- `only` renders just the fields it names, in the order of the definition: `<JsonFields :of="jsonForm" :only="['name', 'email']" />`. Display elements have no dot path, even with a name, so `only` leaves them out.
-- A path that names no field throws a `TypeError`, so a typo shows up at once. `only` and `except` are read when the component sets up.
-
-## Typing the form
-
-The definition is data, so TypeScript doesn't know its fields, and `jsonForm.form` is typed loosely: Formisch's own functions accept only top-level paths on it. Give `useJsonForm` your input type, and your output type when it differs, and they check paths and values as in any Formisch form:
-
-```ts
-import { getInput, useFieldArray } from '@formisch/vue'
-
-interface CheckoutInput {
-  name: string
-  address: { city: string }
-  lines: { product: string; quantity: number }[]
-}
-
-const jsonForm = useJsonForm<CheckoutInput>(definition, { components })
-
-getInput(jsonForm.form, { path: ['address', 'city'] }) // string | undefined
-useFieldArray(jsonForm.form, { path: ['lines'] })
-```
+## Related packages
 
-- Formisch's `<Field>`, `<FieldArray>`, `useField`, `getInput` and `setInput` work on `jsonForm.form` either way. With a type, nested paths type-check, their values are typed, and so is the output your submit handler gets.
-- The type is a promise you make: nothing checks it against the definition. Keep the two in step.
-- A field you render with Formisch's `<Field>` gets none of the adapter's help, like `setInput` turning `'5'` into `5`, or the defaults of a new array item. Leave it out of `<JsonFields>` with `except`.
+- [`@whatsaaaa/form-builder-schema`](https://github.com/whatsaaaa/form-builder/tree/main/packages/schema): build Formisch-ready Valibot schemas from JSON definitions
+- [`@whatsaaaa/form-builder-affects`](https://github.com/whatsaaaa/form-builder/tree/main/packages/affects): show, hide and clear fields by conditions
+- [`@whatsaaaa/form-builder-react`](https://github.com/whatsaaaa/form-builder/tree/main/frameworks/react): the same adapter for React
 
-## Not included
+## License
 
-- Labels and display text reach your components as written in the definition. The builder's `resolveMessage` only changes what goes into the schema, so translate `field.label` in your components.
-- `ui.widget` doesn't pick a component. A component can read `field.ui` itself, e.g. to show a multiselect as checkboxes.
-- Showing and hiding fields, or making one required because of another, belongs to a future affects package. The layout already hides a section, a row or a step whose fields are all hidden, through `shownNodes` in the schema package.
+[MIT](https://github.com/whatsaaaa/form-builder/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whatsaaaa/form-builder-vue",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Render JSON form definitions with Formisch and your own Vue components.",
   "keywords": [
     "form",
@@ -33,12 +33,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@whatsaaaa/form-builder-schema": "^0.15.0"
+    "@whatsaaaa/form-builder-schema": "^0.15.1"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@formisch/vue": "^1.1.1",
-    "@whatsaaaa/form-builder-affects": "^0.1.0",
+    "@vitest/coverage-v8": "^5.0.5",
+    "@whatsaaaa/form-builder-affects": "^0.1.1",
     "happy-dom": "^20.0.0",
     "publint": "^0.3.25",
     "tsdown": "^0.23.2",
@@ -55,6 +56,7 @@
   "scripts": {
     "build": "tsdown",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "type-check": "tsc --noEmit",
     "lint:pkg": "publint && pnpm pack --pack-destination .attw && attw .attw/*.tgz --profile esm-only"
   }