Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Define style guide and proof read component API reference #4442

Closed
83 tasks done
benelan opened this issue Apr 22, 2022 · 17 comments
Closed
83 tasks done

Define style guide and proof read component API reference #4442

benelan opened this issue Apr 22, 2022 · 17 comments
Assignees
@benelan
Labels
3 - installed Issues that have been merged to master branch and are ready for final confirmation. Calcite (dev) Issues logged by Calcite developers. docs Issues relating to documentation updates only.
Milestone
2023 January Prio...

Comments

@benelan
Copy link
Member

benelan commented Apr 22, 2022 •
edited
Loading

Current Style Guide

So far we have the following conventions for API ref descriptions:

  • Use complete sentences with proper grammar, capitalization, and punctuation.
  • No abbreviations, e.g. use "property" instead of "prop".
  • Verbs must be in present tense.
  • When referring to the component that the property/slot/method/css variable belongs to, call it "the component".
  • Use the full tag name when referencing other Calcite Components (prefix with calcite-), e.g. calcite-button instead of button.
  • For plural context, use calcite-buttons instead of calcite-button elements.
  • Use backticks (`) for the names of slots, events, properties, CSS variables, and component names.
  • Use double quotes (") for the values of properties/attributes and event details.
  • Only use single quotes (') as apostrophes.
  • No links or URLs allowed in descriptions. If a link is necessary, a custom JSDoc tag should be added and parsed in the SDK site.
  • Refrain from using "e.g." or "i.e." references. Leverage "such as" (or similar) where examples are referenced.
  • Use "Accessible" instead of "Aria" language
  • Verify slots don't use the text "optional" in their descriptions
  • Remove optional JSDoc tags for props (?)

Common slots

  • header - A slot for adding header text.
  • content - A slot for adding the component's content.

Events

  • For click events, use descriptors such as "Fires", as opposed to "Emits", in line with MDN mousedown and mouseup events.
    • For example: "Fires when the back button has been clicked."

Common properties

  • active - When true, the component is active.
  • appearance - Specifies the appearance style of the component.
  • checked - When true, the component is checked.
  • disabled - When true, interaction is prevented and the component is displayed with lower opacity.
  • dismissible - When true, a close button is added to the component.
  • flipPlacements - Defines the available placements that can be used when a flip occurs.
  • groupSeparator - When true, number values are displayed with the locale's group separator.
  • heading - The component header text.
  • headingLevel - Specifies the number at which section headings should start.
  • height - Specifies the height of the component.
  • icon - Specifies an icon to display.
    • iconStart - Specifies an icon to display at the start of the component.
    • iconEnd - Specifies an icon to display at the end of the component.
    • iconPosition - When used with "icon", specifies its position.
    • flipRtl / iconFlipRtl - When true, the icon will be flipped when the element direction is right-to-left ("rtl").
  • label / intlLabel / textLabel (repeated below) - Accessible name for the component.
    • intlClose / dismissLabel - Accessible name for the component's close button.
    • intlCollapse - Accessible name for the component's collapse button.
    • intlExpand -Accessible name for the component's expand button.
    • intlLoading - Accessible name when the component is loading.
    • intlOptions -Accessible name for the component's options button.
    • intlClear - Accessible name for the component's clear button.
  • layout - Defines the layout of the component.
  • loading - When true, a busy indicator is displayed.
  • locale - Specifies the BCP 47 language tag for the desired language and country format.
  • name - Specifies the name of the component on form submission.
  • open - When true, displays and positions the component.
  • placement
  • referenceElement - The referenceElement used to position the component according to its "placement" value. Setting to an HTMLElement is preferred so the component does not need to query the DOM. However, a string id of the reference element can also be used.
  • required - When true, the component must have a value in order for the form to submit.
  • scale - Specifies the size of the component.
  • selected - When true, the component is selected.
  • text / textLabel (repeated above)
  • value - The component's value.
  • width - Specifies the width of the component.

Original Issue Description

Our property/slot/method descriptions are all over the place right now. We need to decide on some conventions, and then audit and proofread to make sure they are consistent. Some things to consider:

  • Should they be sentences with proper case/punctuation/grammar, or should they be more like bullet points?
  • Which verb tense should we use?
  • Which quotation marks should be used (single vs double vs tick) in the descriptions? Should different quotation marks be used for different purposes (calcite-xyz vs "value")? e.g. disableCloseOnSelect uses double and overlayPositioning uses single
  • How should components be named when mentioned in the description? Should they be the full tag name? Should they be in quotes? - here here here here
  • Should links be allowed in the description? If so, how should they be formatted? e.g. indeterminate, download, value

In addition to the consistency conventions, there is a lot of clean up that needs to happen. For example,

  • The description does not need to mention the default, since it is specified in the table - here
    • This also applies to documentation that is linked out, and contains many properties.
  • The description does not need to specify that it is read-only, since it displays a chip based on a jsdoc tag here
  • Product names should be capitalized, e.g. "Calcite UI Icons" vs this

This is not an exhaustive list, but it is a start. If anyone else has something to add please feel free. @geospatialem and I will decide on and document the conventions, and then start updating the jsdoc.

cc @macandcheese and @jcfranco if you have any preferences on the conventions.

Which Component

All components

Progress checklist (all done!)
  • accordion (Ben)
  • accordion-item (Ben)
  • action (Ben)
  • action-bar (Ben)
  • action-group (Ben)
  • action-menu (Ben)
  • action-pad (Ben)
  • alert (Ben)
  • avatar (Ben)
  • block (Kitty)
  • block-section (Kitty)
  • button (Kitty)
  • card (Kitty)
  • checkbox (Kitty)
  • chip (Kitty)
  • color-picker (Kitty)
  • combobox (Kitty)
  • combobox-item (Kitty)
  • combobox-item-group (Kitty)
  • date-picker (Kitty)
  • dropdown (Kitty)
  • dropdown-group (Kitty)
  • dropdown-item (Kitty)
  • fab (Kitty)
  • filter (Kitty)
  • flow (Kitty)
  • flow-item (Kitty)
  • icon (Kitty)
  • inline-editable (Kitty)
  • input (Kitty)
  • input-date-picker (Kitty)
  • input-message (Kitty)
  • input-time-picker (Kitty)
  • label (Kitty)
  • link (Kitty)
  • list (Kitty)
  • list-item (Kitty)
  • list-item-group (Kitty)
  • loader (Kitty)
  • modal (Kitty)
  • notice (Kitty)
  • option (Kitty)
  • option-group (Kitty)
  • pagination (Kitty)
  • panel (Kitty)
  • pick-list (Kitty)
  • pick-list-group (Kitty)
  • pick-list-item (Kitty)
  • popover (Kitty)
  • popover-manager (Kitty) deprecated
  • progress (Kitty)
  • radio-button (Kitty)
  • radio-button-group (Kitty)
  • radio-group (Kitty)
  • radio-group-item (Kitty)
  • rating (Kitty)
  • scrim (Kitty)
  • select (Kitty)
  • shell (Kitty)
  • shell-center-row (Kitty)
  • shell-panel (Kitty)
  • slider (Kitty)
  • split-button (Kitty)
  • stepper (Kitty)
  • stepper-item (Kitty)
  • switch (Kitty)
  • tab (Kitty)
  • tab-nav (Kitty)
  • tab-title (Kitty)
  • tabs (Kitty)
  • tile (Kitty)
  • tile-select (Kitty)
  • tile-select-group (Kitty)
  • time-picker (Kitty)
  • tip (Kitty)
  • tip-group (Kitty)
  • tip-manager (Kitty)
  • tooltip (Kitty)
  • tooltip-manager (Kitty) deprecated
  • tree (Kitty)
  • tree-item (Kitty)
  • value-list (Kitty)
  • value-list-item (Kitty)
@benelan benelan added docs Issues relating to documentation updates only. 0 - new New issues that need assignment. needs triage Planning workflow - pending design/dev review. labels Apr 22, 2022
@benelan benelan added this to the Back burner milestone Apr 22, 2022
@benelan benelan added 1 - assigned Issues that are assigned to a sprint and a team member. and removed 0 - new New issues that need assignment. needs triage Planning workflow - pending design/dev review. labels Apr 22, 2022
@macandcheese
Copy link
Contributor

macandcheese commented Apr 22, 2022 •
edited
Loading

Thanks for putting this together!

I have no preference on content structure or verbiage as long as it is consistent, and anything that can be turned into metadata items, is - like in the examples you mention above for read-only, and default values.

This was referenced May 2, 2022
Merged
Merged
@geospatialem geospatialem mentioned this issue May 12, 2022
Merged
@driskull
Copy link
Member

Did we discuss back-ticks? I see single and double quotes mentioned.

We use these to highlight code in descriptions. It's nice to see them highlighted in markdown.

@geospatialem
Copy link
Member

We did have some inclusions with the component names above.

  • Components should not be in quotes, e.g. calcite-button instead of calcite-button (ticks do not render as inline code in the doc)

So they would be recognized as calcite-list-item over `calcite-list-item` or "calcite-list-item".

The back-ticks were recommended for removal since they don't register in the docs. For instance on the list item doc page.

screenshot of calcite-list-item with back-ticks in current dogs

@driskull
Copy link
Member

Makes perfect sense. thanks for clarifying!

@benelan
Copy link
Member Author

benelan commented May 12, 2022

Kitty beat me to it. @macandcheese is there any way you can highlight backticks in the doc? If so then I agree using backticks would be nice

@driskull
Copy link
Member

I'm wondering if the docs could just find/replace all backticks? Maybe use them to apply their own highlighting.

@benelan
Copy link
Member Author

benelan commented May 12, 2022

Looks possible to me. Maybe we could switch backticks with code tags. But I'll defer to @macandcheese on this.

@benelan
Copy link
Member Author

benelan commented May 12, 2022

If it is possible, should we switch from only " to only backticks? Or Use both depending on the situation, e.g. " for property values and backticks for property names and calcite-component tags?

@geospatialem
Copy link
Member

If it is possible, should we switch from only " to only backticks? Or Use both depending on the situation, e.g. " for property values and backticks for property names and calcite-component tags?

So far I've only seen one instance of need for the double quotes (""), and it was related to a deprecation.

With the rarity (granted it's rare so far), leaning towards all refs using back-ticks (``) if supported.

@macandcheese
Copy link
Contributor

That would be a good identifier for us to place inside a code block on the docs site.

@macandcheese
Copy link
Contributor

In the future we could think about allowing markdown and parsing it on the documentation site side

@benelan
Copy link
Member Author

benelan commented May 12, 2022

We could do it pretty easily with this https://github.com/remarkjs/react-markdown

@geospatialem geospatialem mentioned this issue May 13, 2022
Merged
This was referenced May 27, 2022
Merged
Merged
@benelan benelan mentioned this issue Jun 3, 2022
Merged
@geospatialem geospatialem mentioned this issue Jun 6, 2022
Merged
@benelan benelan mentioned this issue Jun 10, 2022
Merged
@geospatialem geospatialem mentioned this issue Aug 26, 2022
Merged
geospatialem added a commit that referenced this issue Aug 29, 2022
@geospatialem
docs: incorporate the api reference style guide in some t-named compo…
4d24fe3 
…nents (#5230)

**Related Issue:** #4442

## Summary
Adds consistency to our API documentation within some of the t-named
components, including:
- tab
- tab-nav
- tab-title
- tabs
- tile
- tile-select
- tile-select-group
- time-picker
- tip
- tip-group
- tip-manager

<!--

Please make sure the PR title and/or commit message adheres to the
https://www.conventionalcommits.org/en/v1.0.0/ specification.

Note: If your PR only has one commit and it is NOT semantic, you will
need to either

a. add another commit and wait for the check to update
b. proceed to squash merge, but make sure the commit message is the same
as the title.

This is because of the way GitHub handles single-commit squash merges
(see zeke/semantic-pull-requests#17)

If this is component-related, please verify that:

- [ ] feature or fix has a corresponding test
- [ ] changes have been tested with demo page in Edge

---

If this is skipping an unstable test:

- include info about the test failure
- submit an unstable-test issue by
[choosing](https://github.com/Esri/calcite-components/issues/new/choose)
the unstable test template and filling it out

-->
@geospatialem geospatialem mentioned this issue Sep 9, 2022
Merged
@geospatialem geospatialem mentioned this issue Sep 20, 2022
Merged
This was referenced Oct 14, 2022
Merged
Merged
@geospatialem geospatialem mentioned this issue Nov 28, 2022
Merged
geospatialem added a commit that referenced this issue Nov 30, 2022
@geospatialem
docs: consistent api reference throughout components (#5821)
db43d9c 
**Related Issue:** #4442

## Summary
1. Includes consistency across API references, this PR finalizes the
style guide across all components.

2. Also includes the removal of the optional "`?`" JSDoc tags for the
components listed below.
    - A separate PR will be created for the remaining components.

### Components included:
- ` date-picker`
- `dropdown`
- `dropdown-group`
- `dropdown-item`
- `fab`
- `filter`
- `flow`
-  `flow-item`
- `icon`
- `inline-editable`

<!--

Please make sure the PR title and/or commit message adheres to the
https://www.conventionalcommits.org/en/v1.0.0/ specification.

Note: If your PR only has one commit and it is NOT semantic, you will
need to either

a. add another commit and wait for the check to update
b. proceed to squash merge, but make sure the commit message is the same
as the title.

This is because of the way GitHub handles single-commit squash merges
(see zeke/semantic-pull-requests#17)

If this is component-related, please verify that:

- [ ] feature or fix has a corresponding test
- [ ] changes have been tested with demo page in Edge

---

If this is skipping an unstable test:

- include info about the test failure
- submit an unstable-test issue by
[choosing](https://github.com/Esri/calcite-components/issues/new/choose)
the unstable test template and filling it out

-->
@geospatialem geospatialem mentioned this issue Nov 30, 2022
Merged
geospatialem added a commit that referenced this issue Dec 6, 2022
@geospatialem
docs: remove jsdoc optional props across components (#5857)
92501d3 
**Related Issue:** #4442

## Summary
1. Removes JSDoc optional props (`?`) across components
2. Small doc changes to:
    - `accordion`
    -  `alert` slots
    - `list` refactor props
        - `list`, 
        - `list-item`, and 
        - `list-item-group` 

Once merged, will close out the API style guide issue above.
@geospatialem geospatialem added 3 - installed Issues that have been merged to master branch and are ready for final confirmation. and removed 1 - assigned Issues that are assigned to a sprint and a team member. labels Dec 6, 2022
@github-actions
Copy link
Contributor

github-actions bot commented Dec 6, 2022

Installed and assigned for verification.

@geospatialem geospatialem assigned benelan and unassigned geospatialem Dec 6, 2022
@geospatialem
Copy link
Member

@benelan Could you verify this issue related to our API style guide across components?

@benelan
Copy link
Member Author

benelan commented Dec 9, 2022 •
edited
Loading

Sure! I'm putting another checklist here that I'll use as I go through the component docs

Verification progress
  • accordion
  • accordion-item
  • action
  • action-bar
  • action-group
  • action-menu
  • action-pad
  • alert
  • avatar
  • block
  • block-section
  • button
  • card
  • checkbox
  • chip
  • color-picker
  • combobox
  • combobox-item
  • combobox-item-group
  • date-picker
  • dropdown
  • dropdown-group
  • dropdown-item
  • fab
  • filter
  • flow
  • flow-item
  • icon
  • inline-editable
  • input
  • input-date-picker
  • input-message
  • input-time-picker
  • label
  • link
  • list
  • list-item
  • list-item-group
  • loader
  • modal
  • notice
  • option
  • option-group
  • pagination
  • panel
  • pick-list
  • pick-list-group
  • pick-list-item
  • popover
  • popover-manager deprecated
  • progress
  • radio-button
  • radio-button-group
  • radio-group
  • radio-group-item
  • rating
  • scrim
  • select
  • shell
  • shell-center-row
  • shell-panel
  • slider
  • split-button
  • stepper
  • stepper-item
  • switch
  • tab
  • tab-nav
  • tab-title
  • tabs
  • tile
  • tile-select
  • tile-select-group
  • time-picker
  • tip
  • tip-group
  • tip-manager
  • tooltip
  • tooltip-manager deprecated
  • tree
  • tree-item
  • value-list
  • value-list-item

@benelan benelan added the Calcite (dev) Issues logged by Calcite developers. label Jan 30, 2023
@geospatialem geospatialem self-assigned this Feb 14, 2023
@geospatialem geospatialem mentioned this issue May 31, 2023
Closed
@geospatialem geospatialem removed their assignment May 31, 2023
@geospatialem
Copy link
Member

Closing in favor of #7071.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@benelan benelan

Labels
3 - installed Issues that have been merged to master branch and are ready for final confirmation. Calcite (dev) Issues logged by Calcite developers. docs Issues relating to documentation updates only.
Projects
None yet
Milestone
2023 January Priorities
Development

No branches or pull requests
5 participants
@driskull @alisonailea @macandcheese @geospatialem @benelan