From ac099a2c92b87f51dfb5c75b6ccb46e469d47e77 Mon Sep 17 00:00:00 2001
From: tugcekucukoglu <tugcekucukoglu.860@gmail.com>
Date: Wed, 23 Oct 2024 10:27:06 +0300
Subject: [PATCH] Forms documentation updates

---
 apps/showcase/doc/common/apidoc/index.json    | 442 ++++++++++++++++++
 apps/showcase/doc/forms/pt/PTViewer.vue       |  46 +-
 apps/showcase/doc/forms/theming/StyledDoc.vue |   5 +
 .../doc/forms/theming/TailwindDoc.vue         |   8 -
 apps/showcase/doc/forms/theming/index.vue     |  26 +-
 apps/showcase/tsconfig.json                   |  10 +-
 6 files changed, 485 insertions(+), 52 deletions(-)
 create mode 100644 apps/showcase/doc/forms/theming/StyledDoc.vue
 delete mode 100644 apps/showcase/doc/forms/theming/TailwindDoc.vue

diff --git a/apps/showcase/doc/common/apidoc/index.json b/apps/showcase/doc/common/apidoc/index.json
index caf2c4216..c8ffda559 100644
--- a/apps/showcase/doc/common/apidoc/index.json
+++ b/apps/showcase/doc/common/apidoc/index.json
@@ -1,4 +1,446 @@
 {
+    "form": {
+        "description": "Form provides validation functionality and manages form state.\n\n[Live Demo](https://www.primevue.org/form/)",
+        "components": {
+            "default": {
+                "description": "Form provides validation functionality and manages form state.",
+                "methods": {
+                    "description": "Defines methods that can be accessed by the component's reference.",
+                    "values": []
+                }
+            }
+        },
+        "interfaces": {
+            "description": "Defines the custom interfaces used by the module.",
+            "eventDescription": "Defines the custom events used by the component's emit.",
+            "methodDescription": "Defines methods that can be accessed by the component's reference.",
+            "typeDescription": "Defines the custom types used by the module.",
+            "values": {
+                "PassThroughOptions": {
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "mergeSections",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean",
+                            "default": ""
+                        },
+                        {
+                            "name": "mergeProps",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "PassThroughMergePropsType",
+                            "default": ""
+                        }
+                    ],
+                    "methods": []
+                },
+                "FormPassThroughMethodOptions": {
+                    "description": "Custom passthrough(pt) option method.",
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "instance",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "any",
+                            "default": "",
+                            "description": "Defines instance."
+                        },
+                        {
+                            "name": "props",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "FormProps",
+                            "default": "",
+                            "description": "Defines valid properties."
+                        },
+                        {
+                            "name": "attrs",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "any",
+                            "default": "",
+                            "description": "Defines valid attributes."
+                        },
+                        {
+                            "name": "parent",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "any",
+                            "default": "",
+                            "description": "Defines parent options."
+                        },
+                        {
+                            "name": "global",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "undefined | object",
+                            "default": "",
+                            "description": "Defines passthrough(pt) options in global config."
+                        }
+                    ],
+                    "methods": []
+                },
+                "FormPassThroughOptions": {
+                    "description": "Custom passthrough(pt) options.",
+                    "relatedProp": "FormProps.pt",
+                    "props": [
+                        {
+                            "name": "root",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "FormPassThroughOptionType",
+                            "default": "",
+                            "description": "Used to pass attributes to the root's DOM element."
+                        },
+                        {
+                            "name": "hooks",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "any",
+                            "default": "",
+                            "description": "Used to manage all lifecycle hooks."
+                        }
+                    ],
+                    "methods": []
+                },
+                "FormPassThroughAttributes": {
+                    "description": "Custom passthrough attributes for each DOM elements",
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "[key: string]",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "any"
+                        }
+                    ],
+                    "methods": []
+                },
+                "FormProps": {
+                    "description": "Defines valid properties in Form component.",
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "resolver",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        },
+                        {
+                            "name": "initialValues",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "Record<string, any>",
+                            "default": "",
+                            "description": "The initial values for the form fields."
+                        },
+                        {
+                            "name": "validateOnValueUpdate",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": "true",
+                            "description": "Whether to validate the form fields when the values change."
+                        },
+                        {
+                            "name": "validateOnBlur",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": "false",
+                            "description": "Whether to validate the form fields when they lose focus (on blur)."
+                        },
+                        {
+                            "name": "validateOnMount",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": "false",
+                            "description": "Whether to validate the form fields immediately after the form is mounted."
+                        },
+                        {
+                            "name": "validateOnSubmit",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": "true",
+                            "description": "Whether to validate the form fields when the form is submitted."
+                        },
+                        {
+                            "name": "dt",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "any",
+                            "default": "",
+                            "description": "It generates scoped CSS variables using design tokens for the component."
+                        },
+                        {
+                            "name": "pt",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "PassThrough<FormPassThroughOptions>",
+                            "default": "",
+                            "description": "Used to pass attributes to DOM elements inside the component."
+                        },
+                        {
+                            "name": "ptOptions",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "PassThroughOptions",
+                            "default": "",
+                            "description": "Used to configure passthrough(pt) options of the component."
+                        },
+                        {
+                            "name": "unstyled",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean",
+                            "default": "false",
+                            "description": "When enabled, it removes component related styles in the core."
+                        }
+                    ],
+                    "methods": []
+                },
+                "FormSlots": {
+                    "description": "Defines valid slots in Form component.",
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "default",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        }
+                    ],
+                    "methods": []
+                },
+                "FormEmitsOptions": {
+                    "description": "Defines valid emits in Form component.",
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "submit",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        }
+                    ],
+                    "methods": []
+                }
+            }
+        },
+        "tokens": {
+            "description": "Define design tokens used by the component.",
+            "values": {
+                "PassThroughOptions": {
+                    "props": []
+                },
+                "FormPassThroughMethodOptions": {
+                    "description": "Custom passthrough(pt) option method.",
+                    "props": []
+                },
+                "FormPassThroughOptions": {
+                    "description": "Custom passthrough(pt) options.",
+                    "props": []
+                },
+                "FormPassThroughAttributes": {
+                    "description": "Custom passthrough attributes for each DOM elements",
+                    "props": []
+                },
+                "FormProps": {
+                    "description": "Defines valid properties in Form component.",
+                    "props": []
+                },
+                "FormSlots": {
+                    "description": "Defines valid slots in Form component.",
+                    "props": []
+                },
+                "FormEmitsOptions": {
+                    "description": "Defines valid emits in Form component.",
+                    "props": []
+                }
+            }
+        },
+        "types": {
+            "description": "Defines the custom types used by the module.",
+            "values": {
+                "PassThroughMergePropsType": {
+                    "values": "(args: any) => undefined | boolean | undefined",
+                    "description": "From primevue/passthrough/index.d.ts"
+                },
+                "FormPassThroughOptionType": {
+                    "values": "FormPassThroughAttributes | (options: FormPassThroughMethodOptions) => undefined | string | null | undefined"
+                },
+                "FormEmits": {
+                    "values": "EmitFn<FormEmitsOptions>"
+                }
+            }
+        }
+    },
+    "formstyle": {
+        "description": "[Live Demo](https://www.primevue.org/form/)",
+        "interfaces": {
+            "description": "Defines the custom interfaces used by the module.",
+            "eventDescription": "Defines the custom events used by the component's emit.",
+            "methodDescription": "Defines methods that can be accessed by the component's reference.",
+            "typeDescription": "Defines the custom types used by the module.",
+            "values": {
+                "FormStyle": {
+                    "relatedProp": "",
+                    "props": [],
+                    "methods": [],
+                    "extendedTypes": "default"
+                }
+            }
+        },
+        "tokens": {
+            "description": "Define design tokens used by the component.",
+            "values": {
+                "FormStyle": {
+                    "props": []
+                }
+            }
+        }
+    },
+    "form/src/resolvers": {},
+    "form/src/useform": {
+        "functions": {
+            "description": "Defines the custom functions used by the module.",
+            "values": {
+                "useForm": {
+                    "name": "useForm",
+                    "parameters": [
+                        {
+                            "name": "options",
+                            "type": "useFormOptions"
+                        }
+                    ],
+                    "returnType": "useFormReturn"
+                }
+            }
+        },
+        "interfaces": {
+            "description": "Defines the custom interfaces used by the module.",
+            "eventDescription": "Defines the custom events used by the component's emit.",
+            "methodDescription": "Defines methods that can be accessed by the component's reference.",
+            "typeDescription": "Defines the custom types used by the module.",
+            "values": {
+                "useFormReturn": {
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "defineField",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        },
+                        {
+                            "name": "handleSubmit",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        },
+                        {
+                            "name": "validate",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        },
+                        {
+                            "name": "reset",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        },
+                        {
+                            "name": "valid",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "boolean",
+                            "default": ""
+                        },
+                        {
+                            "name": "states",
+                            "optional": false,
+                            "readonly": false,
+                            "type": "any",
+                            "default": ""
+                        }
+                    ],
+                    "methods": []
+                },
+                "useFormOptions": {
+                    "relatedProp": "",
+                    "props": [
+                        {
+                            "name": "resolver",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "Function",
+                            "default": ""
+                        },
+                        {
+                            "name": "initialValues",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "Record<string, any>",
+                            "default": ""
+                        },
+                        {
+                            "name": "validateOnValueUpdate",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": ""
+                        },
+                        {
+                            "name": "validateOnBlur",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": ""
+                        },
+                        {
+                            "name": "validateOnMount",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": ""
+                        },
+                        {
+                            "name": "validateOnSubmit",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "boolean | string[]",
+                            "default": ""
+                        }
+                    ],
+                    "methods": []
+                }
+            }
+        },
+        "tokens": {
+            "description": "Define design tokens used by the component.",
+            "values": {
+                "useFormReturn": {
+                    "props": []
+                },
+                "useFormOptions": {
+                    "props": []
+                }
+            }
+        }
+    },
     "accordion": {
         "description": "Accordion groups a collection of contents in tabs.\n\n[Live Demo](https://www.primevue.org/accordion/)",
         "components": {
diff --git a/apps/showcase/doc/forms/pt/PTViewer.vue b/apps/showcase/doc/forms/pt/PTViewer.vue
index 0150b382d..213acc89e 100644
--- a/apps/showcase/doc/forms/pt/PTViewer.vue
+++ b/apps/showcase/doc/forms/pt/PTViewer.vue
@@ -1,37 +1,45 @@
 <template>
     <DocPTViewer :docs="docs">
-        <Card style="width: 25rem">
-            <template #title>Advanced Card</template>
-            <template #subtitle>Card subtitle</template>
-            <template #content>
-                <p class="m-0">
-                    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Inventore sed consequuntur error repudiandae numquam deserunt quisquam repellat libero asperiores earum nam nobis, culpa ratione quam perferendis esse, cupiditate neque
-                    quas!
-                </p>
-            </template>
-            <template #footer>
-                <div class="flex gap-4 mt-1">
-                    <Button label="Cancel" severity="secondary" outlined class="w-full" />
-                    <Button label="Save" class="w-full" />
-                </div>
-            </template>
-        </Card>
+        <Form v-slot="$form" :resolver="resolver" :initialValues="initialValues" @submit="onFormSubmit" class="flex flex-col gap-4 w-full sm:w-56">
+            <div class="flex flex-col gap-2">
+                <InputText name="username" type="text" placeholder="Username" fluid />
+                <Message v-if="$form.username?.invalid" severity="error">{{ $form.username.errors[0]?.message }}</Message>
+            </div>
+            <Button type="submit" severity="secondary" label="Submit" />
+        </Form>
     </DocPTViewer>
 </template>
 
 <script>
 import { getPTOptions } from '@/components/doc/helpers';
+import { zodResolver } from '@primevue/form/resolvers';
+import { z } from 'zod';
 
 export default {
     data() {
         return {
             docs: [
                 {
-                    data: getPTOptions('Card'),
-                    key: 'Card'
+                    data: getPTOptions('Form'),
+                    key: 'Form'
                 }
-            ]
+            ],
+            initialValues: {
+                username: ''
+            },
+            resolver: zodResolver(
+                z.object({
+                    username: z.string().min(1, { message: 'Username is required.' })
+                })
+            )
         };
+    },
+    methods: {
+        onFormSubmit({ valid }) {
+            if (valid) {
+                this.$toast.add({ severity: 'success', summary: 'Form is submitted.', life: 3000 });
+            }
+        }
     }
 };
 </script>
diff --git a/apps/showcase/doc/forms/theming/StyledDoc.vue b/apps/showcase/doc/forms/theming/StyledDoc.vue
new file mode 100644
index 000000000..e09e42c80
--- /dev/null
+++ b/apps/showcase/doc/forms/theming/StyledDoc.vue
@@ -0,0 +1,5 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>Component does not apply any styling.</p>
+    </DocSectionText>
+</template>
diff --git a/apps/showcase/doc/forms/theming/TailwindDoc.vue b/apps/showcase/doc/forms/theming/TailwindDoc.vue
deleted file mode 100644
index 4daa6c5f8..000000000
--- a/apps/showcase/doc/forms/theming/TailwindDoc.vue
+++ /dev/null
@@ -1,8 +0,0 @@
-<template>
-    <DocSectionText v-bind="$attrs">
-        <p>
-            Visit <a href="https://github.com/primefaces/primevue-tailwind" target="_blank" rel="noopener noreferrer" class="doc-link">Tailwind Presets</a> project for detailed documentation, examples and ready-to-use presets about how to style
-            PrimeVue components with Tailwind CSS.
-        </p>
-    </DocSectionText>
-</template>
diff --git a/apps/showcase/doc/forms/theming/index.vue b/apps/showcase/doc/forms/theming/index.vue
index 63c317d8a..6ced07c42 100644
--- a/apps/showcase/doc/forms/theming/index.vue
+++ b/apps/showcase/doc/forms/theming/index.vue
@@ -9,9 +9,7 @@
 </template>
 
 <script>
-import DocApiTable from '@/components/doc/DocApiTable.vue';
-import { getStyleOptions } from '@/components/doc/helpers';
-import TailwindDoc from './TailwindDoc.vue';
+import StyledDoc from './StyledDoc.vue';
 
 export default {
     data() {
@@ -20,27 +18,7 @@ export default {
                 {
                     id: 'theming.styled',
                     label: 'Styled',
-                    children: [
-                        {
-                            id: 'theming.classes',
-                            label: 'CSS Classes',
-                            description: 'List of class names used in the styled mode.',
-                            component: DocApiTable,
-                            data: getStyleOptions('Form')
-                        }
-                    ]
-                },
-                {
-                    id: 'theming.unstyled',
-                    label: 'Unstyled',
-                    description: 'Theming is implemented with the pass through properties in unstyled mode.',
-                    children: [
-                        {
-                            id: 'theming.tailwind',
-                            label: 'Tailwind',
-                            component: TailwindDoc
-                        }
-                    ]
+                    component: StyledDoc
                 }
             ]
         };
diff --git a/apps/showcase/tsconfig.json b/apps/showcase/tsconfig.json
index 65b46adf0..fc9083beb 100644
--- a/apps/showcase/tsconfig.json
+++ b/apps/showcase/tsconfig.json
@@ -15,6 +15,14 @@
         "jsx": "preserve",
         "incremental": true
     },
-    "include": ["../../packages/primevue/src/**/*.d.ts", "../../packages/primevue/src/**/style/*.d.ts", "../../packages/themes/types", "../packages/themes/src/**/**/index.js", "../packages/form/src/**/*.d.ts"],
+    "include": [
+        "../../packages/primevue/src/**/*.d.ts",
+        "../../packages/primevue/src/**/style/*.d.ts",
+        "../../packages/themes/types",
+        "../packages/themes/src/**/**/index.js",
+        "../packages/form/src/**/*.d.ts",
+        "../../packages/form/src/**/*.d.ts",
+        "../../packages/form/src/**/style/*.d.ts"
+    ],
     "exclude": ["node_modules", "**/node_modules", "**/dist"]
 }