From 3ebe7ab0b81a35f2b4add377cc718aa045ca9d86 Mon Sep 17 00:00:00 2001 From: clintcs <114178960+clintcs@users.noreply.github.com> Date: Mon, 31 Jul 2023 10:58:19 -0500 Subject: [PATCH] chore: improve documentation consistency --- .changeset/thick-eggs-argue.md | 6 +++ docs/components/autocomplete-field/index.md | 2 + docs/components/autocomplete/index.md | 4 +- docs/components/button/index.md | 17 +++++++-- docs/components/checkbox-field/index.md | 20 ++++++++-- docs/components/checkbox-group-field/index.md | 24 +++++++++--- docs/components/checkbox/index.md | 17 ++++++++- docs/components/field/index.md | 12 ++++-- docs/components/file-input-field/index.md | 37 +++++++++++++------ docs/components/input-field/index.md | 22 +++++++++-- docs/components/input/index.md | 13 ++++++- docs/components/multiselect-field/index.md | 11 +++++- docs/components/multiselect/index.md | 7 +++- docs/components/radio-field/index.md | 17 +++++++-- docs/components/radio-group-field/index.md | 20 ++++++++-- docs/components/radio/index.md | 13 ++++++- docs/components/textarea-field/index.md | 2 + docs/components/textarea/index.md | 16 +++++++- docs/installation.md | 4 +- .../toucan-form/changeset-validation/index.md | 7 +++- docs/toucan-form/index.md | 3 +- 21 files changed, 222 insertions(+), 52 deletions(-) create mode 100644 .changeset/thick-eggs-argue.md diff --git a/.changeset/thick-eggs-argue.md b/.changeset/thick-eggs-argue.md new file mode 100644 index 000000000..f977dca4f --- /dev/null +++ b/.changeset/thick-eggs-argue.md @@ -0,0 +1,6 @@ +--- +'@crowdstrike/ember-toucan-core': patch +'@crowdstrike/ember-toucan-form': patch +--- + +Improve documentation consistency. diff --git a/docs/components/autocomplete-field/index.md b/docs/components/autocomplete-field/index.md index 7d97353f9..39497a3a9 100644 --- a/docs/components/autocomplete-field/index.md +++ b/docs/components/autocomplete-field/index.md @@ -176,6 +176,8 @@ Set the `@isReadOnly` argument to put the input in the read only state. ## Attributes and Modifiers +Optional. + Consumers have direct access to the underlying [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input), so all attributes are supported. Modifiers can also be added directly to the input as shown in the demo. diff --git a/docs/components/autocomplete/index.md b/docs/components/autocomplete/index.md index a48cb89e5..571454e0f 100644 --- a/docs/components/autocomplete/index.md +++ b/docs/components/autocomplete/index.md @@ -86,7 +86,9 @@ export default class extends Component { Optional. -Called when the user makes a selection. It is called with the selected option (derived from `@options`) as its only argument. You'll want to update `@selected` with the new value in your on change handler. +Called when the user makes a selection. +It is called with the selected option (derived from `@options`) as its only argument. +You'll want to update `@selected` with the new value in your on change handler. ```hbs @@ -17,6 +20,8 @@ You can customize the appearance of the button with the `@variant` component arg ## Handling Clicks +Optional. + To handle click events use the `@onClick` component argument. ```hbs @@ -25,7 +30,10 @@ To handle click events use the `@onClick` component argument. ## Disabled State -`aria-disabled` is used over the `disabled` attribute so that screenreaders can still focus the element. To set the button as disabled, use `@isDisabled`. +Optional. + +`aria-disabled` is used over the `disabled` attribute so that screenreaders can still focus the element. +To set the button as disabled, use `@isDisabled`. ```hbs @@ -89,7 +97,10 @@ A disabled named block is provided so that users can optionally render additiona ## Loading State -Button exposes an `@isLoading` component argument. The button content will be only visible to screenreaders. +Optional. + +Button exposes an `@isLoading` component argument. +The button content will be only visible to screenreaders. ```hbs diff --git a/docs/components/checkbox-field/index.md b/docs/components/checkbox-field/index.md index e0e6cb385..4f98f87eb 100644 --- a/docs/components/checkbox-field/index.md +++ b/docs/components/checkbox-field/index.md @@ -83,6 +83,8 @@ Provide a string or array of strings to `@error` to render the text into the Err ## Value and onChange +Optional. + To tie into the input event, provide `@onChange`. `@onChange` will return two arguments: 1. the checked attribute from the target @@ -118,25 +120,37 @@ export default class extends Component { ## Disabled State +Optional. + Set the `@isDisabled` argument to disable the checkbox. ## Read Only State +Optional. + Set the `@isReadOnly` argument to put the checkbox in the read only state. ## Indeterminate State -Set the `@isIndeterminate` argument. To learn more, view the [Checkbox documentation](./checkbox). +Optional. + +Set the `@isIndeterminate` argument. +To learn more, view the [Checkbox documentation](./checkbox). ## Attributes and Modifiers -Consumers have direct access to the underlying [checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox), so all attributes are supported. Modifiers can also be added directly to the Checkbox as shown in the demo. +Optional. + +Consumers have direct access to the underlying [checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox), so all attributes are supported. +Modifiers can also be added directly to the Checkbox as shown in the demo. ## Test Selectors ### Root Element -Provide a custom selector via `@rootTestSelector`. This test selector will be used as the value for the `data-root-field` attribute. The Field can be targeted via: +Provide a custom selector via `@rootTestSelector`. +This test selector will be used as the value for the `data-root-field` attribute. +The Field can be targeted via: ```hbs diff --git a/docs/components/checkbox-group-field/index.md b/docs/components/checkbox-group-field/index.md index 02c24487b..a59981ce0 100644 --- a/docs/components/checkbox-group-field/index.md +++ b/docs/components/checkbox-group-field/index.md @@ -1,10 +1,13 @@ # Checkbox Group Field -Provides a checkbox group to be used within forms. It yields [CheckboxFields](./checkbox-field) back to the consumer so they can render as many checkboxes as needed with built-in state tracking for the selected values. +Provides a checkbox group to be used within forms. +It yields [CheckboxFields](./checkbox-field) back to the consumer so they can render as many checkboxes as needed with built-in state tracking for the selected values. ## Yielded Items -- `CheckboxField`: An underlying [CheckboxField](./checkbox-field) component. All arguments and attributes of CheckboxField can be supplied (e.g., `@isDisabled`, `@hint`, etc.). To give each option a unique value, use the `@value` argument. +- `CheckboxField`: An underlying [CheckboxField](./checkbox-field) component. +All arguments and attributes of CheckboxField can be supplied (e.g., `@isDisabled`, `@hint`, etc.). +To give each option a unique value, use the `@value` argument. ## Label @@ -78,7 +81,9 @@ Provide a string to the `@hint` component argument or content to `:hint` named b ## Error -Optional. Provide a string to `@error` to render the text into the Error section of the fieldset. +Optional. + +Provide a string to `@error` to render the text into the Error section of the fieldset. ## Value and onChange @@ -87,7 +92,9 @@ To tie into the input event when a checkbox is clicked, provide `@onChange`. `@o 1. an array containing the selected values 2. the raw event object -A `@value` argument to the CheckboxGroupField is used to determine which of the checkboxes is currently selected. It does so by comparing `@value` provided to the CheckboxGroupField to each `@value` of the checkbox. When an `@onChange` event occurs, it's most common to update the `@value` argument to the newly selected values as shown in the example below. +A `@value` argument to the CheckboxGroupField is used to determine which of the checkboxes is currently selected. +It does so by comparing `@value` provided to the CheckboxGroupField to each `@value` of the checkbox. +When an `@onChange` event occurs, it's most common to update the `@value` argument to the newly selected values as shown in the example below. ```hbs @@ -34,6 +41,8 @@ assert.dom('[data-checkbox]').hasProperty('indeterminate', true); ## Disabled State +Optional. + Set the `@isDisabled` argument to disable the checkbox. ```hbs @@ -42,6 +51,8 @@ Set the `@isDisabled` argument to disable the checkbox. ## Read Only State +Optional. + Set the `@isReadOnly` argument to put the checkbox in the read only state. ```hbs @@ -50,6 +61,8 @@ Set the `@isReadOnly` argument to put the checkbox in the read only state. ## onChange +Optional. + To tie into the input event, provide `@onChange`. `@onChange` will return two arguments: 1. the checked attribute from the target (e.target.checked) diff --git a/docs/components/field/index.md b/docs/components/field/index.md index a28cbf644..e9060e3bf 100644 --- a/docs/components/field/index.md +++ b/docs/components/field/index.md @@ -1,6 +1,8 @@ # Field -Field is a component to aid in creating form components. It provides a label, hint sections for things like help text, a control block, and an error section for rendering errors. It allows users to provide custom controls with a consistent form-element shell and is not opinionated on what underlying control element is used. +Field is a component to aid in creating form components. +It provides a label, hint sections for things like help text, a control block, and an error section for rendering errors. +It allows users to provide custom controls with a consistent form-element shell and is not opinionated on what underlying control element is used. ## Yielded Items @@ -34,7 +36,8 @@ The Field component does not handle accessibility automatically for the label, h ## Optionally Rendering Components -The yielded components from Field can be optionally rendered by using the `{{#if}}` helper. The below example optionally renders the Hint and Error based on component arguments. +The yielded components from Field can be optionally rendered by using the `{{#if}}` helper. +The below example optionally renders the Hint and Error based on component arguments. ```hbs @@ -56,6 +59,8 @@ The yielded components from Field can be optionally rendered by using the `{{#if ### Attributes and Modifiers +Optional. + Attributes are spread to each sub component of the Field via `...attributes`, so HTML attributes and Ember modifiers can be added. ```hbs @@ -72,7 +77,8 @@ Attributes are spread to each sub component of the Field via `...attributes`, so ### Ordering of Components -Ordering of the elements can be changed by adjusting the order of the children. For example, if it is preferred to put the hint block underneath the control. +Ordering of the elements can be changed by adjusting the order of the children. +For example, if it is preferred to put the hint block underneath the control. ```hbs diff --git a/docs/components/file-input-field/index.md b/docs/components/file-input-field/index.md index 9de1964bc..4aa26d031 100644 --- a/docs/components/file-input-field/index.md +++ b/docs/components/file-input-field/index.md @@ -2,12 +2,6 @@ Provides an underlying `` element building on top of the Field component. -## Accepts - -Optional. - -Used to specify the types of files allowed. [See related documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept). - ## Label Required. @@ -54,6 +48,13 @@ Required. Provide trigger text for the FileInputField (aka `Select Files`) via `@trigger`. +## Accepts + +Optional. + +Used to specify the types of files allowed. +[See related documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept). + ## Hint Optional. @@ -101,19 +102,22 @@ Optional. Provide an array of [File](https://developer.mozilla.org/en-US/docs/Web/API/File) objects to the File input via `@files`. -**Note:** To make things easier, the `@files` argument is an array. This makes it convenient to use existing Array methods like `find` and `filter`. +**Note:** To make things easier, the `@files` argument is an array. +This makes it convenient to use existing Array methods like `find` and `filter`. ## Multiple Optional. -If true, allows users to upload multiple files. If false, the `multiple` attribute is not added to the underlying input. +If true, allows users to upload multiple files. +If false, the `multiple` attribute is not added to the underlying input. ## Value and onChange -Optional +Optional. -To tie into the input event, provide `@onChange`. `@onChange` will return two arguments: +To tie into the input event, provide `@onChange`. +`@onChange` will return two arguments: 1. the list of files selected 2. the raw FileEvent @@ -147,21 +151,30 @@ export default class extends Component { ## Disabled State +Optional. + Set the `@isDisabled` argument to disable the ``. ## Read Only State +Optional. + Set the `@isReadOnly` argument to put the input in the read only state. ## Attributes and Modifiers -Consumers have direct access to the underlying [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input), so all attributes are supported. Modifiers can also be added directly to the input as shown in the demo. +Optional. + +Consumers have direct access to the underlying [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input), so all attributes are supported. +Modifiers can also be added directly to the input as shown in the demo. ## Test Selectors ### Root Element -Provide a custom selector via `@rootTestSelector`. This test selector will be used as the value for the `data-root-field` attribute. The Field can be targeted via: +Provide a custom selector via `@rootTestSelector`. +This test selector will be used as the value for the `data-root-field` attribute. +The Field can be targeted via: ```hbs // in a test: assert.dom('[data-root-field="example"]'); diff --git a/docs/components/input-field/index.md b/docs/components/input-field/index.md index 623b70e02..6773a0ad5 100644 --- a/docs/components/input-field/index.md +++ b/docs/components/input-field/index.md @@ -74,7 +74,8 @@ Provide a string to the `@hint` component argument or content to `:hint` named b Optional. -A character counter is exposed via a `secondary` block. It can be combined with any of the other named blocks or label/hint arguments. +A character counter is exposed via a `secondary` block. +It can be combined with any of the other named blocks or label/hint arguments. ```hbs @@ -103,7 +104,11 @@ Provide a string or array of strings to `@error` to render the text into the Err ## Value and onChange -To tie into the input event, provide `@onChange`. `@onChange` will return two arguments, the first being the value, while the second being the raw event object. It's most common to use this in combination with `@value` which will set the value for the input based on the input received from the change event. +Optional. + +To tie into the input event, provide `@onChange`. +`@onChange` will return two arguments, the first being the value, while the second being the raw event object. +It's most common to use this in combination with `@value` which will set the value for the input based on the input received from the change event. ```hbs diff --git a/docs/components/input/index.md b/docs/components/input/index.md index bb2715aa8..9298bd984 100644 --- a/docs/components/input/index.md +++ b/docs/components/input/index.md @@ -1,9 +1,12 @@ # Input -Provides a Toucan-styled [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). If you are building forms, you may be interested in the [InputField](./input-field) component instead. +Provides a Toucan-styled [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). +If you are building forms, you may be interested in the [InputField](./input-field) component instead. ## Value +Optional. + To set the `value` attribute of the ``, provide `@value`. ```hbs @@ -12,6 +15,8 @@ To set the `value` attribute of the ``, provide `@value`. ## onChange +Optional. + To tie into the input event, provide `@onChange`. `@onChange` will return two arguments, the first being the value, while the second being the raw event. ```hbs @@ -34,6 +39,8 @@ export default class extends Component { ## Disabled State +Optional. + Set the `@isDisabled` argument to disable the input. ```hbs @@ -42,6 +49,8 @@ Set the `@isDisabled` argument to disable the input. ## Read Only State +Optional. + Set the `@isReadOnly` argument to put the input in the read only state. ```hbs @@ -50,4 +59,6 @@ Set the `@isReadOnly` argument to put the input in the read only state. ## Error State +Optional. + Set the `@hasError` argument to apply an error box shadow to the ``. diff --git a/docs/components/multiselect-field/index.md b/docs/components/multiselect-field/index.md index e7d20928c..12e790534 100644 --- a/docs/components/multiselect-field/index.md +++ b/docs/components/multiselect-field/index.md @@ -53,7 +53,8 @@ Provide a string to the `@label` component argument or content to the `:label` n Required. -A `:chip` block is required and is used for rendering each selected option. The block has the following block parameters: +A `:chip` block is required and is used for rendering each selected option. +The block has the following block parameters: - `index`: The index of the current chip - `option`: The raw option value for the current chip @@ -71,7 +72,9 @@ The `Chip` component allows for slight customization to the underlying chip. ``` -The `Remove` component contains the removal `X` on each selected chip. Clicking the button will remove the item from the selected options array. When the multiselect is disabled or in the readonly state, the button will not be available. +The `Remove` component contains the removal `X` on each selected chip. +Clicking the button will remove the item from the selected options array. +When the multiselect is disabled or in the readonly state, the button will not be available. A `@label` argument is **required** for accessibility reasons for the Remove component. @@ -270,6 +273,8 @@ Required. ## Selected +Optional. + The currently selected option. ```hbs @@ -382,6 +387,8 @@ Set the `@isReadOnly` argument to put the input in the read only state. ## Attributes and Modifiers +Optional. + Consumers have direct access to the underlying [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input), so all attributes are supported. Modifiers can also be added directly to the input. diff --git a/docs/components/multiselect/index.md b/docs/components/multiselect/index.md index d9ec2de9c..a6df2414a 100644 --- a/docs/components/multiselect/index.md +++ b/docs/components/multiselect/index.md @@ -7,7 +7,8 @@ If you are building forms, you may be interested in the [MultiselectField](./mul Required. -A `:chip` block is required and is used for rendering each selected option. The block returns the following: +A `:chip` block is required and is used for rendering each selected option. +The block returns the following: - `index`: The index of the current chip - `option`: The raw option value for the current chip @@ -25,7 +26,9 @@ The `Chip` component allows for slight customization to the underlying chip. ``` -The `Remove` component contains the removal `X` on each selected chip. Clicking the button will remove the item from the selected options array. When the multiselect is disabled or in the readonly state, the button will not be available. +The `Remove` component contains the removal `X` on each selected chip. +Clicking the button will remove the item from the selected options array. +When the multiselect is disabled or in the readonly state, the button will not be available. A `@label` argument is **required** for accessibility reasons for the Remove component. diff --git a/docs/components/radio-field/index.md b/docs/components/radio-field/index.md index f758c31d7..c2fd754b6 100644 --- a/docs/components/radio-field/index.md +++ b/docs/components/radio-field/index.md @@ -1,6 +1,7 @@ # Radio Field -Provides an opinionated radio element building on top of the Field component. If you are building real radio groups in forms, you'll want to check out our [RadioGroupField](./radio-group-field) component. +Provides an opinionated radio element building on top of the Field component. +If you are building real radio groups in forms, you'll want to check out our [RadioGroupField](./radio-group-field) component. ## Label @@ -86,12 +87,16 @@ Provide a string to the `@hint` component argument or content to `:hint` named b ## Value, Checked State, and onChange -The `@value` argument is required. To tie into the change event, provide `@onChange`. `@onChange` will return two arguments: +Optional. + +The `@value` argument is required. To tie into the change event, provide `@onChange`. +`@onChange` will return two arguments: 1. the value attribute from the target 2. the raw event object -To set the checked state of the radio, the `@selectedValue` and `@value` must match. If these two arguments do not match, the radio will not be checked. +To set the checked state of the radio, the `@selectedValue` and `@value` must match. +If these two arguments do not match, the radio will not be checked. ```hbs `, provide `@value`. ```hbs @@ -12,7 +15,10 @@ To set the `value` attribute of the `