Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/greatislander/pressbooks-multiselect
https://github.com/greatislander/pressbooks-multiselect
Last synced: 7 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/greatislander/pressbooks-multiselect
- Owner: greatislander
- License: mit
- Created: 2022-12-23T17:16:57.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-01T12:03:39.000Z (8 months ago)
- Last Synced: 2024-11-18T22:06:49.865Z (2 months ago)
- Language: JavaScript
- Size: 1.98 MB
- Stars: 1
- Watchers: 3
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# \
[](https://npmjs.com/package/@pressbooks/multiselect) [](https://github.com/greatislander/pressbooks-multiselect/tree/main/LICENSE)
A web component which enhances the native `` element, built with [Lit](https://lit.dev). This web
component follows the [open-wc](https://github.com/open-wc/open-wc) recommendations.
It owes a great debt to [prior work](https://github.com/microsoft/sonder-ui/tree/master/src/components/multiselect) and
[research](https://www.24a11y.com/2019/select-your-poison-part-2/) by Sarah Higley.
## Installation
```bash
npm i @pressbooks/multiselect
```
## Usage
Wrap a `` element with the `multiple` attribute and a semantically valid label in the
`` tag.
```html
import '@pressbooks/multiselect/pressbooks-multiselect.js';
Multiple Selections
Option 1
```
If you wrap a single select or a select element without a valid label, the component will not render and your existing
markup will be displayed without modification.
If the `` element has a relationship with a hint via the `aria-describedby` attribute, the hint will be attached
to the rendered component as well. If you'd like the hint to appear after the rendered component, add the `slot="after"`
attribute to it:
```html
Multiple Selections
Option 1
Pick some!
```
If you group options within the `` using [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup)
elements, the multiselect will group options using the [ARIA grouped listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-grouped/).
### Styling
Because this web component uses the Shadow Dom, styling is limited to modification via CSS custom properties. However,
[there are plenty to choose from](https://github.com/greatislander/pressbooks-multiselect/blob/a87fab1f7b3ea967b3ae6b58400ed863084326ee/src/PressbooksMultiselect.js#L4-L146).
## Linting and formatting
To scan the project for linting and formatting errors, run
```bash
npm run lint
```
To automatically fix linting and formatting errors, run
```bash
npm run format
```
## Testing with Web Test Runner
To execute a single test run:
```bash
npm run test
```
To run the tests in interactive watch mode run:
```bash
npm run test:watch
```
## Demoing with Storybook
To run a local instance of Storybook for your component, run
```bash
npm run storybook
```
To build a production version of Storybook, run
```bash
npm run storybook:build
```
## Tooling configs
For most of the tools, the configuration is in the `package.json` to minimize the amount of files in your project.
If you customize the configuration a lot, you can consider moving them to individual files.
## Local Demo with `web-dev-server`
```bash
npm start
```
To run a local development server that serves the basic demo located in `demo/index.html`
## Publishing to NPM
As this is a scoped package it must be published by someone within the Pressbooks NPM organization and must use the `--access public` flag:
```bash
npm publish --access public
```