docs: improve consistency for component prop descriptions

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

@@ -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/checkbox/checkbox.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/chip/chip.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/combobox/combobox.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";
 

packages/calcite-components/src/components/fab/fab.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/input-number/input-number.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-time-zone/input-time-zone.tsx

@@ -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/radio-button/radio-button.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/segmented-control/segmented-control.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/shell-panel/shell-panel.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"` 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, and
+   *
+   * `"overlay"` full height, displays on top of center content.
    */
   @Prop({ reflect: true }) displayMode: DisplayMode = "dock";
 

packages/calcite-components/src/components/switch/switch.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/text-area/text-area.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/tile-select/tile-select.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/tree/tree.tsx

@@ -41,16 +41,21 @@ 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"
+   * `"single-persist"` allows and requires one selection.
    */
   @Prop({ mutable: true, reflect: true }) selectionMode: SelectionMode = "single";