From a4f1fc572d5df8404f58742f58632b36f871207f Mon Sep 17 00:00:00 2001 From: Westbrook Johnson Date: Thu, 1 Oct 2020 00:11:29 -0400 Subject: [PATCH] docs(menu): split the various elements into individual docs pages --- packages/dropdown/README.md | 66 +++++++++++++++++++++++ packages/menu/README.md | 12 ++--- packages/menu/menu-group.md | 54 +++++++++++++++++++ packages/menu/menu-item.md | 101 ++++++++++++++++++++++++++++++++++++ 4 files changed, 227 insertions(+), 6 deletions(-) create mode 100644 packages/menu/menu-group.md create mode 100644 packages/menu/menu-item.md diff --git a/packages/dropdown/README.md b/packages/dropdown/README.md index afe6112a3e..fdc6abb6d1 100644 --- a/packages/dropdown/README.md +++ b/packages/dropdown/README.md @@ -87,6 +87,72 @@ import { Dropdown } from '@spectrum-web-components/dropdown'; ``` +### Value + +When the `value` of an `` matches the `value` attribute or the trimmed `textContent` (or `itemText`) of a descendent `` element, it will make that element as `selected`. + +### Matching `value` + +```html + + + + Deselect + + + Select inverse + + + Feather... + + + Select and mask... + + + + Save selection + + + Make work path + + + +``` + +### Matching `itemText` + +```html + + + + Deselect + + + Select inverse + + + Feather... + + + Select and mask... + + + + Save selection + + + Make work path + + + +``` + ## States ### Invalid diff --git a/packages/menu/README.md b/packages/menu/README.md index 54a5ec3111..473af24891 100644 --- a/packages/menu/README.md +++ b/packages/menu/README.md @@ -60,22 +60,22 @@ import { ```html - + Deselect - + Select inverse - + Feather... - + Select and mask... - + Save selection - + Make work path diff --git a/packages/menu/menu-group.md b/packages/menu/menu-group.md new file mode 100644 index 0000000000..b9a110dcd5 --- /dev/null +++ b/packages/menu/menu-group.md @@ -0,0 +1,54 @@ +## Overview + +An `` will gather a collection of `` elements into a group as part of the content delivered in an `` element. + +### Usage + +[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/menu?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/menu) +[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/menu?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/menu) + +``` +yarn add @spectrum-web-components/menu +``` + +Import the side effectful registration of `` as follows: + +``` +import '@spectrum-web-components/menu/sp-menu-group.js'; +``` + +When looking to leverage the `MenuGroup` base class as a type and/or for extension purposes, do so via: + +``` +import { MenuGroup } from '@spectrum-web-components/menu'; +``` + +## Example + +An `` can be used to organize ``s in an `` in to collections with a shared header. Use an element addressed to the `slot="header` to pass the content of that header. + + +```html + + + + New York + + Central Park + + + Prospect Park + + + + San Fransisco + + Golden Gate Park + + + Lake Merced Park + + + + +``` diff --git a/packages/menu/menu-item.md b/packages/menu/menu-item.md new file mode 100644 index 0000000000..1faaa3c566 --- /dev/null +++ b/packages/menu/menu-item.md @@ -0,0 +1,101 @@ +## Overview + +For use within an `` element, an `` represents a single item in a menu. + +### Usage + +[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/menu?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/menu) +[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/menu?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/menu) + +``` +yarn add @spectrum-web-components/menu +``` + +Import the side effectful registration of `` as follows: + +``` +import '@spectrum-web-components/menu/sp-menu-item.js'; +``` + +When looking to leverage the `MenuItem` base class as a type and/or for extension purposes, do so via: + +``` +import { MenuItem } from '@spectrum-web-components/menu'; +``` + +## Example + +Menus are a collection of ``s that can be modified via a `disabled` or `selected` attribute to represent an item in that state. + +```html + + + Active Menu Item + + + Disabled Menu Item + + + Selected Menu Item + + +``` + +### Value + +When displayed as a descendent of an element that manages selection (e.g. ``, ``, ``, etc.), an `` will represent the "selected" value of that ancestor when its `value` attribute or the trimmed `textContent` (represeted by `el.itemText`) matches the `value` of the ancestor element. + +In the following example, the selected `` represents a `value` of `Text that is really long and useful to a visitor, but not exactly good to use in your application or component state.` for the ancestor element. + +```html + + + + Text that is really long and useful to a visitor, but not exactly + good to use in your application or component state. + + Not selected + + + + + Menu items examples + + + Text that is really long and useful to a visitor, but not exactly + good to use in your application or component state. + + Not selected + + +``` + +When the `value` attribute is leveraged, the selected `` represents a `value` of `short-key` for the `` element. + +```html + + Menu items examples + + Not selected + + Text that is really long and useful to a visitor, but not exactly + good to use in your application or component state. + + + + + Menu items examples + + Not selected + + Text that is really long and useful to a visitor, but not exactly + good to use in your application or component state. + + + +```