docs: setting up submit control (#177)

* docs: setting up submit control

* refactor: remove new line

apps/demo/src/pages/examples/form-component.astro

@@ -1,4 +1,5 @@
 ---
+import type { Submit } from "@astro-reactive/common";
 import Form, { FormGroup } from "@astro-reactive/form";
 
 const simpleForm = new FormGroup([
@@ -21,6 +22,61 @@ const simpleForm = new FormGroup([
     placeholder: "-- Please choose an option --",
   },
 ]);
+
+const nameForm = new FormGroup(
+  [
+    {
+      name: "firstName",
+      label: "First Name",
+      value: "John",
+    },
+    {
+      name: "lastName",
+      label: "Last Name",
+      value: "Doe",
+    },
+  ],
+  "Name"
+);
+
+const skills = new FormGroup(
+  [
+    {
+      name: "JavaScript",
+      type: "checkbox",
+      label: "JavaScript",
+    },
+    {
+      name: "TypeScript",
+      type: "checkbox",
+      label: "TypeScript",
+    },
+    {
+      name: "React",
+      type: "checkbox",
+      label: "React",
+    },
+    {
+      name: "Vue",
+      type: "checkbox",
+      label: "Vue",
+    },
+  ],
+  "Skills"
+);
+
+/**
+ * comment
+ */
+
+const submitControl: Submit = {
+  name: "submit",
+  type: "submit",
+};
 ---
 
-<Form formGroups={simpleForm} />
+<h2>Simple Form</h2>
+<Form formGroups={simpleForm} submitControl={submitControl} />
+
+<h2>Form with nested form groups</h2>
+<Form formGroups={[nameForm, skills]} />

apps/docs/src/config.ts

@@ -1,6 +1,7 @@
 export const SITE = {
   title: "Astro Reactive",
-  description: "Documentation for the Astro Reactive Library",
+  description:
+    "Let your data build your UI with native Astro components and architecture.",
   defaultLanguage: "en_US",
 };
 
@@ -30,7 +31,7 @@ export const KNOWN_LANGUAGES = {
 } as const;
 export const KNOWN_LANGUAGE_CODES = Object.values(KNOWN_LANGUAGES);
 
-export const GITHUB_EDIT_URL = `https://github.com/ayoayco/astro-reactive-library/tree/main/docs`;
+export const GITHUB_EDIT_URL = `https://github.com/ayoayco/astro-reactive-library/tree/main/apps/docs`;
 
 export const COMMUNITY_INVITE_URL = `https://astro.build/chat`;
 

apps/docs/src/layouts/MainLayout.astro

@@ -32,7 +32,7 @@ const githubEditUrl = `${CONFIG.GITHUB_EDIT_URL}/${currentFile}`;
     <title>
       {
         frontmatter.title
-          ? `${frontmatter.title} 🚀 ${CONFIG.SITE.title}`
+          ? `${frontmatter.title} | ${CONFIG.SITE.title}`
           : CONFIG.SITE.title
       }
     </title>
@@ -144,7 +144,7 @@ const githubEditUrl = `${CONFIG.GITHUB_EDIT_URL}/${currentFile}`;
       <div id="grid-main">
         <div class="warning">
           <strong>🛠 Under Construction:</strong> This library and the documentation
-          for it are undergoing rigorous development. Read and join our <a
+          are undergoing rigorous development. Read and join our <a
             href="https://github.com/ayoayco/astro-reactive-library/discussions"
             >Discussions</a
           > for questions, suggestions, or feedback.

apps/docs/src/pages/en/api/form/form-component.md

@@ -18,6 +18,8 @@ const form = new FormGroup(
 <Form formGroups={form} />
 ```
 
+-----
+
 ## Usage
 
 Setting up the `Form` component is mainly done by providing it your configuration via the `formGroups` property which takes either a `FormGroup` or an array `FormGroup[]`.
@@ -26,7 +28,7 @@ Setting up the `Form` component is mainly done by providing it your configuratio
 
 ### Setting up a form
 
-Giving the component a `FormGroup` object will set up a form. 
+Assigning a `FormGroup` object to the `formGroup` property will set up a form.
 
 ```astro
 ---
@@ -53,21 +55,100 @@ const form = new FormGroup([
   },
 ]);
 ---
-
 <Form formGroups={form} />
 ```
 
-The `FormGroup` constructor takes an array `ControlConfig[]`.
-
-*See the `ControlConfig` type in the [FormControl](/en/api/form/form-group) class documentation.*
-
 The example above will result in a form containing three controls: a text field `username`, a textarea `comment`, and a `size` dropdown.
 
 ![single-form](https://user-images.githubusercontent.com/4262489/200187918-95052561-e02c-453d-9a9b-940303a80046.png)
 
+The `FormGroup` constructor takes an array `ControlConfig[]`.
+
+> **❗️ Note:** The `ControlConfig` type will be defined in the [FormControl](/en/api/form/form-control) class documentation.
+
+
 ### Setting up multiple field sets
 
-To render a form with multiple field sets, give the component an array `FormGroup[]`
+To render a form with multiple field sets, assign an array `FormGroup[]` to the `formGroups` property.
+
+```astro
+---
+import Form, { FormGroup } from "@astro-reactive/form";
+
+const nameForm = new FormGroup(
+  [
+    {
+      name: "firstName",
+      label: "First Name",
+      value: "John",
+    },
+    {
+      name: "lastName",
+      label: "Last Name",
+      value: "Doe",
+    },
+  ],
+  "Name"
+);
+
+const skills = new FormGroup(
+  [
+    {
+      name: "JavaScript",
+      type: "checkbox",
+      label: "JavaScript",
+    },
+    {
+      name: "TypeScript",
+      type: "checkbox",
+      label: "TypeScript",
+    },
+    {
+      name: "React",
+      type: "checkbox",
+      label: "React",
+    },
+    {
+      name: "Vue",
+      type: "checkbox",
+      label: "Vue",
+    },
+  ],
+  "Skills"
+);
+---
+<Form formGroups={[nameForm, skills]} />
+```
+
+The example above renders a form with two field sets with legend `Name` and `Skills`.
+
+![multiple form groups](https://user-images.githubusercontent.com/4262489/200191529-ff5fed93-2cd4-4337-9eb2-f47e64259206.png)
+
+The `FormGroup` constructor optionally takes a name property to set the legend for the field set.
+
+### Setting up the Submit button
+
+The `Form` component takes an optional `submitControl` property. This property is of type `Submit` which is a especial type for the submit button.
+
+This implementation is to distinguish the submit button from other buttons and limit the form to only have one of it.
+
+```astro
+---
+import Form, { FormGroup } from "@astro-reactive/form";
+
+const form = new FormGroup([]);
+
+const submitControl: Submit = {
+  name: "submit",
+  type: "submit",
+};
+---
+<Form formGroups={form} submitControl={submitControl} />
+```
+
+This is a very crude solution to prevent having multiple submit buttons. For suggestions to improve this, join our [discussions](https://github.com/ayoayco/astro-reactive-library/discussions).
+
+-----
 
 ## Properties
 
@@ -88,17 +169,19 @@ Determines how the form is are rendered
 
 
 ### `readOnly`
-
+Type: `boolean`
-#### `boolean`
 
 Sets the whole form as read-only.
 
 ### `showValidationHints`
+Type: `boolean`
 
 When used with our `validator` package, the `Form` component is able to render validation hints when `showValidationHints` is set to true:
-1. asterisks on required controls' labels
+- asterisks on required controls' labels
-2. controls with validation errors are colored red
+- controls with validation errors are colored red
 
 ### `submitControl`
+Type: `Submit`
 
 ### `theme`
+Type: `'light' | 'dark'`

apps/docs/src/pages/en/api/form/form-control.md

@@ -2,6 +2,8 @@
 title: FormControl
 type: class
 package: "@astro-reactive/form"
-description: The Reactive Form component for Astro
+description: FormControl class
 layout: ../../../../layouts/MainLayout.astro
 ---
+
+> **❗ Note:** This documentation is incomplete.

apps/docs/src/pages/en/api/form/form-group.md

@@ -2,10 +2,12 @@
 title: FormGroup
 type: class
 package: "@astro-reactive/form"
-description: The Reactive Form component for Astro
+description: The FormGroup class represents a group of controls that will be rendered as a fieldset element in a form.
 layout: ../../../../layouts/MainLayout.astro
 ---
 
+> **❗ Note:** This documentation is incomplete.
+
 The `FormGroup` class represents a group of controls that will be rendered as a fieldset element in a form.
 
 ## Properties

apps/docs/src/pages/en/introduction.md

@@ -1,6 +1,6 @@
 ---
 title: Hi, explorer! 🚀
-description: Library homepage
+description: Astro Reactive Library Docs
 layout: ../../layouts/MainLayout.astro
 ---
 
@@ -10,7 +10,7 @@ Thanks for checking out the Astro Reactive Library! Welcome to a new adventure.
 
 This project aims to be a new library of components and utilities for building reactive user interfaces with [Astro](https://astro.build).
 
-There's a lot of opportunity to contribute. A good start will be to understand what Astro is, and how to set up a basic Astro project. For this, the [Astro website](https://astro.build) and [documentation](https://docs.astro.build/en/getting-started/) are good places to start.
+We are working on a fun and easy tutorial so you can learn how to build reactive UIs with Astro from scratch using our packages. For now, see our [API Docs](/en/api) for example usage.
 
 ## Packages
 
@@ -26,6 +26,8 @@ There's a lot of opportunity to contribute. A good start will be to understand w
 
 Any contribution is welcome. Feel free to look around our [repository](https://github.com/ayoayco/astro-reactive-library) to find something that interests you. :)
 
+There's a lot of opportunity to contribute. A good start will be to understand what Astro is, and how to set up a basic Astro project. For this, the [Astro website](https://astro.build) and [documentation](https://docs.astro.build/en/getting-started/) are good places to start.
+
 The [issues page](https://github.com/ayoayco/astro-reactive-library/issues?q=is%3Aopen+is%3Aissue+label%3A%22accepting+PRs%22) contains some ideas, but they should not limit your contribution.
 
 If you don't find anything there, I'm happy to help you get your contribution in.