docs: improve consistency for component prop descriptions (#8580)

**Related Issue:** #7071

## Summary
Updates doc consistency across various components defined in the above
issue for props, events, methods, and css vars, including:

- `block-section`
- `checkbox`
- `chip`
- `combobox`
- `fab`
- `input-number`
- `input-time-zone`
- `radio-button`
- `segmented-control`
- `shell-panel`
- `switch`
- `text-area`
- `tile-select`
- `tree`

---------

Co-authored-by: Matt Driscoll <[email protected]>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

packages/calcite-components/src/components.d.ts

@@ -65,11 +65,11 @@ export class BlockSection implements LocalizedComponent, T9nComponent, LoadableC
   @Prop() text: string;
 
   /**
-   * Specifies how the component's toggle is displayed -
+   * Specifies how the component's toggle is displayed, where:
    *
-   * `"button"` (selectable header), or
+   * `"button"` sets the toggle to a selectable header, and
    *
-   * `"switch"` (toggle switch).
+   * `"switch"` sets the toggle to a switch.
    */
   @Prop({ reflect: true }) toggleDisplay: BlockSectionToggleDisplay = "button";
 

packages/calcite-components/src/components/block-section/block-section.tsx

@@ -97,7 +97,7 @@ export class Button
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */
@@ -404,7 +404,8 @@ export class Button
   private setTooltipText = (): void => {
     const { contentEl } = this;
     if (contentEl) {
-      this.tooltipText = contentEl.offsetWidth < contentEl.scrollWidth ? this.el.innerText || null : null;
+      this.tooltipText =
+        contentEl.offsetWidth < contentEl.scrollWidth ? this.el.innerText || null : null;
     }
   };
 

packages/calcite-components/src/components/button/button.tsx

@@ -55,7 +55,7 @@ export class Checkbox
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/checkbox/checkbox.tsx

@@ -78,7 +78,7 @@ export class Chip
   @Prop({ reflect: true }) appearance: Extract<"outline" | "outline-fill" | "solid", Appearance> =
     "solid";
 
-  /** Specifies the kind of the component (will apply to border and background if applicable). */
+  /** Specifies the kind of the component, which will apply to border and background if applicable. */
   @Prop({ reflect: true }) kind: Extract<"brand" | "inverse" | "neutral", Kind> = "neutral";
 
   /** When `true`, a close button is added to the component. */

packages/calcite-components/src/components/chip/chip.tsx

@@ -122,8 +122,13 @@ export class Combobox
   @Prop({ reflect: true }) clearDisabled = false;
 
   /**
-   * When `selectionMode` is `"ancestors"` or `"multiple"`, specifies the display of multiple `calcite-combobox-item` selections
-   * - `"all"` (displays all selections with individual `calcite-chip`s), `"fit"` (displays individual `calcite-chip`s that scale to the component's size, including a non-closable `calcite-chip`, which provides the number of additional `calcite-combobox-item` selections not visually displayed), or `"single"` (display one `calcite-chip` with the total number of selections).
+   * When `selectionMode` is `"ancestors"` or `"multiple"`, specifies the display of multiple `calcite-combobox-item` selections, where:
+   *
+   * `"all"` displays all selections with individual `calcite-chip`s,
+   *
+   * `"fit"` displays individual `calcite-chip`s that scale to the component's size, including a non-closable `calcite-chip`, which provides the number of additional `calcite-combobox-item` selections not visually displayed, and
+   *
+   * `"single"` displays one `calcite-chip` with the total number of selections.
    */
   @Prop({ reflect: true }) selectionDisplay: SelectionDisplay = "all";
 
@@ -153,7 +158,7 @@ export class Combobox
   }
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/combobox/combobox.tsx

@@ -34,7 +34,7 @@ export class Fab implements InteractiveComponent, LoadableComponent {
   @Prop({ reflect: true }) appearance: Extract<"solid" | "outline-fill", Appearance> = "solid";
 
   /**
-   * Specifies the kind of the component (will apply to border and background).
+   * Specifies the kind of the component, which will apply to border and background.
    */
   @Prop({ reflect: true }) kind: Extract<"brand" | "danger" | "inverse" | "neutral", Kind> =
     "brand";

packages/calcite-components/src/components/fab/fab.tsx

@@ -131,7 +131,7 @@ export class InputDatePicker
   }
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */
@@ -379,7 +379,7 @@ export class InputDatePicker
   //--------------------------------------------------------------------------
 
   /**
-   * Fires when the component's value changes.
+   * Fires when the component's `value` changes.
    */
   @Event({ cancelable: false }) calciteInputDatePickerChange: EventEmitter<void>;
 

packages/calcite-components/src/components/input-date-picker/input-date-picker.tsx

@@ -123,7 +123,7 @@ export class InputNumber
   }
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/input-number/input-number.tsx

@@ -103,7 +103,7 @@ export class InputText
   }
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/input-text/input-text.tsx

@@ -203,7 +203,7 @@ export class InputTimePicker
   }
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */
@@ -392,7 +392,7 @@ export class InputTimePicker
   @Event({ cancelable: false }) calciteInputTimePickerBeforeOpen: EventEmitter<void>;
 
   /**
-   * Fires when the time value is changed as a result of user input.
+   * Fires when the component's `value` is changes.
    */
   @Event({ cancelable: true }) calciteInputTimePickerChange: EventEmitter<void>;
 

packages/calcite-components/src/components/input-time-picker/input-time-picker.tsx

@@ -78,7 +78,7 @@ export class InputTimeZone
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */
@@ -151,9 +151,9 @@ export class InputTimeZone
   @Prop({ reflect: true }) overlayPositioning: OverlayPositioning = "absolute";
 
   /**
-   * This date will be used as a reference to Daylight Savings Time when creating time zone item groups.
+   * This `date` will be used as a reference to Daylight Savings Time when creating time zone item groups.
    *
-   * It can be either a Date instance or a string in ISO format (YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS.SSSZ)
+   * It can be either a Date instance or a string in ISO format (`"YYYY-MM-DD"`, `"YYYY-MM-DDTHH:MM:SS.SSSZ"`).
    *
    * @see [Date.prototype.toISOString](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
    */
@@ -211,14 +211,29 @@ export class InputTimeZone
   //
   //--------------------------------------------------------------------------
 
+  /**
+   * Fires when the component is requested to be closed and before the closing transition begins.
+   */
   @Event({ cancelable: false }) calciteInputTimeZoneBeforeClose: EventEmitter<void>;
 
+  /**
+   * Fires when the component is added to the DOM but not rendered, and before the opening transition begins.
+   */
   @Event({ cancelable: false }) calciteInputTimeZoneBeforeOpen: EventEmitter<void>;
 
+  /**
+   * Fires when the component's `value` changes.
+   */
   @Event({ cancelable: false }) calciteInputTimeZoneChange: EventEmitter<void>;
 
+  /**
+   * Fires after the component is closed and animation is complete.
+   */
   @Event({ cancelable: false }) calciteInputTimeZoneClose: EventEmitter<void>;
 
+  /**
+   * Fires after the component is opened and animation is complete.
+   */
   @Event({ cancelable: false }) calciteInputTimeZoneOpen: EventEmitter<void>;
 
   //--------------------------------------------------------------------------

packages/calcite-components/src/components/input-time-zone/input-time-zone.tsx

@@ -124,7 +124,7 @@ export class Input
   }
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/input/input.tsx

@@ -51,7 +51,7 @@ export class Meter implements FormComponent, LoadableComponent, LocalizedCompone
   @Prop({ reflect: true }) fillType: "single" | "range" = "range";
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/meter/meter.tsx

@@ -80,7 +80,7 @@ export class RadioButton
   @Prop({ mutable: true, reflect: true }) focused = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/radio-button/radio-button.tsx

@@ -71,7 +71,7 @@ export class Rating
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/rating/rating.tsx

@@ -63,7 +63,7 @@ export class SegmentedControl
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/segmented-control/segmented-control.tsx

@@ -75,7 +75,7 @@ export class Select
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/select/select.tsx

@@ -75,8 +75,13 @@ export class ShellPanel implements ConditionalSlotComponent, LocalizedComponent,
   }
 
   /**
-   * Specifies the display mode - `"dock"` (full height, displays adjacent to center content), `"float"` (not full height, content is separated detached from `calcite-action-bar`, displays on top of center content),
-   * or `"overlay"` (full height, displays on top of center content).
+   * Specifies the display mode of the component, where:
+   *
+   * `"dock"` displays at full height adjacent to center content,
+   *
+   * `"overlay"` displays at full height on top of center content, and
+   *
+   * `"float"` does not display at full height with content separately detached from `calcite-action-bar` on top of center content.
    */
   @Prop({ reflect: true }) displayMode: DisplayMode = "dock";
 

packages/calcite-components/src/components/shell-panel/shell-panel.tsx

@@ -79,7 +79,7 @@ export class Slider
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/slider/slider.tsx

@@ -51,7 +51,7 @@ export class Switch
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/switch/switch.tsx

@@ -100,7 +100,7 @@ export class TextArea
   @Prop({ reflect: true }) disabled = false;
 
   /**
-   * The ID of the form that will be associated with the component.
+   * The `id` of the form that will be associated with the component.
    *
    * When not set, the component will be associated with its ancestor form element, if any.
    */

packages/calcite-components/src/components/text-area/text-area.tsx

@@ -85,9 +85,11 @@ export class TileSelect implements InteractiveComponent, LoadableComponent {
   @Prop({ reflect: true }) inputAlignment: Extract<"end" | "start", Alignment> = "start";
 
   /**
-   * The selection mode of the component.
+   * Specifies the selection mode of the component, where:
    *
-   * Use `"radio"` for single selection, and `"checkbox"` for multiple selections.
+   * `"radio"` is for single selection, and
+   *
+   * `"checkbox"` is for multiple selections.
    */
   @Prop({ reflect: true }) type: TileSelectType = "radio";
 

packages/calcite-components/src/components/tile-select/tile-select.tsx

@@ -41,13 +41,20 @@ export class Tree {
   @Prop({ mutable: true, reflect: true }) scale: Scale = "m";
 
   /**
-   * Specifies the selection mode, where
+   * Specifies the selection mode of the component, where:
+   *
    * `"ancestors"` displays with a checkbox and allows any number of selections from corresponding parent and child selections,
+   *
    * `"children"` allows any number of selections from one parent from corresponding parent and child selections,
+   *
    * `"multichildren"` allows any number of selections from corresponding parent and child selections,
+   *
    * `"multiple"` allows any number of selections,
+   *
    * `"none"` allows no selections,
+   *
    * `"single"` allows one selection, and
+   *
    * `"single-persist"` allows and requires one selection.
    *
    * @default "single"