@effect-app/vue-components 0.3.3 → 0.4.2

package/src/stories/OmegaForm/OneHundredWaysToWriteAForm.vue

@@ -0,0 +1,188 @@
+<template>
+  <div class="container">
+  <h1>One hundred ways to write a form</h1>
+  <p>
+    OmegaForm is a powerful and flexible form library that wraps
+    <a href="https://tanstack.com/form/latest" target="_blank">TanStack Form</a>
+    and uses
+    <a href="https://effect.website/docs/schema/introduction/" target="_blank">
+      Effect Schema
+    </a>
+    as the schema definition. All of this allows you to create forms in a
+    declarative way. 
+    We also use
+    <a href="https://vuetifyjs.com/" target="_blank">Vuetify</a> as peer dependency
+    for the UI components, but you can use any other UI library you want or custom inputs.
+    Here are some examples of how to write forms using
+    different approaches
+  </p>
+  <p>for our example, we will use the following dependencies</p>
+  <pre v-highlightjs><code class="javascript">{{ `import { S } from "effect-app"
+import { OmegaForm, OmegaInput, useOmegaForm } from "@effect-app/vue-components"` }}</code></pre>
+
+  <h2>Simplest way</h2>
+  <p>Now, let's write a form using the following schema:</p>
+  <pre v-highlightjs><code class="typescript">{{ `const schema = S.Struct({
+  name: S.String,
+  age: S.Number,
+})` }}</code></pre>
+
+  <p>Now, let's write in the template the form using the following schema:</p>
+  <pre
+    v-highlightjs
+  ><code class="vue">{{ `<OmegaForm :schema="schema" :on-submit="console.log">
+  <template #internalForm="{ form }">
+    <OmegaInput label="name" :form="form" name="name" />
+    <OmegaInput label="age" :form="form" name="age" />
+  </template>
+</OmegaForm>` }}</code></pre>
+
+  <OmegaForm :schema="schema" :on-submit="console.log">
+    <template #internalForm="{ form }">
+      <OmegaInput label="name" :form="form" name="name" />
+      <OmegaInput label="age" :form="form" name="age" />
+    </template>
+  </OmegaForm>
+
+  <p>
+    <code>OmegaInput</code>
+    is a component that will render a form input based on the schema. It's
+    alread embedded inside the
+    <code>OmegaForm</code>
+    component, so you don't need to import it separately or pass form as a prop:
+  </p>
+  <pre v-highlightjs><code class="vue">{{ `<OmegaForm :schema="schema">
+  <template #internalForm="{ form }">
+    <component :is="form.Input" label="name" name="name" />
+    <component :is="form.Input" label="age" name="age" />
+  </template>
+</OmegaForm>` }}</code></pre>
+  <p>you can also register to the values via the `subscribe` prop</p>
+  <pre
+    v-highlightjs
+  ><code class="vue">{{ `<OmegaForm :schema="schema" :subscribe="['values']">
+    <template #internalForm="{ form, subscribedValues: { values } }">
+      <component :is="form.Input" label="name" name="name" />
+      <component :is="form.Input" label="age" name="age" />
+      <pre>\{\{ values \}\}</pre>
+    </template>
+  </OmegaForm>` }}</code></pre>
+
+  <OmegaForm :schema="schema" :subscribe="['values']">
+    <template #internalForm="{ form, subscribedValues: { values } }">
+      <component :is="form.Input" label="name" name="name" />
+      <component :is="form.Input" label="age" name="age" />
+      <pre>{{ values }}</pre>
+    </template>
+  </OmegaForm>
+
+  <h2>Using the useOmegaForm hook</h2>
+  <p>
+    The useOmegaForm hook is a hook that returns the form instance and the
+    values. It's a good way to create a form in a functional way.
+  </p>
+  <pre
+    v-highlightjs
+  ><code class="typescript">{{ `const form = useOmegaForm(schema)` }}</code></pre>
+  <p>
+    Now, you can use the form instance to create the form in the template.
+  </p>
+  <pre v-highlightjs><code class="vue">{{ `<OmegaForm :form="form">
+    <form.Input" label="name" name="name" />
+    <form.Input" label="age" name="age" />
+</OmegaForm>` }}</code></pre>
+
+  <p>you can still register to the values via the `subscribe` prop</p>
+  <pre
+    v-highlightjs
+  ><code class="vue">{{ `<OmegaForm :form="form" :subscribe="['values']">
+    <template #externalForm="{ subscribedValues: { values } }">
+      <form.Input" label="name" name="name" />
+      <form.Input" label="age" name="age" />
+      <pre>\{\{ values \}\}</pre>
+    </template>
+  </OmegaForm>` }}</code></pre>
+  <p>
+    <strong>Note:</strong> the template name is <code>externalForm</code>
+    because the form is not inside the component, it's outside. And you don't
+    have access to the form instance inside the template variables anymore.
+  </p>
+
+  <h3>Using custom inputs</h3>
+  <p>
+    You can use custom inputs by passing an OmegaInput a child component.
+  </p>
+  <pre v-highlightjs><code class="vue">{{ `<OmegaForm :form="form">
+  <form.Input label="name" name="name">
+    <template #default="{ field, label }">
+      <label :for="name">\{\{ label \}\}</label>
+      <input
+        :id="name"
+        v-model="field.state.value"
+        :name="name"
+        style="border: 1px solid red"
+        @change="(e) => field.handleChange(e.target.value)"
+      />
+    </template>
+  </form.Input>
+</OmegaForm>` }}</code></pre>
+  <OmegaForm :form="form">
+    <form.Input label="name" name="name">
+      <template #default="{ field, label, name }">
+        <label :for="name">{{ label }}</label>
+        <input
+          :id="name"
+          v-model="field.state.value"
+          :name="name"
+          style="border: 1px solid red"
+          @change="(e: any) => field.handleChange(e.target.value)"
+        />
+      </template>
+    </form.Input>
+  </OmegaForm>
+  <h3>Known issues</h3>
+  <p>
+    You can't write something like this:
+  </p>
+  <pre v-highlightjs><code class="vue">{{ `<OmegaForm :schema="schema">
+  <template #internalForm="{ form }">
+    <form.Input label="name" name="name" />
+    <form.Input label="age" name="age" />
+  </template>
+</OmegaForm>` }}</code></pre>
+  <p>
+    because When Vue's template compiler encounters <code>form.Input</code>, it try to resolve or analyze the form object and its Input property earlier in the rendering pipeline. Since form.Input is provided by the parent OmegaForm through the slot, this direct usage inside the slot might create a tighter, more immediate dependency loop that the compiler/renderer detects or falls into, leading to the stack overflow.
+  </p>
+</div>
+</template>
+
+<script setup lang="ts">
+import { S } from "effect-app"
+import { OmegaForm, OmegaInput, useOmegaForm } from "../../components/OmegaForm"
+
+const schema = S.Struct({
+  name: S.String,
+  age: S.Number,
+})
+const form = useOmegaForm(schema)
+</script>
+
+<style scoped>
+p,
+pre {
+  margin-bottom: 1rem;
+}
+form {
+  margin-bottom: 2rem;
+}
+
+.container {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0 1rem;
+}
+
+h1, h2, h3 {
+  text-wrap: balance;
+}
+</style>

package/src/stories/OmegaForm/PersistencyForm.vue

@@ -4,17 +4,17 @@
     :subscribe="['errors', 'values']"
     show-errors-on="onChange"
   >
-    <template #default="{ form, subscribedValues: { errors, values } }">
+    <template #externalForm="{ subscribedValues: { errors, values: vvv } }">
       <div>Errors: {{ errors }}</div>
-      <div>Values: {{ values }}</div>
-      <OmegaInput label="first" :form="form" name="first" />
+      <div>Values: {{ vvv }}</div>
+      <OmegaInput label="first" :form="addForm" name="first" />
       <div>+</div>
-      <OmegaInput label="second" :form="form" name="second" />
+      <OmegaInput label="second" :form="addForm" name="second" />
       <br />
       <hr />
       <br />
-      <OmegaInput label="third.fourth" :form="form" name="third.fourth" />
-      <OmegaInput label="third.fifth" :form="form" name="third.fifth" />
+      <OmegaInput label="third.fourth" :form="addForm" name="third.fourth" />
+      <OmegaInput label="third.fifth" :form="addForm" name="third.fifth" />
     </template>
   </OmegaForm>
 

package/src/stories/OmegaForm/SimpleForm.vue

@@ -1,6 +1,6 @@
 <template>
   <OmegaForm :schema="schema" :on-submit="onSubmit" :subscribe="['values']">
-    <template #default="{ form, subscribedValues: { values } }">
+    <template #internalForm="{ form, subscribedValues: { values } }">
       <div>values: {{ values }}</div>
       <OmegaInput label="asder2" name="asder2" :form="form">
         <template #default="inputProps">

package/src/stories/OmegaForm/SimpleFormVuetifyDefault.vue

@@ -1,6 +1,6 @@
 <template>
   <OmegaForm :schema="schema" :subscribe="['values']">
-    <template #default="{ form, subscribedValues: { values } }">
+    <template #internalForm="{ form, subscribedValues: { values } }">
       <OmegaInput label="aString" :form="form" name="aString" />
       <pre>{{ values }}</pre>
     </template>

package/src/stories/OmegaForm/SumExample.vue

@@ -1,10 +1,8 @@
 <template>
   <OmegaForm :form="addForm">
-    <template #default="{ form }">
-      <OmegaInput label="first" :form="form" name="first" />
-      <div>+</div>
-      <OmegaInput label="second" :form="form" name="second" />
-    </template>
+    <OmegaInput label="first" :form="addForm" name="first" />
+    <div>+</div>
+    <OmegaInput label="second" :form="addForm" name="second" />
   </OmegaForm>
 
   <!-- Technically you can do this only with a subscribe but only inside OmegaForm Context -->

package/src/stories/OmegaForm/form.Input.vue

@@ -0,0 +1,86 @@
+<template>
+  <OmegaForm
+    :schema="S.Struct({ myString: S.String })"
+    :on-submit="console.log"
+  >
+    <template #internalForm="{ form }">
+      <component :is="form.Input" label="myString" name="myString" />
+    </template>
+  </OmegaForm>
+  <OmegaForm :form="exampleForm">
+    <exampleForm.Input label="aString" name="aString" />
+    <exampleForm.Input label="aStringMin2" name="aStringMin2" />
+    <exampleForm.Input label="aStringMin2Max4" name="aStringMin2Max4" />
+    <exampleForm.Input
+      label="aStringMin2Max3Nullable"
+      name="aStringMin2Max3Nullable"
+    />
+    <exampleForm.Input label="aNumber" name="aNumber" />
+    <exampleForm.Input label="aNumberMin2" name="aNumberMin2" />
+    <exampleForm.Input label="aNumberMin2Max" name="aNumberMin2Max" />
+    <exampleForm.Input
+      label="aNumberMin2Max4Nullable"
+      name="aNumberMin2Max4Nullable"
+    />
+    <exampleForm.Input
+      label="aSelect"
+      name="aSelect"
+      :options="[
+        { title: 'a', value: 'a' },
+        { title: 'b', value: 'b' },
+        { title: 'c', value: 'c' },
+      ]"
+    />
+    <button>Submit</button>
+    <button type="reset" @click.prevent="exampleForm.clear()">Clear</button>
+    <button type="button" @click="exampleForm.reset()">Reset</button>
+  </OmegaForm>
+</template>
+
+<script setup lang="ts">
+import { S } from "effect-app"
+import { OmegaForm, useOmegaForm } from "../../components/OmegaForm"
+
+const schema = S.Struct({
+  aString: S.String,
+  aStringMin2: S.String.pipe(S.minLength(2)),
+  aStringMin2Max4: S.String.pipe(S.minLength(2)).pipe(S.maxLength(4)),
+  aStringMin2Max3Nullable: S.UndefinedOr(
+    S.String.pipe(S.minLength(2)).pipe(S.maxLength(3)),
+  ),
+  aNumber: S.Number,
+  aNumberMin2: S.Number.pipe(S.greaterThan(2)),
+  aNumberMin2Max: S.Number.pipe(S.greaterThan(2)).pipe(S.lessThan(4)),
+  aNumberMin2Max4Nullable: S.NullOr(S.Number.pipe(S.between(2, 4))),
+  aSelect: S.Union(S.Literal("a"), S.Literal("b"), S.Literal("c")),
+})
+
+const exampleForm = useOmegaForm(
+  schema,
+  {
+    onSubmit: ({
+      value,
+    }: {
+      value: {
+        aString: string
+        aStringMin2: string
+        aStringMin2Max4: string
+        aStringMin2Max3Nullable?: string
+        aNumber: number
+        aNumberMin2: number
+        aNumberMin2Max: number
+        aNumberMin2Max4Nullable: number | null
+        aSelect: "a" | "b" | "c"
+      }
+    }) => {
+      console.log(value)
+    },
+  },
+  {
+    persistency: {
+      policies: ["local"],
+      overrideDefaultValues: true,
+    },
+  },
+)
+</script>

package/src/stories/OmegaForm.stories.ts

@@ -10,6 +10,8 @@ import SimpleFormVuetifyDefault from "./OmegaForm/SimpleFormVuetifyDefault.vue"
 import SumExample from "./OmegaForm/SumExample.vue"
 import PersistencyForm from "./OmegaForm/PersistencyForm.vue"
 import MetaForm from "./OmegaForm/Meta.vue"
+import FormInput from "./OmegaForm/form.Input.vue"
+import OneHundredWaysToWriteAForm from "./OmegaForm/OneHundredWaysToWriteAForm.vue"
 
 const mockIntl = {
   locale: ref("en"),
@@ -20,7 +22,6 @@ const mockIntl = {
 const meta: Meta<typeof OmegaForm> = {
   title: "Components/OmegaForm",
   component: OmegaForm,
-  tags: ["autodocs"],
   argTypes: {
     schema: { control: "object" },
     onSubmit: { action: "submitted" },
@@ -41,6 +42,13 @@ const meta: Meta<typeof OmegaForm> = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+export const AnHundredWayToWriteAFormStory: Story = {
+  render: () => ({
+    components: { OneHundredWaysToWriteAForm },
+    template: "<OneHundredWaysToWriteAForm />",
+  }),
+}
+
 export const SimpleFormStory: Story = {
   render: () => ({
     components: { SimpleForm },
@@ -89,3 +97,10 @@ export const MetaStory: Story = {
     template: "<MetaForm />",
   }),
 }
+
+export const FormInputStory: Story = {
+  render: () => ({
+    components: { FormInput },
+    template: "<FormInput />",
+  }),
+}