@magnit-ce/collection-browser

v0.0.2

Published

a month ago

A custom html element that provides a selection gallery as a dialog, to mimic an os-native file browser.

Downloads

0High
0Medium
0Low

catapart

custom element html browser file gallery option choose

magnitce-collection-browser

A custom HTMLElement that provides a selection gallery to mimic an os-native file browser.

Package size: ~8kb minified, ~13kb verbose.

Quick Reference

<collection-browser>
    <h2 slot="navigation-header">Categories</h2>
    <div slot="category" data-category="1">Category 1</div>
    <div slot="category" data-category="2">Category 2</div>
    <div data-category="1">A</div>
    <div data-category="1">B</div>
    <div data-category="1">C</div>
    <div data-category="2">D</div>
    <div data-category="2">E</div>
    <div data-category="2">F</div>
</collection-browser>
<script type="module" src="/path/to/collection-browser[.min].js"></script>

Demos

https://catapart.github.io/magnitce-collection-browser/demo/

Support

Firefox
Chrome
Edge
Safari (Has not been tested; should be supported, based on custom element support)

Getting Started

Install/Reference the library

Reference/Install

HTML Import (not required for vanilla js/ts; alternative to import statement)

<script type="module" src="/path/to/collection-browser[.min].js"></script>

npm

npm install @magnit-ce/collection-browser

Import

Vanilla js/ts

import "/path/to/collection-browser[.min].js"; // if you didn't reference from a <script>, reference with an import like this

import { CollectionBrowserElement } from "/path/to/collection-browser[.min].js";

npm

import "@magnit-ce/collection-browser"; // if you didn't reference from a <script>, reference with an import like this

import { CollectionBrowserElement } from "@magnit-ce/collection-browser";

Overview

The <collection-browser> element is a container element for any arbitrary child elements that will display them as a gallery of selectable items.

It consists of a gallery of items and a navigation pane for including elements that can be used to filter the gallery items, with headers for each - the gallery and the navigation.

The element uses the shadowDOM both for its styling scope, to manage its internal layout, and for its slotting functionality, to place items and navigation categories appropriately.

It also provides simple item filtering using the category elements, as well as events for custom handling of all of its management.

Events

The <collection-browser> element dispatches the following three events:

change: fires when an item is selected. Provides data about the current selected item, as well as the previously selected items.
category: fires when a category is selected. Provides data about the current selected category, as well as the previously selected category.
add: fires when the "Add Item" button is clicked.

By default, when a change event, or a category event is dispatched, the <collection-browser> element will apply styles and filtering to the items. Both of these functions can be prevented on each event by handling the event and calling the preventDefault() function on th Event parameter.

Selection is managed by a selected class which is added or removed from items depending upon their selected state. The actual class name can be customized by setting the static selectedClassName property on the element.

Default filtering functionality consists of adding or removing a has-category class depending upon whether an item can be matched (see Attributes) to the selected category.

Attributes

The <collection-browser> element uses the multi attribute (alternative: multiple) to determine if only a single item can be selected, or if multiple items can be selected. If the multi attribute is present, all items may be selected at the same time. If the multi attribute is not present, each selection event will deselect all previously selected items.

`data-category` data attribute

Simple filtering can be achieved with the <collection-browser> by using the data-category attribute as a key to match each item with an element that fills the category slot. In the simplest example, this means adding a data-category attribute with a specific value to a category element, and then adding a data-category attribute with that same value to an item element:

<collection-browser>
    <div slot="category" data-category="1">Category 1</div>
    <div slot="category" data-category="2">Category 2</div>
    <div slot="category" data-category="3">Category 3</div>
    <div slot="category" data-category="4">Category 4</div>
    <div data-category="1">A</div>
    <div data-category="1">B</div>
    <div data-category="1">C</div>
    <div data-category="2">D</div>
    <div data-category="2">E</div>
    <div data-category="2">F</div>
    <div data-category="3">G</div>
    <div data-category="3">H</div>
    <div data-category="3">I</div>
    <div data-category="4">J</div>
    <div data-category="4">K</div>
    <div data-category="4">L</div>
</collection-browser>

Items may be linked to multiple category elements by providing each of the category keys as a comma-separated list as the value for the item's data-category attribute. In this example, the "J", "K", and "L" elements would get the has-category class if either of their provided categories were selected:

<collection-browser>
    <div slot="category" data-category="1">Category 1</div>
    <div slot="category" data-category="2">Category 2</div>
    <div slot="category" data-category="3">Category 3</div>
    <div slot="category" data-category="4">Category 4</div>
    <div data-category="1">A</div>
    <div data-category="1">B</div>
    <div data-category="1">C</div>
    <div data-category="2">D</div>
    <div data-category="2">E</div>
    <div data-category="2">F</div>
    <div data-category="3">G</div>
    <div data-category="3">H</div>
    <div data-category="3">I</div>
    <div data-category="1,4">J</div>
    <div data-category="2,4">K</div>
    <div data-category="3,4">L</div>
</collection-browser>

Slots

The <collection-browser> element exposes the following slots: |Slot Name|Description|Default |-|-|-| |[Default]|Slot that holds all of the <collection-browser>'s items.(note: this slot has no name; all children of the <collection-browser> element that do not have an assigned slot attribute will be placed in this default slot.)|[empty]| |category|A category that is related to the items and can be used for populating or filtering the items. Multiple elements can use the category slot at the same time for a list of categories.|[empty]| |navigation-header|A header for the navigation pane. Can be used to describe the collection of categories.|HTMLHeaderElement[part="navigation-header"]| |navigation-header-content|Content to be rendered inside the header for the list of categories.|[empty]| |header|A header for the browser's items.|HTMLHeaderElement[part="header"]| |header-content|Content to be rendered inside the header for the browser's items. For convenience, this slot does not include the "Add Item" button, despite the button being rendered in the header element.|[empty]| |add-button|A button that dispatches an event to indicate a new item should be added to the <collection-browser> element.|[HTMLButtonElement[part="add-button"]]| |add-button-content|Content to be rendered inside of the "Add Item" button. Replaces the add-button-icon and add-button-label parts.|[HTMLSpanElement[part="add-button-icon"],HTMLSpanElement[part="add-button-label"]]|

Parts

Styling

The <collection-browser> element can be styled with CSS, normally, but it also makes use of the shadowDOM for it's layout and functionality. Each of the elements in the <collection-browser> element's shadowRoot can be selected for styling, directly, by using the ::part() selector.

In this example, the header part is being selected for styling:

collection-browser::part(header)
{
    /* styling */
}

For a list of all part names, see the parts section.

License

This library is in the public domain. You do not need permission, nor do you need to provide attribution, in order to use, modify, reproduce, publish, or sell it or any works using it or derived from it.