chore: improve documentation consistency

.changeset/thick-eggs-argue.md

@@ -0,0 +1,6 @@
+---
+'@crowdstrike/ember-toucan-core': patch
+'@crowdstrike/ember-toucan-form': patch
+---
+
+Improve documentation consistency.

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.
 

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
 <Form::Controls::Autocomplete

docs/components/button/index.md

@@ -1,9 +1,12 @@
 # Button
 
-Buttons are clickable elements used primarily for actions. Button content expresses what action will occur when the user interacts with it.
+Buttons are clickable elements used primarily for actions. 
+Button content expresses what action will occur when the user interacts with it.
 
 ## Variants
 
+Optional.
+
 You can customize the appearance of the button with the `@variant` component argument.
 
 <div class="flex flex-col gap-4 md:flex-row">
@@ -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
 <Button @isDisabled={{true}}>Disabled</Button>
@@ -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
 <Button @isLoading={{true}}>Loading…</Button>

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
 <Form::Fields::Checkbox @label='Label' @rootTestSelector='example' />

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
 <Form::Fields::CheckboxGroup
@@ -119,6 +126,8 @@ export default class extends Component {
 
 ## Disabled State
 
+Optional.
+
 ### Fieldset
 
 To disable the fieldset and all child checkboxes, set the `@isDisabled` argument directly on the checkbox group field.
@@ -159,6 +168,8 @@ To disable individual checkbox fields, set the `@isDisabled` argument directly o
 
 ## Read Only State
 
+Optional.
+
 ### Fieldset
 
 To set all checkbox group options to readonly, use the `@isReadOnly` argument directly on the Checkbox Group.
@@ -199,7 +210,10 @@ Individual checkboxes can be set to read only by setting the `@isReadOnly` argum
 
 ## 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 individual radio fields.
+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 individual radio fields.
 
 ## All UI States
 

docs/components/checkbox/index.md

@@ -1,9 +1,12 @@
 # Checkbox
 
-Provides a Toucan-styled [checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox). If you are building forms, you may be interested in the [CheckboxField](./checkbox-field) component instead.
+Provides a Toucan-styled [checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox). 
+If you are building forms, you may be interested in the [CheckboxField](./checkbox-field) component instead.
 
 ## Checked State
 
+Optional.
+
 To set the `checked` attribute of the checkbox, provide `@isChecked`.
 
 ```hbs
@@ -20,7 +23,11 @@ assert.dom('[data-checkbox-2]').isNotChecked();
 
 ## Indeterminate
 
-Checkboxes have the ability to be in the [indeterminate state](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes). This is accomplished with `@isIndeterminate`. It is up to the consumer to decide what will force the checkbox into the indeterminate state.
+Optional.
+
+Checkboxes have the ability to be in the [indeterminate state](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes). 
+This is accomplished with `@isIndeterminate`. 
+It is up to the consumer to decide what will force the checkbox into the indeterminate state.
 
 ```hbs
 <Form::Controls::Checkbox @isIndeterminate={{true}} data-checkbox />
@@ -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)

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
 <Form::Field as |field|>
@@ -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
 <Form::Field as |field|>

docs/components/file-input-field/index.md

@@ -2,12 +2,6 @@
 
 Provides an underlying `<input type="file">` 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 `<input type="file">`.
 
 ## 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"]');