ci: add markdownlint config file and generate/lint component docs (#7887

) **Related Issue:** #7662 ## Summary - Add project markdownlint config - Set rules for project consistency (versus the default file consistency) - Generate component READMEs - Lint markdown files and fix some issues manually
Esri · Sep 28, 2023 · d20b36c · d20b36c
1 parent 45b2803
commit d20b36c
Show file tree

Hide file tree

Showing 92 changed files with 1,689 additions and 929 deletions.
diff --git a/.lintstagedrc.json b/.lintstagedrc.json
@@ -3,5 +3,5 @@
   "*.scss": ["stylelint --fix", "prettier --write"],
   "packages/**/*.{ts,tsx}": ["eslint --ext .ts,.tsx --fix", "prettier --write"],
   ".github/scripts/*.js": ["eslint --ext .js", "prettier --write"],
-  "*.md": ["markdownlint --fix --disable MD024 MD013 MD041 MD033", "prettier --write"]
+  "*.md": ["markdownlint --fix", "prettier --write"]
 }
diff --git a/.markdownlintrc b/.markdownlintrc
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
+  "first-line-heading": false,
+  "no-inline-html": false,
+  "line-length": false,
+  "code-block-style": { "style": "fenced" },
+  "code-fence-style": { "style": "backtick" },
+  "heading-style": { "style": "atx" },
+  "no-duplicate-heading": { "siblings_only": true },
+  "emphasis-style": { "style": "underscore" },
+  "strong-style": { "style": "underscore" },
+  "ul-style": { "style": "dash" }
+}
diff --git a/packages/calcite-components/.gitignore b/packages/calcite-components/.gitignore
@@ -3,4 +3,5 @@ docs/
 hydrate/
 *.js
 src/components/icon/assets
+node_modules
 www/
diff --git a/packages/calcite-components/conventions/Accessibility/AccessibilityDesign.md b/packages/calcite-components/conventions/Accessibility/AccessibilityDesign.md
@@ -1,12 +1,53 @@
 # Design Quick Start Guide
 
-1. **[Color](#1-color)**: [Color contrast](#color-contrast) | [Color and state](#color--state)
-2. **[Typography](#2-typography)**: [Text styling](#text-styling) | [Text resizing](#text-resizing)
-3. **[Information hierarchy](#3-information-hierarchy)**: [Semantic structure](#semantic-structure) | [Headings](#headings) | [Links](#links) | [Navigation](#navigation) | [Focus order](#focus-order)
-4. **[Forms](#4-forms)**: [Labels](#labels) | [Grouping controls](#grouping-controls) | [Form fields](#form-fields) | [Buttons and disabled buttons](#buttons) | [User notifications](#user-notifications) | [Touch zones](#touch-zones)
-5. **[Images](#5-images)**: [Background images](#background-images) | [Icons](#icons)
-6. **[Animation](#6-animation)**
-7. **[Writing and labels](#7-writing-and-labels)**: [Error messaging](#error-messaging)
+<details>
+    <summary>Table of Contents</summary>
+
+- [Design Quick Start Guide](#design-quick-start-guide)
+  - [1. Color](#1-color)
+    - [Color contrast](#color-contrast)
+    - [Color and state](#color-and-state)
+    - [Who does color help?](#who-does-color-help)
+    - [Color resources](#color-resources)
+    - [WCAG Success Criteria for Color](#wcag-success-criteria-for-color)
+  - [2. Typography](#2-typography)
+    - [Text styling](#text-styling)
+    - [Text resizing](#text-resizing)
+    - [Who does typography help?](#who-does-typography-help)
+    - [Typography resources](#typography-resources)
+  - [3. Information hierarchy](#3-information-hierarchy)
+    - [Semantic structure](#semantic-structure)
+    - [Headings](#headings)
+    - [Links](#links)
+    - [Navigation](#navigation)
+    - [Focus order](#focus-order)
+    - [Who does information hierarchy help?](#who-does-information-hierarchy-help)
+    - [Information hierarchy resources](#information-hierarchy-resources)
+    - [WCAG Success Criteria for Information hierarchy](#wcag-success-criteria-for-information-hierarchy)
+  - [4. Forms](#4-forms)
+    - [Labels](#labels)
+    - [Grouping controls](#grouping-controls)
+    - [Form fields](#form-fields)
+    - [Buttons](#buttons)
+      - [Disabled buttons](#disabled-buttons)
+    - [User notifications](#user-notifications)
+    - [Touch zones](#touch-zones)
+    - [Who does form accessibility help?](#who-does-form-accessibility-help)
+    - [WCAG Success Criteria for Forms](#wcag-success-criteria-for-forms)
+  - [5. Images](#5-images)
+    - [Background images](#background-images)
+    - [Icons](#icons)
+    - [Who does image accessibility help?](#who-does-image-accessibility-help)
+    - [WCAG Success Criteria for Images](#wcag-success-criteria-for-images)
+  - [6. Animation](#6-animation)
+    - [Who does animation help?](#who-does-animation-help)
+    - [WCAG Success Criteria for Animation](#wcag-success-criteria-for-animation)
+  - [7. Writing and labels](#7-writing-and-labels)
+    - [Error messaging](#error-messaging)
+    - [Who does writing and labels help?](#who-does-writing-and-labels-help)
+    - [WCAG Success Criteria for Writing and labels](#wcag-success-criteria-for-writing-and-labels)
+
+</details>
 
 ## 1. Color
 
@@ -18,7 +59,7 @@ Large text equates 18pt or 14pt bold and greater. Regular sized text is anything
 
 > Note: Windows also provides a high contrast mode that is designed to improve text legibility and readability. It is often used by people with low-vision. High contrast mode will force a preset color palette on the browsing experience, but it also disables background images.
 
-### Color & state
+### Color and state
 
 When designing components, it is important to use a combination of color, shapes, and text to indicate states and statuses, such as keyboard focus, form validation, and alerts. Using these other elements provides a secondary indicator in the event a color cannot be seen.
 

diff --git a/packages/calcite-components/conventions/Accessibility/AccessibilityDeveloper.md b/packages/calcite-components/conventions/Accessibility/AccessibilityDeveloper.md
@@ -1,8 +1,18 @@
 # Developer Quick Start Guide
 
-1. **[Shadow DOM](#1-shadow-dom)**
-2. **[Tests](#2-tests)**: [Adding a test](#adding-a-test) | [Failed test example](#failed-test-example) | [How to test](#how-to-test)
-3. **[Storybook](#3-storybook)**: [Adding a new story](#adding-a-new-story)
+<details>
+    <summary>Table of Contents</summary>
+
+- [Developer Quick Start Guide](#developer-quick-start-guide)
+  - [1. Shadow DOM](#1-shadow-dom)
+  - [2. Tests](#2-tests)
+    - [Adding a test](#adding-a-test)
+      - [Failed test example](#failed-test-example)
+    - [How to test](#how-to-test)
+  - [3. Storybook](#3-storybook)
+    - [Adding a new story](#adding-a-new-story)
+
+</details>
 
 ## 1. Shadow DOM
 

diff --git a/packages/calcite-components/conventions/Accessibility/AccessibilityRoles.md b/packages/calcite-components/conventions/Accessibility/AccessibilityRoles.md
@@ -1,17 +1,51 @@
 # Roles
 
-1. [Widget Roles](#1-widget-roles)
-2. [Abstract Roles](#2-abstract-roles)
-3. [Composite Roles](#3-composite-roles)
-   - i. [combobox](#i-combobox)
-   - ii. [grid](#ii-grid)
-   - iii. [listbox](#iii-listbox)
-   - iv. [menu](#iv-menu)
-   - v. [menubar](#v-menubar)
-   - vi. [radiogroup](#vi-radiogroup)
-   - vii. [tablist](#vii-tablist)
-   - viii. [tree](#viii-tree)
-   - ix. [treegrid](#ix-treegrid)
+<details>
+    <summary>Table of Contents</summary>
+
+- [Roles](#roles)
+  - [1. Widget Roles](#1-widget-roles)
+  - [2. Abstract Roles](#2-abstract-roles)
+  - [3. Composite Roles](#3-composite-roles)
+    - [i. combobox](#i-combobox)
+      - [Combobox example](#combobox-example)
+      - [Combobox code](#combobox-code)
+      - [Keyboard functionality for Combobox](#keyboard-functionality-for-combobox)
+    - [ii. grid](#ii-grid)
+      - [Grid Example](#grid-example)
+      - [Grid Code](#grid-code)
+      - [Keyboard functionality for Grid](#keyboard-functionality-for-grid)
+    - [iii. listbox](#iii-listbox)
+      - [Listbox Example](#listbox-example)
+      - [Listbox Code](#listbox-code)
+      - [Keyboard functionality for Listbox](#keyboard-functionality-for-listbox)
+    - [iv. menu](#iv-menu)
+      - [Menu Example](#menu-example)
+      - [Menu Code](#menu-code)
+      - [Keyboard functionality for Menu](#keyboard-functionality-for-menu)
+    - [v. menubar](#v-menubar)
+      - [Menubar Example](#menubar-example)
+      - [Menubar Code](#menubar-code)
+      - [Keyboard functionality for Menubar](#keyboard-functionality-for-menubar)
+    - [vi. radiogroup](#vi-radiogroup)
+      - [Radiogroup Example](#radiogroup-example)
+      - [a. Radiogroup Code](#a-radiogroup-code)
+      - [b. Radiogroup Code in Semantic HTML](#b-radiogroup-code-in-semantic-html)
+      - [Keyboard functionality for Radiogroup](#keyboard-functionality-for-radiogroup)
+    - [vii. tablist](#vii-tablist)
+      - [Tablist Example](#tablist-example)
+      - [Tablist Code](#tablist-code)
+      - [Keyboard functionality for Tablist](#keyboard-functionality-for-tablist)
+    - [viii. tree](#viii-tree)
+      - [Tree Example](#tree-example)
+      - [Tree Code](#tree-code)
+      - [Keyboard functionality for Tree](#keyboard-functionality-for-tree)
+    - [ix. treegrid](#ix-treegrid)
+      - [Treegrid Example](#treegrid-example)
+        - [Treegrid Code](#treegrid-code)
+      - [Keyboard functionality for Treegrid](#keyboard-functionality-for-treegrid)
+
+</details>
 
 ## 1. Widget Roles
 

diff --git a/packages/calcite-components/conventions/README.md b/packages/calcite-components/conventions/README.md
@@ -79,7 +79,7 @@ Only attach additional data to your event if that data cannot be determined from
 
 `<calcite-tab-nav>` is also an example of this. The `event.details.tab` item contains the index of the selected tab or the tab name which cannot be easily determined from the state of `<calcite-tab-nav>` in some cases so it makes sense to include in the event.
 
-### Native event cancelation
+### Native event cancellation
 
 When a component **handles events for its own interaction** (e.g., moving between list items, closing an open menu), if the event is tied to default browser behavior (e.g., space key scrolling the page), `Event.preventDefault()` must be called to avoid mixed behavior.
 
@@ -421,22 +421,22 @@ For such cases, the following pattern will enable developers to create custom ch
 - Must provide a `customItemSelectors` property to allow querying for custom elements in addition to their expected children.
 - An interface for the class (used by custom item classes) and element (used by parent component APIs) must be created in the parent's `interfaces.d.ts` file, where the necessary child APIs must be extracted.
 
-**Example**
+##### Example
 
-**`parent/interfaces.d.ts`**
+###### `parent/interfaces.d.ts`
 
 ```ts
 type ChildComponentLike = Pick<Components.CalciteChild, "required" | "props" | "from" | "parent">;
 type ChildComponentLikeElement = ChilcComponentLike & HTMLElement;
 ```
 
-**`parent/parent.tsx`**
+###### `parent/parent.tsx`
 
 ```tsx
   @Prop() selectedItem: HTMLChildComponentElement | ChildComponentLikeElement;
 ```
 
-**`custom-item/custom-item.tsx`**
+###### `custom-item/custom-item.tsx`
 
 ```tsx
 export class CustomItem implements ChildComponentLike {

diff --git a/packages/calcite-components/package.json b/packages/calcite-components/package.json
@@ -31,7 +31,7 @@
     "lint": "concurrently npm:lint:*",
     "lint:html": "prettier --write \"**/*.html\" >/dev/null",
     "lint:json": "prettier --write \"**/*.json\" >/dev/null",
-    "lint:md": "markdownlint \"**/*.md\" --fix --ignore node_modules --disable MD024 MD013 MD041 MD033 && prettier --write \"**/*.md\" >/dev/null",
+    "lint:md": "markdownlint \"**/*.md\" --fix --dot --ignore-path .gitignore && prettier --write \"**/*.md\" >/dev/null",
     "lint:scss": "stylelint --fix \"src/**/*.scss\" && prettier --write \"**/*.scss\" >/dev/null",
     "lint:ts": "eslint --ext .ts,.tsx --fix . && prettier --write \"**/*.ts?(x)\" >/dev/null",
     "posttest": "npm run test:prerender",

diff --git a/packages/calcite-components/src/components/accordion-item/readme.md b/packages/calcite-components/src/components/accordion-item/readme.md
@@ -17,9 +17,11 @@ A child component of `calcite-accordion`, where some behavior is inherited from
 
 ## Slots
 
-| Slot | Description                                                                   |
-| ---- | ----------------------------------------------------------------------------- |
-|      | A slot for adding custom content, including nested `calcite-accordion-item`s. |
+| Slot              | Description                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+|                   | A slot for adding custom content, including nested `calcite-accordion-item`s.               |
+| `"actions-end"`   | A slot for adding `calcite-action`s or content to the end side of the component's header.   |
+| `"actions-start"` | A slot for adding `calcite-action`s or content to the start side of the component's header. |
 
 ## Dependencies
 

diff --git a/packages/calcite-components/src/components/action-bar/readme.md b/packages/calcite-components/src/components/action-bar/readme.md
@@ -8,25 +8,25 @@ The `calcite-action-bar` component is made up of multiple `calcite-action`s in t
 
 ## Usage
 
-### Basic
+### Actions-end
 
-Renders `calcite-action`s that stick to the top of the bar.
+The actions-end slot renders `calcite-action`s that stick to the end of the bar prior to the expand/collapse icon.
 
 ```html
 <calcite-action-bar>
-  <calcite-action text="Add" icon="plus"></calcite-action>
-  <calcite-action text="Save" icon="save"></calcite-action>
+  <calcite-action text="Information" icon="information"></calcite-action>
+  <calcite-action text="Feedback" slot="actions-end" icon="mega-phone"></calcite-action>
 </calcite-action-bar>
 ```
 
-### Actions-end
+### Basic
 
-The actions-end slot renders `calcite-action`s that stick to the end of the bar prior to the expand/collapse icon.
+Renders `calcite-action`s that stick to the top of the bar.
 
 ```html
 <calcite-action-bar>
-  <calcite-action text="Information" icon="information"></calcite-action>
-  <calcite-action text="Feedback" slot="actions-end" icon="mega-phone"></calcite-action>
+  <calcite-action text="Add" icon="plus"></calcite-action>
+  <calcite-action text="Save" icon="save"></calcite-action>
 </calcite-action-bar>
 ```
 
@@ -47,12 +47,12 @@ Renders a group of `calcite-action`s contained in a `calcite-action-group`. Acti
 
 ```html
 <calcite-action-bar>
-  <calcite-action-group>
+  <calcite-action-group label="Manage item">
     <calcite-action text="Add" icon="plus"></calcite-action>
     <calcite-action text="Save" icon="save"></calcite-action>
   </calcite-action-group>
 
-  <calcite-action-group>
+  <calcite-action-group label="Item types">
     <calcite-action text="Layers" icon="layers"></calcite-action>
     <calcite-action text="Basemaps" icon="layer-basemap"></calcite-action>
   </calcite-action-group>
@@ -61,15 +61,16 @@ Renders a group of `calcite-action`s contained in a `calcite-action-group`. Acti
 
 ## Properties
 
-| Property                  | Attribute                   | Description                                                                     | Type                         | Default      |
-| ------------------------- | --------------------------- | ------------------------------------------------------------------------------- | ---------------------------- | ------------ |
-| `expandDisabled`          | `expand-disabled`           | When `true`, the expand-toggling behavior is disabled.                          | `boolean`                    | `false`      |
-| `expanded`                | `expanded`                  | When `true`, the component is expanded.                                         | `boolean`                    | `false`      |
-| `layout`                  | `layout`                    | The layout direction of the actions.                                            | `"horizontal" \| "vertical"` | `"vertical"` |
-| `messageOverrides`        | `message-overrides`         | Use this property to override individual strings used by the component.         | `ActionBarMessages`          | `undefined`  |
-| `overflowActionsDisabled` | `overflow-actions-disabled` | Disables automatically overflowing `calcite-action`s that won't fit into menus. | `boolean`                    | `false`      |
-| `position`                | `position`                  | Arranges the component depending on the element's `dir` property.               | `"end" \| "start"`           | `undefined`  |
-| `scale`                   | `scale`                     | Specifies the size of the expand `calcite-action`.                              | `"l" \| "m" \| "s"`          | `undefined`  |
+| Property                  | Attribute                   | Description                                                                     | Type                                      | Default      |
+| ------------------------- | --------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- | ------------ |
+| `actionsEndGroupLabel`    | `actions-end-group-label`   | Specifies the accessible label for the last action-group.                       | `string`                                  | `undefined`  |
+| `expandDisabled`          | `expand-disabled`           | When `true`, the expand-toggling behavior is disabled.                          | `boolean`                                 | `false`      |
+| `expanded`                | `expanded`                  | When `true`, the component is expanded.                                         | `boolean`                                 | `false`      |
+| `layout`                  | `layout`                    | The layout direction of the actions.                                            | `"horizontal" \| "vertical"`              | `"vertical"` |
+| `messageOverrides`        | --                          | Use this property to override individual strings used by the component.         | `{ expand?: string; collapse?: string; }` | `undefined`  |
+| `overflowActionsDisabled` | `overflow-actions-disabled` | Disables automatically overflowing `calcite-action`s that won't fit into menus. | `boolean`                                 | `false`      |
+| `position`                | `position`                  | Arranges the component depending on the element's `dir` property.               | `"end" \| "start"`                        | `undefined`  |
+| `scale`                   | `scale`                     | Specifies the size of the expand `calcite-action`.                              | `"l" \| "m" \| "s"`                       | `undefined`  |
 
 ## Events
 
@@ -89,11 +90,12 @@ Type: `Promise<void>`
 
 ## Slots
 
-| Slot               | Description                                                                                                            |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-|                    | A slot for adding `calcite-action`s that will appear at the top of the component.                                      |
-| `"actions-end"`    | A slot for adding `calcite-action`s that will appear at the bottom of the component, above the collapse/expand button. |
-| `"expand-tooltip"` | A slot to set the `calcite-tooltip` for the expand toggle.                                                             |
+| Slot               | Description                                                                                                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|                    | A slot for adding `calcite-action`s that will appear at the top of the component.                                                                                         |
+| `"actions-end"`    | A slot for adding `calcite-action`s that will appear at the end of the component, prior to the collapse/expand button.                                                    |
+| `"bottom-actions"` | [Deprecated] Use the `"actions-end"` slot instead. A slot for adding `calcite-action`s that will appear at the bottom of the component, above the collapse/expand button. |
+| `"expand-tooltip"` | A slot to set the `calcite-tooltip` for the expand toggle.                                                                                                                |
 
 ## CSS Custom Properties