docs: incorporate the api reference style guide in some t-named components

src/components/tab-nav/tab-nav.tsx

@@ -42,12 +42,12 @@ export class TabNav {
   //--------------------------------------------------------------------------
 
   /**
-   * Name to use when saving selected tab data to localStorage
+   * Specifies the name when saving selected `calcite-tab` data to `localStorage`.
    */
   @Prop() storageId: string;
 
   /**
-   * Pass the same string to multiple tab navs to keep them all in sync if one changes
+   * Specifies text to update multiple components to keep in sync if one changes.
    */
   @Prop() syncId: string;
 
@@ -275,7 +275,7 @@ export class TabNav {
   //--------------------------------------------------------------------------
 
   /**
-   * Emitted when the active tab changes
+   * Emits when the selected `calcite-tab` changes.
    *
    * @see [TabChangeEventDetail](https://github.com/Esri/calcite-components/blob/master/src/components/tab/interfaces.ts#L1)
    */

src/components/tab-title/tab-title.tsx

@@ -45,9 +45,11 @@ export class TabTitle implements InteractiveComponent {
   //--------------------------------------------------------------------------
 
   /**
-   * Show this tab title as selected
+   * When true, the component and its respective `calcite-tab` contents are selected.
    *
-   * @deprecated Use selected instead.
+   * Only one tab can be selected within the `calcite-tabs` parent.
+   *
+   * @deprecated Use "selected" instead.
    */
   @Prop({ reflect: true, mutable: true }) active = false;
 
@@ -57,7 +59,9 @@ export class TabTitle implements InteractiveComponent {
   }
 
   /**
-   * When true, display this tab title as selected.
+   * When true, the component and its respective `calcite-tab` contents are selected.
+   *
+   * Only one tab can be selected within the `calcite-tabs` parent.
    */
   @Prop({ reflect: true, mutable: true }) selected = false;
 
@@ -69,16 +73,16 @@ export class TabTitle implements InteractiveComponent {
     }
   }
 
-  /** Disable this tab title  */
+  /** When true, interaction is prevented and the component is displayed with lower opacity.  */
   @Prop({ reflect: true }) disabled = false;
 
-  /** optionally pass an icon to display at the end of a tab title - accepts calcite ui icon names  */
+  /** Specifies an icon to display at the end of the component - accepts Calcite UI icon names.  */
   @Prop({ reflect: true }) iconEnd?: string;
 
-  /** flip the icon(s) in rtl */
+  /** When true, the icon will be flipped when the element direction is right-to-left ("rtl"). */
   @Prop({ reflect: true }) iconFlipRtl?: FlipContext;
 
-  /** optionally pass an icon to display at the start of a tab title - accepts calcite ui icon names  */
+  /** Specifies an icon to display at the start of the component - accepts Calcite UI icon names.  */
   @Prop({ reflect: true }) iconStart?: string;
 
   /**
@@ -102,8 +106,9 @@ export class TabTitle implements InteractiveComponent {
   @Prop({ reflect: true, mutable: true }) bordered = false;
 
   /**
-   * Optionally include a unique name for the tab title,
-   * be sure to also set this name on the associated tab.
+   * Specifies a unique name for the component.
+   *
+   * When specified, use the same value on the `calcite-tab`.
    */
   @Prop({ reflect: true }) tab?: string;
 
@@ -279,14 +284,14 @@ export class TabTitle implements InteractiveComponent {
   //--------------------------------------------------------------------------
 
   /**
-   * Fires when a specific tab is activated. Emits the "tab" property or the index position.
+   * Fires when a `calcite-tab` is selected. Emits the "tab" property, or the index position.
    *
    * @see [TabChangeEventDetail](https://github.com/Esri/calcite-components/blob/master/src/components/tab/interfaces.ts#L1)
    */
   @Event({ cancelable: false }) calciteTabsActivate: EventEmitter<TabChangeEventDetail>;
 
   /**
-   * Fires when a specific tab is activated (`event.details`)
+   * Fires when a `calcite-tab` is selected (`event.details`).
    *
    * @see [TabChangeEventDetail](https://github.com/Esri/calcite-components/blob/master/src/components/tab/interfaces.ts#L1)
    * @internal
@@ -315,7 +320,7 @@ export class TabTitle implements InteractiveComponent {
   //--------------------------------------------------------------------------
 
   /**
-   * Return the index of this title within the nav
+   * Returns the index of the title within the `calcite-tab-nav`.
    */
   @Method()
   async getTabIndex(): Promise<number> {

src/components/tab/tab.tsx

@@ -18,7 +18,7 @@ import { nodeListToArray } from "../../utils/dom";
 import { Scale } from "../interfaces";
 
 /**
- * @slot - A slot for adding custom content.
+ * @slot - A slot for adding content to the component.
  */
 @Component({
   tag: "calcite-tab",
@@ -41,15 +41,18 @@ export class Tab {
   //--------------------------------------------------------------------------
 
   /**
-   * Optionally include a unique name for this tab,
-   * be sure to also set this name on the associated title.
+   * Specifies a unique name for the component.
+   *
+   * When specified, use the same value on the `calcite-tab-title`.
    */
-  @Prop({ reflect: true }) tab: string;
+  @Prop({ reflect: true }) tab?: string;
 
   /**
-   * Show this tab
+   * When true, the component's contents are selected.
+   *
+   * Only one tab can be selected within the `calcite-tabs` parent.
    *
-   * @deprecated Use selected instead.
+   * @deprecated Use "selected" instead.
    */
   @Prop({ reflect: true, mutable: true }) active = false;
 
@@ -59,7 +62,9 @@ export class Tab {
   }
 
   /**
-   * When true, display this tab.
+   * When true, the component's contents are selected.
+   *
+   * Only one tab can be selected within the `calcite-tabs` parent.
    */
   @Prop({ reflect: true, mutable: true }) selected = false;
 
@@ -167,7 +172,7 @@ export class Tab {
   //--------------------------------------------------------------------------
 
   /**
-   * Return the index of this tab within the tab array
+   * Returns the index of the component item within the tab array.
    */
   @Method()
   async getTabIndex(): Promise<number> {

src/components/tabs/tabs.tsx

@@ -5,7 +5,7 @@ import { SLOTS } from "./resources";
 
 /**
  * @slot - A slot for adding `calcite-tab`s.
- * @slot tab-nav - A slot for adding a tab navigation component.
+ * @slot tab-nav - A slot for adding a `calcite-tab-nav`.
  */
 @Component({
   tag: "calcite-tabs",
@@ -28,23 +28,23 @@ export class Tabs {
   //--------------------------------------------------------------------------
 
   /**
-   * Align tab titles to the edge or fully justify them across the tab nav ("center")
+   * Specifies the layout of the `calcite-tab-nav`, justifying the `calcite-tab-title`s to the start ("inline"), or across and centered ("center").
    */
   @Prop({ reflect: true }) layout: TabLayout = "inline";
 
   /**
-   * Display the tabs top (default) or bottom of the tab content. above and below are deprecated.
+   * Specifies the position of the component in relation to the `calcite-tab`s. The "above" and "below" values are deprecated.
    *
    */
   @Prop({ reflect: true }) position: TabPosition = "top";
 
   /**
-   * Specify the scale of the tabs component, defaults to m
+   * Specifies the size of the component.
    */
   @Prop({ reflect: true }) scale: Scale = "m";
 
   /**
-   * Optionally enable tabs to appear like a folder-style menu when its layout is "inline"
+   * When true and layout is set to "inline", the component will display with a folder style menu.
    */
   @Prop({ reflect: true, mutable: true }) bordered = false;
 

src/components/tile-select-group/tile-select-group.tsx

@@ -25,10 +25,14 @@ export class TileSelectGroup implements InteractiveComponent {
   //
   //--------------------------------------------------------------------------
 
-  /** The disabled state of the tile select. */
+  /** When true, interaction is prevented and the component is displayed with lower opacity. */
   @Prop({ reflect: true }) disabled = false;
 
-  /** Tiles by default move horizontally, stacking with each row, vertical allows single-column layouts */
+  /**
+   * Defines the layout of the component.
+   *
+   * Use "horizontal" for rows, and "vertical" for a single column.
+   */
   @Prop({ reflect: true }) layout?: TileSelectGroupLayout = "horizontal";
 
   //--------------------------------------------------------------------------

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

@@ -40,50 +40,54 @@ export class TileSelect implements InteractiveComponent {
   //
   //--------------------------------------------------------------------------
 
-  /** The checked state of the tile select. */
+  /** When true, the component is checked. */
   @Prop({ reflect: true, mutable: true }) checked = false;
 
   @Watch("checked")
   checkedChanged(newChecked: boolean): void {
     this.input.checked = newChecked;
   }
 
-  /** The description text that appears beneath the heading of the tile. */
+  /** A description for the component, which displays below the heading. */
   @Prop({ reflect: true }) description?: string;
 
-  /** The disabled state of the tile select. */
+  /** When true, interaction is prevented and the component is displayed with lower opacity. */
   @Prop({ reflect: true }) disabled = false;
 
-  /** The heading text that appears between the icon and description of the tile. */
+  /** The component header text, which displays between the icon and description. */
   @Prop({ reflect: true }) heading?: string;
 
-  /** The hidden state of the tile select. */
+  /** When true, the component is not displayed and is not focusable or checkable. */
   @Prop({ reflect: true }) hidden = false;
 
-  /** The icon that appears at the top of the tile. */
+  /** Specifies an icon to display. */
   @Prop({ reflect: true }) icon?: string;
 
-  /** The name of the tile select.  This name will appear in form submissions as either a radio or checkbox identifier based on the `type` property. */
+  /** Specifies the name of the component on form submission. */
   @Prop({ reflect: true }) name;
 
   @Watch("name")
   nameChanged(newName: string): void {
     this.input.name = newName;
   }
 
-  /** Display an interactive radio or checkbox. */
+  /** When true, displays an interactive input based on the "type" property. */
   @Prop({ reflect: true }) inputEnabled = false;
 
-  /** The side of the tile that the radio or checkbox appears on when inputEnabled is true. */
+  /** When inputEnabled is true, the placement of the interactive input on the component. */
   @Prop({ reflect: true }) inputAlignment: Extract<"end" | "start", Alignment> = "start";
 
-  /** The selection mode of the tile select: radio (single) or checkbox (multiple). */
+  /**
+   * The selection mode of the component.
+   *
+   * Use radio for single selection, and checkbox for multiple selections.
+   */
   @Prop({ reflect: true }) type: TileSelectType = "radio";
 
-  /** The value of the tile select.  This value will appear in form submissions when this tile select is checked. */
+  /** The component's value. */
   @Prop() value?: any;
 
-  /** specify the width of the tile, defaults to auto */
+  /** Specifies the width of the component. */
   @Prop({ reflect: true }) width: Extract<"auto" | "full", Width> = "auto";
 
   //--------------------------------------------------------------------------
@@ -112,7 +116,11 @@ export class TileSelect implements InteractiveComponent {
   //--------------------------------------------------------------------------
 
   /**
-   * Emits a custom change event.  For checkboxes, it emits when the checkbox is checked or unchecked.  For radios it only emits when it is checked.
+   * Emits a custom change event.
+   *
+   * For checkboxes it emits when checked or unchecked.
+   *
+   * For radios it only emits when checked.
    */
   @Event({ cancelable: false }) calciteTileSelectChange: EventEmitter<void>;
 

src/components/tile/tile.tsx

@@ -9,8 +9,8 @@ import {
 import { InteractiveComponent, updateHostInteraction } from "../../utils/interactive";
 
 /**
- * @slot content-start - A slot for adding non-actionable elements before the tile content.
- * @slot content-end - A slot for adding non-actionable elements after the tile content.
+ * @slot content-start - A slot for adding non-actionable elements before the component's content.
+ * @slot content-end - A slot for adding non-actionable elements after the component's content.
  */
 @Component({
   tag: "calcite-tile",
@@ -32,37 +32,45 @@ export class Tile implements ConditionalSlotComponent, InteractiveComponent {
   //
   //--------------------------------------------------------------------------
 
-  /** The active state of the tile. */
+  /**
+   * When true, the component is active.
+   */
   @Prop({ reflect: true }) active = false;
 
-  /** The description text that appears beneath the heading of the tile. */
+  /**
+   * A description for the component, which displays below the heading.
+   */
   @Prop({ reflect: true }) description?: string;
 
   /**
-   * When true, prevents interaction.
+   * When true, interaction is prevented and the component is displayed with lower opacity.
    */
   @Prop({ reflect: true }) disabled = false;
 
-  /** The embed mode of the tile.  When true, renders without a border and padding for use by other components. */
+  /**
+   * The component's embed mode.
+   *
+   * When true, renders without a border and padding for use by other components.
+   */
   @Prop({ reflect: true }) embed = false;
 
   /**
-   * The focused state of the tile.
+   * The focused state of the component.
    *
    * @internal
    */
   @Prop({ reflect: true }) focused = false;
 
-  /** The heading text that appears between the icon and description of the tile. */
+  /** The component header text, which displays between the icon and description. */
   @Prop({ reflect: true }) heading?: string;
 
-  /** The hidden state of the tile. */
+  /** When true, the component is not displayed and is not focusable.  */
   @Prop({ reflect: true }) hidden = false;
 
-  /** The (optional) url for the tile. (Only applies when embed is set to false) */
+  /** When embed is "false", the url for the component. */
   @Prop({ reflect: true }) href?: string;
 
-  /** The icon that appears at the top of the tile. */
+  /** Specifies an icon to display. */
   @Prop({ reflect: true }) icon?: string;
 
   // --------------------------------------------------------------------------