From aba8b34003efdf07454a73994f856bd04cdf240f Mon Sep 17 00:00:00 2001 From: Kitty Hurley Date: Tue, 23 Aug 2022 15:06:53 -0500 Subject: [PATCH 1/3] docs: tab components --- src/components/tab-nav/tab-nav.tsx | 6 +++--- src/components/tab-title/tab-title.tsx | 29 +++++++++++++++----------- src/components/tab/tab.tsx | 21 ++++++++++++------- src/components/tabs/tabs.tsx | 10 ++++----- 4 files changed, 38 insertions(+), 28 deletions(-) diff --git a/src/components/tab-nav/tab-nav.tsx b/src/components/tab-nav/tab-nav.tsx index 0bc810d751d..6cff75cb2c4 100644 --- a/src/components/tab-nav/tab-nav.tsx +++ b/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) */ diff --git a/src/components/tab-title/tab-title.tsx b/src/components/tab-title/tab-title.tsx index de19bb0226e..10dab2a4fe0 100644 --- a/src/components/tab-title/tab-title.tsx +++ b/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; /** - * 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 { diff --git a/src/components/tab/tab.tsx b/src/components/tab/tab.tsx index 5d43ea94712..724fef5a520 100644 --- a/src/components/tab/tab.tsx +++ b/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 { diff --git a/src/components/tabs/tabs.tsx b/src/components/tabs/tabs.tsx index 34ddd0f4d1e..d0d058a3001 100644 --- a/src/components/tabs/tabs.tsx +++ b/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; From 1f8dd3baf5bf207dd873afaf13c8dfa01837c5f7 Mon Sep 17 00:00:00 2001 From: Kitty Hurley Date: Wed, 24 Aug 2022 18:07:08 -0500 Subject: [PATCH 2/3] tile components --- .../tile-select-group/tile-select-group.tsx | 8 +++-- src/components/tile-select/tile-select.tsx | 34 ++++++++++++------- src/components/tile/tile.tsx | 30 ++++++++++------ 3 files changed, 46 insertions(+), 26 deletions(-) diff --git a/src/components/tile-select-group/tile-select-group.tsx b/src/components/tile-select-group/tile-select-group.tsx index 501052244a4..7639d4c57c9 100644 --- a/src/components/tile-select-group/tile-select-group.tsx +++ b/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"; //-------------------------------------------------------------------------- diff --git a/src/components/tile-select/tile-select.tsx b/src/components/tile-select/tile-select.tsx index 77db1f9790b..58322cceb5c 100644 --- a/src/components/tile-select/tile-select.tsx +++ b/src/components/tile-select/tile-select.tsx @@ -40,7 +40,7 @@ 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") @@ -48,22 +48,22 @@ export class TileSelect implements InteractiveComponent { 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") @@ -71,19 +71,23 @@ export class TileSelect implements InteractiveComponent { 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; diff --git a/src/components/tile/tile.tsx b/src/components/tile/tile.tsx index 5c6b6f208a0..36e711a49fc 100644 --- a/src/components/tile/tile.tsx +++ b/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; // -------------------------------------------------------------------------- From cefeceba9cb68a2748c413280f3e6523b873caee Mon Sep 17 00:00:00 2001 From: Kitty Hurley Date: Fri, 26 Aug 2022 17:03:43 -0500 Subject: [PATCH 3/3] time picker and tip components --- src/components/time-picker/time-picker.tsx | 32 ++++++++++----------- src/components/tip-group/tip-group.tsx | 2 +- src/components/tip-manager/tip-manager.scss | 4 +-- src/components/tip-manager/tip-manager.tsx | 24 ++++++++-------- src/components/tip/tip.tsx | 18 ++++++------ 5 files changed, 41 insertions(+), 39 deletions(-) diff --git a/src/components/time-picker/time-picker.tsx b/src/components/time-picker/time-picker.tsx index 660bf95112f..e5a4a948135 100644 --- a/src/components/time-picker/time-picker.tsx +++ b/src/components/time-picker/time-picker.tsx @@ -57,91 +57,91 @@ export class TimePicker { //-------------------------------------------------------------------------- /** - * aria-label for the hour input + * Accessible name for the component's hour input. * * @default "Hour" */ @Prop() intlHour = TEXT.hour; /** - * aria-label for the hour down button + * Accessible name for the component's hour down button. * * @default "Decrease hour" */ @Prop() intlHourDown = TEXT.hourDown; /** - * aria-label for the hour up button + * Accessible name for the component's hour up button. * * @default "Increase hour" */ @Prop() intlHourUp = TEXT.hourUp; /** - * aria-label for the meridiem (am/pm) input + * Accessible name for the component's meridiem (AM/PM) input. * * @default "AM/PM" */ @Prop() intlMeridiem = TEXT.meridiem; /** - * aria-label for the meridiem (am/pm) down button + * Accessible name for the component's meridiem (AM/PM) down button. * * @default "Decrease AM/PM" */ @Prop() intlMeridiemDown = TEXT.meridiemDown; /** - * aria-label for the meridiem (am/pm) up button + * Accessible name for the component's meridiem (AM/PM) up button. * * @default "Increase AM/PM" */ @Prop() intlMeridiemUp = TEXT.meridiemUp; /** - * aria-label for the minute input + * Accessible name for the component's minute input. * * @default "Minute" */ @Prop() intlMinute = TEXT.minute; /** - * aria-label for the minute down button + * Accessible name for the component's minute down button. * * @default "Decrease minute" */ @Prop() intlMinuteDown = TEXT.minuteDown; /** - * aria-label for the minute up button + * Accessible name for the component's minute up button. * * @default "Increase minute" */ @Prop() intlMinuteUp = TEXT.minuteUp; /** - * aria-label for the second input + * Accessible name for the component's second input. * * @default "Second" */ @Prop() intlSecond = TEXT.second; /** - * aria-label for the second down button + * Accessible name for the component's second down button. * * @default "Decrease second" */ @Prop() intlSecondDown = TEXT.secondDown; /** - * aria-label for the second up button + * Accessible name for the component's second up button. * * @default "Increase second" */ @Prop() intlSecondUp = TEXT.secondUp; /** - * BCP 47 language tag for desired language and country format + * BCP 47 language tag for desired language and country format. * * @internal */ @@ -154,13 +154,13 @@ export class TimePicker { this.setValue(this.value, false); } - /** The scale (size) of the time picker */ + /** Specifies the size of the component. */ @Prop() scale: Scale = "m"; - /** number (seconds) that specifies the granularity that the value must adhere to */ + /** Specifies the granularity the "value" must adhere to (in seconds). */ @Prop() step = 60; - /** The selected time in UTC (always 24-hour format) */ + /** The component's value in UTC (always 24-hour format). */ @Prop({ mutable: true }) value: string = null; @Watch("value") diff --git a/src/components/tip-group/tip-group.tsx b/src/components/tip-group/tip-group.tsx index 299a6aeac9d..54f61a67f6b 100644 --- a/src/components/tip-group/tip-group.tsx +++ b/src/components/tip-group/tip-group.tsx @@ -16,7 +16,7 @@ export class TipGroup { // -------------------------------------------------------------------------- /** - * The title used for all nested tips. + * The component header text for all nested `calcite-tip`s. * */ @Prop() groupTitle?: string; diff --git a/src/components/tip-manager/tip-manager.scss b/src/components/tip-manager/tip-manager.scss index 310035e7d68..f58867ad3c5 100644 --- a/src/components/tip-manager/tip-manager.scss +++ b/src/components/tip-manager/tip-manager.scss @@ -3,8 +3,8 @@ * * These properties can be overridden using the component's tag as selector. * - * @prop --calcite-tip-manager-height: the maximum height of the tip-manager - * @prop --calcite-tip-max-width: the maximum width of a slotted tip within tip-manager + * @prop --calcite-tip-manager-height: The maximum height of the component. + * @prop --calcite-tip-max-width: The maximum width of a slotted `calcite-tip` within the component. */ :host { diff --git a/src/components/tip-manager/tip-manager.tsx b/src/components/tip-manager/tip-manager.tsx index f0e773bdae4..fc6ee07feed 100644 --- a/src/components/tip-manager/tip-manager.tsx +++ b/src/components/tip-manager/tip-manager.tsx @@ -30,7 +30,7 @@ export class TipManager { // // -------------------------------------------------------------------------- /** - * Closed state of the `calcite-tip-manager`. + * When true, does not display or position the component. */ @Prop({ reflect: true, mutable: true }) closed = false; @@ -41,32 +41,32 @@ export class TipManager { } /** - * Number at which section headings should start for this component. + * Specifies the number at which section headings should start. */ @Prop() headingLevel: HeadingLevel; /** - * Alternate text for closing the tip. + * Accessible name for the component's close button. */ @Prop() intlClose?: string; /** - * The default group title for the `calcite-tip-manager`. + * Accessible name for the `calcite-tip-group` title. */ @Prop() intlDefaultTitle?: string; /** - * Alternate text for navigating to the next tip. + * Accessible name for navigating to the next tip. */ @Prop() intlNext?: string; /** - * Label that appears on hover of pagination icon. + * Text that accompanies the component's pagination. */ @Prop() intlPaginationLabel?: string; /** - * Alternate text for navigating to the previous tip. + * Accessible name for navigating to the previous tip. */ @Prop() intlPrevious?: string; @@ -119,7 +119,7 @@ export class TipManager { // // -------------------------------------------------------------------------- - /** Selects the next tip to display */ + /** Selects the next `calcite-tip` to display. */ @Method() async nextTip(): Promise { this.direction = "advancing"; @@ -127,7 +127,7 @@ export class TipManager { this.selectedIndex = (nextIndex + this.total) % this.total; } - /** Selects the previous tip to display */ + /** Selects the previous `calcite-tip` to display. */ @Method() async previousTip(): Promise { this.direction = "retreating"; @@ -142,14 +142,14 @@ export class TipManager { // -------------------------------------------------------------------------- /** - * Emitted when the `calcite-tip-manager` has been toggled open or closed. + * Emits when the component has been open or closed. * - * @deprecated use calciteTipManagerClose instead. + * @deprecated use "calciteTipManagerClose" instead. */ @Event({ cancelable: false }) calciteTipManagerToggle: EventEmitter; /** - * Emitted when the `calcite-tip-manager` has been closed. + * Emits when the component has been closed. */ @Event({ cancelable: false }) calciteTipManagerClose: EventEmitter; diff --git a/src/components/tip/tip.tsx b/src/components/tip/tip.tsx index 10d53edcb97..19e4fd823aa 100644 --- a/src/components/tip/tip.tsx +++ b/src/components/tip/tip.tsx @@ -10,7 +10,7 @@ import { /** * @slot - A slot for adding text and a hyperlink. - * @slot thumbnail - A slot for adding an HTML image element to the tip. + * @slot thumbnail - A slot for adding an HTML image element. */ @Component({ tag: "calcite-tip", @@ -24,32 +24,34 @@ export class Tip implements ConditionalSlotComponent { // // -------------------------------------------------------------------------- /** - * No longer displays the tip. + * When true, the component does not display. */ @Prop({ reflect: true, mutable: true }) dismissed = false; /** - * Indicates whether the tip can be dismissed. + * When true, the close button is not present on the component. */ @Prop({ reflect: true }) nonDismissible = false; /** - * The heading of the tip. + * The component header text. */ @Prop() heading?: string; /** - * Number at which section headings should start for this component. + * Specifies the number at which section headings should start. */ @Prop() headingLevel: HeadingLevel; /** - * The selected state of the tip if it is being used inside a `calcite-tip-manager`. + * When true and if it has a parent `calcite-tip-manager`, the component is selected. + * + * Only one tip can be selected within the `calcite-tip-manager` parent. */ @Prop({ reflect: true }) selected = false; /** - * Alternate text for closing the tip. + * Accessible name for the component's close button. */ @Prop() intlClose?: string; @@ -82,7 +84,7 @@ export class Tip implements ConditionalSlotComponent { // -------------------------------------------------------------------------- /** - * Emitted when the component has been dismissed. + * Emits when the component has been dismissed. */ @Event({ cancelable: false }) calciteTipDismiss: EventEmitter;