docs: align 't' components with style guide

[DintaMel]

Related Issue: #12833

Summary

Audited the following components for consistency with the Style Guide:

• tab-nav
• tab-title
• table-row
• table
• tabs
• text-area
• tile-group
• tile
• time-picker
• tooltip
• tree-item

[geospatialem]

✨📚 ✨

Few follow-ups and one proposed change is dependent on some of our internal discussions.

There may be additional considerations with some of the following:

• tab-nav.tsx, tab-title.tsx, table.tsx, table-cell.tsx, text-area.tsx, time-picker.tsx - messageOverrides property
• tab-nav.scss - there is an extra space after iconStart, in --calcite-tab-text-color
• time-picker.tsx - the step and value have content in parenthesis, they may be okay as-is, maybe a closer look to confirm? 👀

[geospatialem]

While testing the component, since we only allow for one selected tab-title, maybe this description should be left as-is for readability purposes:

Specifies the component's accent color when selected or active.

cc @matgalla for 👀

[DintaMel]

@geospatialem can you help me understand why the number we allow to be selected changes things?

I also think my changes are consistent with guidance Matt mentioned in my PR for S components to use the format "When [prop] or [state], stuff happens..."

[geospatialem]

can you help me understand why the number we allow to be selected changes things?

Matt's comment came in after mine did yesterday, so my comment is outdated based on the more recent conversations.

While testing the component, since we only allow for one selected tab-title, maybe this description should be left as-is for readability purposes:

Specifies the component's accent color when selected or active.

cc @matgalla for 👀

The reason for the comment above is the selected property can only be applied to one tab-title. Since the majority of use cases rely on a user activating the tab-title rather than programmatically setting it, I was wondering if we should call out the property name (with backticks), but flexible on either language as long as we have alignment with @matgalla.

[matgalla]

I think you raise a good point @geospatialem! True, users probably won't be setting the selected tab often, but there may also be an expectation of the prop name in backticks since we've established that format elsewhere. If it wasn't the same prop name I'd be in agreement, but I'm leaning towards the wording consistency with stepper at first glance here

[matgalla]

More food for thought - something like chip/chip-group might act as a gray area in between both cases here. chip-group can have selection-mode=single|multiple and --calcite-chip-select-icon-color-press is used to specify the color of the selected elements for both. Would we expect users to apply selected props to chips more or less often based on these options?

The current wording for chip's prop description is a bit unique by necessity, but I'm assuming it will be a part of #12833 as well. I'm tempted to say we just always lead with "When selected, " but is that awkward saying "selected" twice in the chip prop description?

When selected, specifies the component's selection element icon color.

Orrr maybe this is another example of a component where users wouldn't often specify an initial selected chip? 🤔

[matgalla]

One more thought for now - do we need "or active" in prop descriptions that are scoped to selected props? Do they both need to be mentioned or could we remove it?

[geospatialem]

This still is a bit hard to read through, will let others post considerations for readability. cc @Esri/calcite-pes

One copyedit with the "," character at the trailing end:

Suggested change

	* @prop --calcite-table-selection-cell-icon-color-selected: Specifies the icon color of the component's `selectionMode` selection icon for `selected` `calcite-table-row`s,.
	* @prop --calcite-table-selection-cell-icon-color-selected: Specifies the icon color of the component's `selectionMode` selection icon for `selected` `calcite-table-row`s.

[DintaMel]

I think the "selectionMode selection icon" part is particularly difficult to read. Maybe we don't need to use the property in this case. The verbiage for selectionMode doesn't mention the selection icons, so I don't think it's a helpful addition.

Suggested change

	* @prop --calcite-table-selection-cell-icon-color-selected: Specifies the icon color of the component's `selectionMode` selection icon for `selected` `calcite-table-row`s,.
	* @prop --calcite-table-selection-cell-icon-color-selected: Specifies the icon color of the component's selection icon on `selected` `calcite-table-row`s.

I prefer the above, but if we wanted to keep selectionMode maybe this would be better.

Suggested change

	* @prop --calcite-table-selection-cell-icon-color-selected: Specifies the icon color of the component's `selectionMode` selection icon for `selected` `calcite-table-row`s,.
	* @prop --calcite-table-selection-cell-icon-color-selected: On `selected` `calcite-table-row`s, specifies the icon color of the component's selection icon that is associated with the component's `selectionMode`.

[geospatialem]

I prefer the above, but if we wanted to keep selectionMode maybe this would be better.

+1 for the above example 🚀

• @prop --calcite-table-selection-cell-icon-color-selected: Specifies the icon color of the component's selection icon on selected calcite-table-rows.

[DintaMel]

@geospatialem can you clarify if you're wanting the one with selectionMode or without?

[geospatialem]

@geospatialem can you clarify if you're wanting the one with selectionMode or without?

Updated this comment, am referring to the first instance without selectionMode.

[DintaMel]

As I was making this change I noticed that many of the table tokens needed additional clarification on when they were applicable. For this one I prepended "When selectionMode is "multiple" or "single"," because it is not applicable when selectionMode is "none".

When selectionMode is "multiple" or "single", specifies the icon color of the component's selection icon on selected calcite-table-rows.