From 986151fe3e09cbb6210f2060515ead4c8bcaca3a Mon Sep 17 00:00:00 2001 From: Ayo Ayco Date: Wed, 4 Jan 2023 13:43:50 +0100 Subject: [PATCH] docs(form): update Form properties and respective documentation (#248) * chore: project clean up * feat(form): update Form properties * docs: update documentation for the Form properties * fix(demo): update form method demo --- README.md | 6 +- apps/demo/src/pages/index.astro | 2 +- .../src/components/Footer/AvatarList.astro | 3 +- .../src/pages/en/api/form/form-component.md | 62 +++++++++++++----- packages/common/types/control.types.ts | 13 +--- packages/form/README.md | 2 +- packages/form/components/Form.astro | 65 ++++++++++++++----- packages/validator/README.md | 2 +- 8 files changed, 103 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index b8f5c8d..01e3dad 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- Astro Reactive Library Logo + Astro Reactive Library Logo
Astro Reactive Library
@@ -10,7 +10,7 @@ Build & Test Result - Last Commit + Last Commit - + 👉 _[Join our contributors!](https://github.com/astro-reactive/astro-reactive/blob/main/CONTRIBUTING.md)_ diff --git a/apps/demo/src/pages/index.astro b/apps/demo/src/pages/index.astro index 2a645c4..999bab5 100644 --- a/apps/demo/src/pages/index.astro +++ b/apps/demo/src/pages/index.astro @@ -110,6 +110,6 @@ const submit: Submit = { theme={theme} submitControl={submit} action="https://localhost" - method="POST" + method="post" /> diff --git a/apps/docs/src/components/Footer/AvatarList.astro b/apps/docs/src/components/Footer/AvatarList.astro index f6b0d87..c6334ed 100644 --- a/apps/docs/src/components/Footer/AvatarList.astro +++ b/apps/docs/src/components/Footer/AvatarList.astro @@ -5,7 +5,7 @@ type Props = { }; const { path } = Astro.props as Props; const resolvedPath = `apps/docs/${path}`; -const url = `https://api.github.com/repos/ayoayco/astro-reactive-library/commits?path=${resolvedPath}`; +const url = `https://api.github.com/repos/astro-reactive/astro-reactive/commits?path=${resolvedPath}`; const commitsURL = `https://github.com/astro-reactive/astro-reactive/commits/main/${resolvedPath}`; type Commit = { @@ -180,4 +180,3 @@ const additionalContributors = unique.length - recentContributors.length; // lis margin-left: 0.75rem; } - 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 607d019..4d864ed 100644 --- a/apps/docs/src/pages/en/api/form/form-component.md +++ b/apps/docs/src/pages/en/api/form/form-component.md @@ -158,22 +158,41 @@ This is a very crude solution to prevent having multiple submit buttons. For sug ## Properties -The following are input properties a `Form` component can take. +The following are input properties a `Form` component can take. Only the `formGroups` property is required. -| Property | Type | | -| ------------------------------------------- | -------------------------- | -------- | -| [formGroups](#formgroups) | `FormGroup \| FormGroup[]` | required | -| [readOnly](#readonly) | `boolean` | optional | -| [showValidationHints](#showvalidationhints) | `boolean` | optional | -| [validateOnLoad](#validateOnLoad) | `boolean` | optional | -| [submitControl](#submitcontrol) | `Submit` | optional | -| [theme](#theme) | `'light' \| 'dark'` | optional | +| Property | Type | | +| ------------------------------------------- | -------------------------- | ----------------------------------- | +| [formGroups](#formgroups) | `FormGroup \| FormGroup[]` | required | +| [action](#action) | `string` | optional | +| [method](#method) | `'get' \| 'post' \| 'dialog'` | optional | +| [readOnly](#readonly) | `boolean` | optional | +| [showValidationHints](#showvalidationhints) | `boolean` | optional | +| [submitControl](#submitcontrol) | `Submit` | optional | +| [theme](#theme) | `'light' \| 'dark'` | optional | +| [validateOnLoad](#validateOnLoad) | `boolean` | optional | ### `formGroups` Type: `FormGroup | FormGroup[]` -Determines how the form is are rendered +Determines how the form is rendered + +### action + +Type: `string` + +Sets the `action` [attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-action) for the form. Set this to the URL that processes the form submission. + +### method + +Type: HTTPSubmitMethod + +Sets the `method` [attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-method) for the form. Set this to the HTTP method to submit the form: 'post', 'get', or 'dialog'. + +From [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-method): +- `post` - The POST method; form data sent as the request body. +- `get (default)` - The GET method; form data appended to the action URL with a ? separator. Use this method when the form has no side effects. +- `dialog` - When the form is inside a

, closes the dialog and throws a submit event on submission without submitting data or clearing the form. ### `readOnly` @@ -190,17 +209,28 @@ When used with our `validator` package, the `Form` component is able to render v - asterisks on required controls' labels - controls with validation errors are colored red -### `validateOnLoad` - -Type: `boolean` - -When used with our `validator` package, the `Form` component is able to render validation errors on server-side rendering when `validateOnLoad` is set to true otherwise, the validation errors will only be rendered on the client-side. - ### `submitControl` Type: `Submit` +A special button that triggers the submit event for a form. + +```ts +const submit: Submit = { + type: 'submit', + value: 'Let\'s go!' +} +``` + ### `theme` Type: `'light' | 'dark'` +Sets the form to use light or dark mode. + +### `validateOnLoad` + +Type: `boolean` + +When used with our `validator` package, the `Form` component is able to render validation errors on server-side rendering when `validateOnLoad` is set to true. Otherwise, the validation errors will only be rendered on the client-side upon user interaction. + diff --git a/packages/common/types/control.types.ts b/packages/common/types/control.types.ts index ec9720d..277e9c6 100644 --- a/packages/common/types/control.types.ts +++ b/packages/common/types/control.types.ts @@ -27,16 +27,7 @@ export type InputType = | "url" | "week"; -export type HTTPRequestMethodType = - | "GET" - | "POST" - | "PUT" - | "PATCH" - | "DELETE" - | "TRACE" - | "OPTIONS" - | "CONNECT" - | "HEAD"; +export type HTTPSubmitMethod = "get" | "post" | "dialog"; export type ControlType = InputType | "dropdown" | "textarea"; @@ -48,7 +39,7 @@ export interface ControlBase { label?: string; placeholder?: string; validators?: ValidatorRules; - triggerValidationOn?: ValidationHooks; + triggerValidationOn?: ValidationHooks; } export interface Checkbox extends ControlBase { diff --git a/packages/form/README.md b/packages/form/README.md index f3ab34d..ba29286 100644 --- a/packages/form/README.md +++ b/packages/form/README.md @@ -1,5 +1,5 @@

- Astro Reactive Library Logo + Astro Reactive Library Logo
Astro Reactive Form
diff --git a/packages/form/components/Form.astro b/packages/form/components/Form.astro index bcc8a41..0403ded 100644 --- a/packages/form/components/Form.astro +++ b/packages/form/components/Form.astro @@ -1,19 +1,54 @@ --- -import type { HTTPRequestMethodType, Submit } from '@astro-reactive/common'; +import type { HTTPSubmitMethod, Submit } from '@astro-reactive/common'; import { FormGroup, FormControl } from '../core'; import FieldSet from './FieldSet.astro'; import Field from './Field.astro'; import ShortUniqueId from 'short-unique-id'; export interface Props { + /** + * Determines how the form is rendered + */ formGroups: FormGroup | FormGroup[]; - readOnly?: boolean; - showValidationHints?: boolean; - validateOnLoad?: boolean; - submitControl?: Submit; - theme?: 'light' | 'dark'; + + /** + * Sets the `action` attribute for the form. Set this to the URL that processes the form submission. + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-method + */ action?: string; - method?: HTTPRequestMethodType; + + /** + * Sets the `method` attribute for the form. Set this to the HTTP method to submit the form: 'post', 'get', or 'dialog'. + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-method + */ + method?: HTTPSubmitMethod; + + /** + * Sets the whole form as read-only. + */ + readOnly?: boolean; + + /** + * When used with our `validator` package, the `Form` component is able to render validation hints when `showValidationHints` is set to true: + * - asterisks on required controls' labels + * - controls with validation errors are colored red + */ + showValidationHints?: boolean; + + /** + * A special button that triggers the submit event for a form. + */ + submitControl?: Submit; + + /** + * Sets the form to use light or dark mode. + */ + theme?: 'light' | 'dark'; + + /** + * When used with our `validator` package, the `Form` component is able to render validation errors on server-side rendering when `validateOnLoad` is set to true. Otherwise, the validation errors will only be rendered on the client-side upon user interaction. + */ + validateOnLoad?: boolean; } const { @@ -23,8 +58,8 @@ const { showValidationHints = false, validateOnLoad = false, readOnly = false, - action = "", - method = "GET" + action = '', + method = 'get', } = Astro.props; const uid = new ShortUniqueId({ length: 9 }); @@ -32,19 +67,15 @@ const formTheme = theme ?? 'light'; const formName = Array.isArray(formGroups) ? null : formGroups?.name || null; const formId = Array.isArray(formGroups) ? uid() : formGroups?.id || null; -// if `validateOnLoad` prop is true, +// if `validateOnLoad` prop is true, // it should forced all FormControl to validate on load if (validateOnLoad) { if (Array.isArray(formGroups)) { - formGroups.forEach(group => - group.controls.forEach(control => - control.setValidateOnLoad(validateOnLoad) - ) + formGroups.forEach((group) => + group.controls.forEach((control) => control.setValidateOnLoad(validateOnLoad)) ); } else { - formGroups.controls.forEach(control => - control.setValidateOnLoad(validateOnLoad) - ) + formGroups.controls.forEach((control) => control.setValidateOnLoad(validateOnLoad)); } } --- diff --git a/packages/validator/README.md b/packages/validator/README.md index 3f01240..49353c5 100644 --- a/packages/validator/README.md +++ b/packages/validator/README.md @@ -1,5 +1,5 @@

- Astro Reactive Library Logo + Astro Reactive Library Logo
Astro Reactive Validator