From 31b95cbe2b2c797f73970923c4a436b0de73c4aa Mon Sep 17 00:00:00 2001 From: Ayo Ayco Date: Sun, 6 Nov 2022 21:23:55 +0100 Subject: [PATCH] docs: setting up submit control (#177) * docs: setting up submit control * refactor: remove new line --- .../src/pages/examples/form-component.astro | 58 +++++++++- apps/docs/src/config.ts | 5 +- apps/docs/src/layouts/MainLayout.astro | 4 +- .../src/pages/en/api/form/form-component.md | 107 ++++++++++++++++-- .../src/pages/en/api/form/form-control.md | 4 +- apps/docs/src/pages/en/api/form/form-group.md | 4 +- apps/docs/src/pages/en/introduction.md | 6 +- 7 files changed, 167 insertions(+), 21 deletions(-) diff --git a/apps/demo/src/pages/examples/form-component.astro b/apps/demo/src/pages/examples/form-component.astro index c5a0e35..69c1a9b 100644 --- a/apps/demo/src/pages/examples/form-component.astro +++ b/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", +}; --- -
+

Simple Form

+ + +

Form with nested form groups

+ diff --git a/apps/docs/src/config.ts b/apps/docs/src/config.ts index 8cb6699..94f29c7 100644 --- a/apps/docs/src/config.ts +++ b/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`; diff --git a/apps/docs/src/layouts/MainLayout.astro b/apps/docs/src/layouts/MainLayout.astro index b0e2d14..6ab53b5 100644 --- a/apps/docs/src/layouts/MainLayout.astro +++ b/apps/docs/src/layouts/MainLayout.astro @@ -32,7 +32,7 @@ const githubEditUrl = `${CONFIG.GITHUB_EDIT_URL}/${currentFile}`; { frontmatter.title - ? `${frontmatter.title} 🚀 ${CONFIG.SITE.title}` + ? `${frontmatter.title} | ${CONFIG.SITE.title}` : CONFIG.SITE.title } @@ -144,7 +144,7 @@ const githubEditUrl = `${CONFIG.GITHUB_EDIT_URL}/${currentFile}`;
🛠 Under Construction: This library and the documentation - for it are undergoing rigorous development. Read and join our Discussions for questions, suggestions, or feedback. diff --git a/apps/docs/src/pages/en/api/form/form-component.md b/apps/docs/src/pages/en/api/form/form-component.md index b80cb21..1d9dccc 100644 --- a/apps/docs/src/pages/en/api/form/form-component.md +++ b/apps/docs/src/pages/en/api/form/form-component.md @@ -18,6 +18,8 @@ const form = new FormGroup( ``` +----- + ## 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([ }, ]); --- - ``` -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" +); +--- + +``` + +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", +}; +--- + +``` + +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` - -#### `boolean` +Type: `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 -2. controls with validation errors are colored red +- asterisks on required controls' labels +- controls with validation errors are colored red ### `submitControl` +Type: `Submit` -### `theme` \ No newline at end of file +### `theme` +Type: `'light' | 'dark'` diff --git a/apps/docs/src/pages/en/api/form/form-control.md b/apps/docs/src/pages/en/api/form/form-control.md index 138a667..11b5771 100644 --- a/apps/docs/src/pages/en/api/form/form-control.md +++ b/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. \ No newline at end of file diff --git a/apps/docs/src/pages/en/api/form/form-group.md b/apps/docs/src/pages/en/api/form/form-group.md index c37687b..a31a2dd 100644 --- a/apps/docs/src/pages/en/api/form/form-group.md +++ b/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 diff --git a/apps/docs/src/pages/en/introduction.md b/apps/docs/src/pages/en/introduction.md index 600e23c..af1841c 100644 --- a/apps/docs/src/pages/en/introduction.md +++ b/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.