From 8bbc1e13f0473004f74cb403ef26cc1544647ebc Mon Sep 17 00:00:00 2001
From: Davide Di Pumpo <davidemak@gmail.com>
Date: Mon, 20 Oct 2025 17:14:09 +0200
Subject: [PATCH] feat: Updates doc

---
 .../stories/OmegaForm.stories.ts              |   8 +-
 .../OmegaForm/OneHundredWaysToWriteAForm.vue  | 209 -------------
 .../stories/OmegaForm/UsingOmegaForm.vue      | 281 ++++++++++++++++++
 3 files changed, 285 insertions(+), 213 deletions(-)
 delete mode 100644 packages/vue-components/stories/OmegaForm/OneHundredWaysToWriteAForm.vue
 create mode 100644 packages/vue-components/stories/OmegaForm/UsingOmegaForm.vue

diff --git a/packages/vue-components/stories/OmegaForm.stories.ts b/packages/vue-components/stories/OmegaForm.stories.ts
index 41f06962af..0c99c1e77c 100644
--- a/packages/vue-components/stories/OmegaForm.stories.ts
+++ b/packages/vue-components/stories/OmegaForm.stories.ts
@@ -15,7 +15,6 @@ import FormInputComponent from "./OmegaForm/form.Input.vue"
 import IntersectionExampleComponent from "./OmegaForm/IntersectionExample.vue"
 import MetaFormComponent from "./OmegaForm/Meta.vue"
 import NullComponent from "./OmegaForm/Null.vue"
-import OneHundredWaysToWriteAFormComponent from "./OmegaForm/OneHundredWaysToWriteAForm.vue"
 import PersistencyFormComponent from "./OmegaForm/PersistencyForm.vue"
 import ProgrammaticallyHandleSubmitCheckErrorsComponent from "./OmegaForm/ProgrammaticallyHandleSubmitCheckErrors.vue"
 import SetErrorOnSubmitComponent from "./OmegaForm/SetErrorOnSubmit.vue"
@@ -24,6 +23,7 @@ import SimpleFormVuetifyDefaultComponent from "./OmegaForm/SimpleFormVuetifyDefa
 import SumExampleComponent from "./OmegaForm/SumExample.vue"
 import TanstackComponent from "./OmegaForm/Tanstack.vue"
 import UnionComponent from "./OmegaForm/Union.vue"
+import UsingOmegaFormComponent from "./OmegaForm/UsingOmegaForm.vue"
 
 const mockIntl = {
   locale: ref("en"),
@@ -54,10 +54,10 @@ const meta: StoryMeta<typeof OmegaForm> = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const AnHundredWayToWriteAForm: Story = {
+export const UsingOmegaForm: Story = {
   render: () => ({
-    components: { OneHundredWaysToWriteAFormComponent },
-    template: "<OneHundredWaysToWriteAFormComponent />"
+    components: { UsingOmegaFormComponent },
+    template: "<UsingOmegaFormComponent />"
   })
 }
 
diff --git a/packages/vue-components/stories/OmegaForm/OneHundredWaysToWriteAForm.vue b/packages/vue-components/stories/OmegaForm/OneHundredWaysToWriteAForm.vue
deleted file mode 100644
index a13d71c18b..0000000000
--- a/packages/vue-components/stories/OmegaForm/OneHundredWaysToWriteAForm.vue
+++ /dev/null
@@ -1,209 +0,0 @@
-<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>
-</form.Form>` }}</code></pre>
-
-    <form.Form>
-      <form.Input
-        label="name"
-        name="name"
-      />
-      <form.Input
-        label="age"
-        name="age"
-      />
-    </form.Form>
-
-    <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>
-</form.Form>` }}</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>
-  </form.Form>` }}</code></pre>
-
-    <form.Form :subscribe="['values']">
-      <template #default="{ subscribedValues: { values } }">
-        <form.Input
-          label="name"
-          name="name"
-        />
-        <form.Input
-          label="age"
-          name="age"
-        />
-        <pre>{{ values }}</pre>
-      </template>
-    </form.Form>
-
-    <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">{{ `<form.Form>
-    <form.Input" label="name" name="name" />
-    <form.Input" label="age" name="age" />
-</form.Form>` }}</code></pre>
-
-    <p>you can still register to the values via the `subscribe` prop</p>
-    <pre v-highlightjs>
-<code class="vue">{{ `<form.Form :subscribe="['values']">
-    <template #externalForm="{ subscribedValues: { values } }">
-      <form.Input" label="name" name="name" />
-      <form.Input" label="age" name="age" />
-      <pre>\{\{ values \}\}</pre>
-    </template>
-  </form.Form>` }}</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">{{ `<form.Form>
-  <form.Input label="name" name="name">
-    <template #default="{ field, state, label }">
-      <label :for="name">\{\{ label \}\}</label>
-      <input
-        :id="name"
-        v-model="state.value"
-        :name="name"
-        style="border: 1px solid red"
-        @change="(e) => field.handleChange(e.target.value)"
-      />
-    </template>
-  </form.Input>
-</form.Form>` }}</code></pre>
-    <form.Form>
-      <form.Input
-        label="name"
-        name="name"
-      >
-        <template #default="{ field, label, state }">
-          <label :for="field.name">{{ label }}</label>
-          <input
-            :id="field.name"
-            v-model="state.value"
-            :name="field.name"
-            style="border: 1px solid red"
-            @change="(e: any) => field.handleChange(e.target.value)"
-          >
-        </template>
-      </form.Input>
-    </form.Form>
-    <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>
-</form.Form>` }}</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 { useOmegaForm } from "../../src/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>
diff --git a/packages/vue-components/stories/OmegaForm/UsingOmegaForm.vue b/packages/vue-components/stories/OmegaForm/UsingOmegaForm.vue
new file mode 100644
index 0000000000..b1565e55cd
--- /dev/null
+++ b/packages/vue-components/stories/OmegaForm/UsingOmegaForm.vue
@@ -0,0 +1,281 @@
+<template>
+  <div class="container">
+    <h1>Using OmegaForm</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. This allows you to create forms in a declarative way using the compound component
+      pattern. 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.
+    </p>
+    <p>For our examples, we will use the following dependencies:</p>
+    <pre v-highlightjs>
+<code class="javascript">{{ `import { S } from "effect-app"
+import { useOmegaForm, createUseFormWithCustomInput } from "@effect-app/vue-components"` }}</code></pre>
+
+    <h2>Basic Usage</h2>
+    <p>First, let's define a schema using Effect Schema:</p>
+    <pre v-highlightjs>
+<code class="typescript">{{ `const schema = S.Struct({
+  name: S.String,
+  age: S.Number,
+})` }}</code></pre>
+
+    <p>Then, create a form instance using the <code>useOmegaForm</code> hook:</p>
+    <pre v-highlightjs><code class="typescript">{{ `const form = useOmegaForm(schema)` }}</code></pre>
+
+    <p>Now you can use the compound component pattern in your template:</p>
+    <pre v-highlightjs>
+<code class="vue">{{ `<form.Form>
+  <form.Input label="name" name="name" />
+  <form.Input label="age" name="age" />
+</form.Form>` }}</code></pre>
+
+    <h3>Live Example</h3>
+    <form.Form>
+      <form.Input
+        label="name"
+        name="name"
+      />
+      <form.Input
+        label="age"
+        name="age"
+      />
+    </form.Form>
+
+    <h2>Subscribing to Form Values</h2>
+    <p>You can subscribe to form values using the <code>subscribe</code> prop:</p>
+    <pre v-highlightjs>
+<code class="vue">{{ `<form.Form :subscribe="['values']">
+  <template #default="{ subscribedValues: { values } }">
+    <form.Input label="name" name="name" />
+    <form.Input label="age" name="age" />
+    <pre>\{\{ values \}\}</pre>
+  </template>
+</form.Form>` }}</code></pre>
+
+    <h3>Live Example with Subscribed Values</h3>
+    <form.Form :subscribe="['values']">
+      <template #default="{ subscribedValues: { values } }">
+        <form.Input
+          label="name"
+          name="name"
+        />
+        <form.Input
+          label="age"
+          name="age"
+        />
+        <pre>{{ values }}</pre>
+      </template>
+    </form.Form>
+
+    <h2>Using Custom Inputs</h2>
+    <p>
+      You can use custom inputs by providing a default slot to <code>form.Input</code>:
+    </p>
+    <pre v-highlightjs>
+<code class="vue">{{ `<form.Form>
+  <form.Input label="name" name="name">
+    <template #default="{ field, state, label }">
+      <label :for="field.name">\{\{ label \}\}</label>
+      <input
+        :id="field.name"
+        v-model="state.value"
+        :name="field.name"
+        style="border: 1px solid red"
+        @change="(e) => field.handleChange(e.target.value)"
+      />
+    </template>
+  </form.Input>
+</form.Form>` }}</code></pre>
+
+    <h3>Live Example with Custom Input</h3>
+    <form.Form>
+      <form.Input
+        label="name"
+        name="name"
+      >
+        <template #default="{ field, label, state }">
+          <label :for="field.name">{{ label }}</label>
+          <input
+            :id="field.name"
+            v-model="state.value"
+            :name="field.name"
+            style="border: 1px solid red"
+            @change="(e: any) => field.handleChange(e.target.value)"
+          >
+        </template>
+      </form.Input>
+    </form.Form>
+
+    <h2>Creating a Custom useForm Hook</h2>
+    <p>
+      For larger applications, you may want to create your own <code>useForm</code> hook with a custom input component.
+      This is useful when you want to use a UI library other than Vuetify or apply consistent styling across all forms.
+    </p>
+
+    <h3>Define Your Custom Input Component</h3>
+    <p>First, create a custom input component that accepts the <code>InputProps</code> type:</p>
+    <pre v-highlightjs>
+<code class="vue">{{ `<template>
+  <div>
+    <label :for="field.name">\{\{ inputProps.label \}\}</label>
+    <input
+      :id="field.name"
+      :name="field.name"
+      :value="state.value"
+      @change="(e) => field.handleChange(e.target.value)"
+    >
+    <span v-if="inputProps.error">
+      \{\{ inputProps.errorMessages.join(", ") \}\}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts" generic="From extends Record<PropertyKey, any>, Name extends DeepKeys<From>">
+import type { DeepKeys } from "@tanstack/vue-form"
+import type { InputProps } from "@effect-app/vue-components"
+
+defineProps<InputProps<From, Name>>()
+
+defineEmits<{
+  (e: "focus", event: Event): void
+  (e: "blur", event: Event): void
+}>()
+
+defineOptions({
+  inheritAttrs: false
+})
+</script>` }}</code></pre>
+
+    <h3>Create Your Custom useForm Hook</h3>
+    <p>Then, use <code>createUseFormWithCustomInput</code> to create a custom hook:</p>
+    <pre v-highlightjs>
+<code class="typescript">{{ `import { createUseFormWithCustomInput } from "@effect-app/vue-components"
+import CustomInput from "./CustomInput.vue"
+
+export const useForm = createUseFormWithCustomInput(CustomInput)` }}</code></pre>
+
+    <h3>Use Your Custom Hook</h3>
+    <p>Now you can use your custom <code>useForm</code> hook throughout your application:</p>
+    <pre v-highlightjs>
+<code class="vue">{{ `<script setup lang="ts">
+import { S } from "effect-app"
+import { useForm } from "./composables/useForm"
+
+const schema = S.Struct({
+  name: S.String,
+  age: S.Number
+})
+
+const form = useForm(schema, {
+  onSubmit: async ({ value }) => {
+    console.log(value)
+  }
+})
+</script>
+
+<template>
+  <form.Form>
+    <form.Input label="Name" name="name" />
+    <form.Input label="Age" name="age" />
+    <button type="submit">Submit</button>
+  </form.Form>
+</template>` }}</code></pre>
+
+    <h3>Advanced: Custom Input Props</h3>
+    <p>
+      You can extend the input props to add custom properties like custom types or options:
+    </p>
+    <pre v-highlightjs>
+<code class="typescript">{{ `import type { InputProps as OmegaInputProps } from "@effect-app/vue-components"
+
+// Define custom type props
+export type TypeProps = {
+  type?: "text" | "email" | "color"
+  options?: undefined
+} | {
+  type?: "select" | "radio"
+  options?: {
+    title: string
+    value: string | number
+  }[]
+}
+
+// Extend the InputProps type
+export type InputProps<From extends Record<PropertyKey, any>, TName extends string> =
+  OmegaInputProps<From, TName> & { inputProps: TypeProps }
+
+// Create the custom hook with typed props
+export const useForm = createUseFormWithCustomInput<TypeProps>(CustomInput)` }}</code></pre>
+
+    <h2>Key Concepts</h2>
+    <ul>
+      <li>
+        <strong>Compound Component Pattern:</strong> The <code>useOmegaForm</code> hook returns a form instance with
+        nested components like <code>Form</code> and <code>Input</code>
+      </li>
+      <li><strong>Type Safety:</strong> The schema definition ensures type safety throughout the form</li>
+      <li><strong>Flexibility:</strong> You can use built-in Vuetify components or provide your own custom inputs</li>
+      <li><strong>Reactive Values:</strong> Subscribe to form state changes using the <code>subscribe</code> prop</li>
+      <li>
+        <strong>Custom Hooks:</strong> Use <code>createUseFormWithCustomInput</code> to create reusable form hooks with
+        custom input components
+      </li>
+    </ul>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { S } from "effect-app"
+import { useOmegaForm } from "../../src/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;
+}
+
+ul {
+  margin-bottom: 1rem;
+  padding-left: 1.5rem;
+}
+
+li {
+  margin-bottom: 0.5rem;
+}
+</style>