Initial version of Lit adapter for Tanstack form

docs/framework/lit/quick-start.md

@@ -0,0 +1,105 @@
+---
+id: quick-start
+title: Quick Start
+---
+
+
+The bare minimum to get started with TanStack Form is to create `FormOptions`and a `TanstackFormController`:
+
+```ts
+import type { FormOptions } from '@tanstack/lit-form'
+
+interface Employee {
+  firstName: string
+  lastName: string
+  employed: boolean
+  jobTitle: string
+}
+
+interface Data {
+  employees: Partial<Employee>[]
+}
+
+const formConfig: FormOptions<Data> = {}
+
+#form = new TanstackFormController(this, formConfig)
+```
+
+In this example `this`references to the instance of your `LitElement` in which you want to use Tanstack Form.
+
+To wire a form element in your template up with Tanstack Form simply use the `field` method of `TanstackFormController`:
+```ts
+render() {
+ return html`
+ <p>Please enter your first name></p>
+ ${this.form.field(
+          {
+            name: `firstName`,
+            validators: {
+              onChange: ({ value }) =>
+                value.length < 3 ? 'Not long enough' : undefined,
+            },
+          },
+          (field: FieldApi<Employee, 'firstName'>) => {
+            return html` <div>
+              <label>First Name</label>
+              <input
+                id="firstName"
+                type="text"
+                placeholder="First Name"
+               @blur="${() => field.handleBlur()}"
+               .value="${field.getValue()}"
+               @input="${(event: InputEvent) => {
+                   if (event.currentTarget) {
+                     const newValue = (event.currentTarget as HTMLInputElement).value;
+                     field.handleChange(newValue);
+                   }
+               }}"
+              />
+            </div>`
+          },
+        )}`;
+}
+```
+The first parameter of `field` is `FieldOptions` and the second is callback to render your element. Be aware that you need
+to handle updating the element and form yourself as seen in the example above. If you do not want to do this, you can use
+the `bind` directive.
+
+## The `bind` directive
+Tanstack Form provides a `bind` directive which makes wiring up elements to the form a bit easier. You no longer need to
+listen to events, update form state or component state, the `bind` directive will do it for you:
+```ts
+render() {
+ return html`
+ <p>Please enter your first name></p>
+ ${this.form.field(
+          {
+            name: `firstName`,
+            validators: {
+              onChange: ({ value }) =>
+                value.length < 3 ? 'Not long enough' : undefined,
+            },
+          },
+          (field: FieldApi<Employee, 'firstName'>) => {
+            return html` <div>
+              <label>First Name</label>
+              <input
+                id="firstName"
+                type="text"
+                placeholder="First Name"
+                ${bind(field)}
+              />
+            </div>`
+          },
+        )}`;
+}
+```
+The required parameter of the `bind` directive is the instance of `FieldApi` you want to bind to.
+By default, the directive works for HTML's text inputs, checkbox inputs and selects.
+
+If you want to make it work for custom
+elements you can provide a function as an optional argument, which tells the directive how to wire up to your custom elements.
+This function has the following signature: `<T extends HTMLElement, Value = any>(
+element: T,
+): ControlValueAccessor<T, Value> | undefined`. `ControlValueAccessor` is a provided interface that describes how Tanstack Form
+should interact with a given element. You can find an example of this in the `ui-libraries`-example.

examples/lit/simple/.eslintrc.cjs

@@ -0,0 +1,15 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
+const config = {
+  extends: ['plugin:react/recommended', 'plugin:react-hooks/recommended'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: './tsconfig.json',
+  },
+  rules: {
+    'react/no-children-prop': 'off',
+  },
+}
+
+module.exports = config

examples/lit/simple/.gitignore

@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

examples/lit/simple/README.md

@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install`
+- `npm run dev`

examples/lit/simple/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + Lit + TS</title>
+    <script type="module" src="/src/index.ts"></script>
+  </head>
+  <body>
+    <tanstack-form-demo> </tanstack-form-demo>
+  </body>
+</html>

examples/lit/simple/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@tanstack/form-example-lit-simple",
+  "version": "0.0.1",
+  "main": "src/index.jsx",
+  "scripts": {
+    "dev": "vite --port=3001",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tanstack/lit-form": "<1.0.0",
+    "lit": "^3.1.1"
+  },
+  "devDependencies": {
+    "vite": "^5.0.10"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

examples/lit/simple/src/index.ts

@@ -0,0 +1,168 @@
+import { html, LitElement } from 'lit'
+import { customElement } from 'lit/decorators.js'
+
+import { styles } from './styles.js'
+import type { FormOptions } from '@tanstack/lit-form'
+import { TanstackFormController, bind } from '@tanstack/lit-form'
+
+import { repeat } from 'lit/directives/repeat.js'
+
+interface Employee {
+  firstName: string
+  lastName: string
+  employed: boolean
+  jobTitle: string
+}
+
+interface Data {
+  employees: Partial<Employee>[]
+}
+
+const formConfig: FormOptions<Data> = {}
+
+@customElement('tanstack-form-demo')
+export class TanstackFormDemo extends LitElement {
+  static styles = styles
+
+  #form = new TanstackFormController(this, formConfig)
+
+  render() {
+    return html`
+      <form
+        id="form"
+        @submit=${(e: Event) => {
+          e.preventDefault()
+        }}
+      >
+        <h1>Tanstack Form - Lit Demo</h1>
+        ${this.#form.field(
+          {
+            name: 'employees',
+            defaultValue: [],
+          },
+          (employeesField) => {
+            return html`${repeat(
+                employeesField.getValue(),
+                (_, index) => index,
+                (_, index) => {
+                  return html`
+                    ${this.#form.field(
+                      {
+                        name: `employees.${index}.firstName`,
+                        validators: {
+                          onChange: ({ value }: { value: string }) => {
+                            return value && value.length < 3
+                              ? 'Not long enough'
+                              : undefined
+                          },
+                        },
+                      },
+                      (field) => {
+                        return html` <div>
+                          <label>First Name</label>
+                          <input
+                            type="text"
+                            placeholder="First Name"
+                            ${bind(field)}
+                          />
+                        </div>`
+                      },
+                    )}
+                    ${this.#form.field(
+                      { name: `employees.${index}.lastName` },
+                      (lastNameField) => {
+                        return html` <div>
+                          <label>Last Name</label>
+                          <input
+                            type="text"
+                            placeholder="Last Name"
+                            ${bind(lastNameField)}
+                          />
+                        </div>`
+                      },
+                    )}
+                    ${this.#form.field(
+                      { name: `employees.${index}.employed` },
+                      (employedField) => {
+                        return html`<div>
+                            <label>Employed?</label>
+                            <input
+                              type="checkbox"
+                              @input="${() =>
+                                employedField.handleChange(
+                                  !employedField.getValue(),
+                                )}"
+                              .checked="${employedField.getValue()}"
+                              @blur="${() => employedField.handleBlur()}"
+                            />
+                          </div>
+                          ${employedField.getValue()
+                            ? this.#form.field(
+                                {
+                                  name: `employees.${index}.jobTitle`,
+                                  validators: {
+                                    onChange: ({
+                                      value,
+                                    }: {
+                                      value: string
+                                    }) => {
+                                      return value.length === 0
+                                        ? 'Needs to have a job here'
+                                        : null
+                                    },
+                                  },
+                                },
+                                (jobTitleField) => {
+                                  return html` <div>
+                                    <label>Job Title</label>
+                                    <input
+                                      type="text"
+                                      placeholder="Job Title"
+                                      ${bind(jobTitleField)}
+                                    />
+                                  </div>`
+                                },
+                              )
+                            : ''} `
+                      },
+                    )}
+                  `
+                },
+              )}
+
+              <div>
+                <button
+                  type="button"
+                  @click=${() => {
+                    employeesField.pushValue({
+                      firstName: '',
+                      lastName: '',
+                      employed: false,
+                    })
+                  }}
+                >
+                  Add employee
+                </button>
+              </div> `
+          },
+        )}
+
+        <div>
+          <button type="submit" ?disabled=${this.#form.api.state.isSubmitting}>
+            ${this.#form.api.state.isSubmitting ? html` Submitting` : 'Submit'}
+          </button>
+          <button
+            type="button"
+            id="reset"
+            @click=${() => {
+              this.#form.api.reset()
+            }}
+          >
+            Reset
+          </button>
+        </div>
+      </form>
+      <pre>${JSON.stringify(this.#form.api.state, null, 2)}</pre>
+    `
+  }
+}