# @netology-group/wc-user-list

> `user-list` web component

Latest version **0.8.0** (published 2022-04-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install @netology-group/wc-user-list
pnpm add @netology-group/wc-user-list
yarn add @netology-group/wc-user-list
bun add @netology-group/wc-user-list
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.8.0 |
| Published | 2022-04-20 |
| First published | 2018-12-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 131.6 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| Author | Aleksey Konstantinov |
| Maintainers | opensource-netology-group, aenesterov, alexkonst, dkvovik, flyer3d |

## Links

- npm: https://www.npmjs.com/package/@netology-group/wc-user-list
- npm.io page: https://npm.io/package/@netology-group/wc-user-list

## Dependencies (5)

- [lodash](https://npm.io/package/lodash.md) ~4.17.10
- [lit-html](https://npm.io/package/lit-html.md) ~0.10.2
- [@polymer/lit-element](https://npm.io/package/@polymer/lit-element.md) ~0.5.2
- [@netology-group/wc-utils](https://npm.io/package/@netology-group/wc-utils.md) ^0.3.2
- [@webcomponents/webcomponentsjs](https://npm.io/package/@webcomponents/webcomponentsjs.md) ~2.0.2

## Recent versions

- 0.8.0 (latest) — 2022-04-20
- 0.8.0-dev.0 (dev) — 2022-04-11
- 0.4.2 (beta) — 2021-03-10
- 0.7.4 — 2021-12-23
- 0.7.4-dev.1 — 2021-12-20
- 0.7.4-dev.0 — 2021-12-20
- 0.7.3 — 2021-06-25
- 0.7.2 — 2021-06-07
- 0.7.1 — 2021-06-07
- 0.7.0 — 2021-05-31
- 0.6.0 — 2021-05-28
- 0.5.1 — 2021-05-19
- 0.5.1-dev.0 — 2021-05-17
- 0.5.0 — 2021-04-27
- 0.4.3 — 2021-03-19
- … 8 more at https://npm.io/package/@netology-group/wc-user-list/versions

## README

# <user-list>

[![downloads](https://img.shields.io/npm/dm/@netology-group/wc-user-list)](https://www.npmjs.com/package/@netology-group/wc-user-list)

`user-list` is an element for displaying a list of users with their avatars and online statuses that provides useful filtering, sorting and grouping options.

## Installation

```
npm install --save netology-group/wc-user-list
```

## Example

HTML:
```html
<user-list
  id="list1"
  me="3"
  melead
  canblock
  withfilter
  sortby="online:desc,name:asc,blocked:desc"
  groupby="role"
></user-list>
```

You need to pass array of users for list:

```js
var userList1 = document.getElementById('list1')

userList1.users = [
  {
    id: 1,
    name: 'Calhoun Beer',
    avatar: 'https://robohash.org/nihilveritatisfugit.png?size=64x64&set=set1',
    online: false,
    role: 'user',
    blocked: false
  },
  {
    id: 2,
    name: 'Oneida Ivimey',
    avatar: 'https://robohash.org/quisetofficia.png?size=64x64&set=set1',
    online: false,
    role: 'user',
    blocked: true
  },
  {
    id: 3,
    name: 'Sheila MacCombe',
    avatar: 'https://robohash.org/consequaturnihildolores.png?size=64x64&set=set1',
    online: false,
    role: 'user',
    blocked: true
  }
]
```

## Using in project

To start using `user-list` you need to add next line in your project root.

```js
import '@netology-group/wc-user-list/dist/user-list'
```

Also you need to add `webcomponents-bundle` polyfill and `custom-elements-es5-adapter` (see [webcomponentsjs](https://github.com/webcomponents/webcomponentsjs)).

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/2.0.2/webcomponents-bundle.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/2.0.2/custom-elements-es5-adapter.js"></script>
```

## Build

You may want to build your own custom `user-list`-like element. Here's how:

```js
import {
  UserList,
  withStyles,
  withFilter,
  withSort,
  withGroup
} from '@netology-group/wc-user-list'

// custom styles
const css = `...`
// custom map of strings for grouping
const withGroupConfig = {
  mapping: {
    admin: 'Admins',
    moderator: 'Moderators',
    presenter: 'Presenters',
    user: 'Users'
  }
}

window.customElements.define('custom-user-list', withGroup(withSort(withFilter(withStyles(UserList, css))), withGroupConfig))
```

## Demo
```bash
npm start
```

## User object

Example:

```
{
  id: 1,
  name: 'Calhoun Beer',
  avatar: 'https://robohash.org/nihilveritatisfugit.png?size=64x64&set=set1',
  online: false,
  role: 'user',
  blocked: false
}
```

| Property | Type | Required |
| --- | --- | --- |
| `id` | Number | yes |
| `name` | String | yes |
| `avatar` | String | yes |
| `online` | Boolean | no |
| `blocked` | Boolean | yes |


## API

### Attributes and properties:

| Name | Kind | Type | Description |
| --- | --- | --- | --- |
| `users` | `property` | `Array` | Array of users |
| `me` | `attribute` | `Number` | Highlight user with specified `id` |
| `melead` | `attribute` | `Boolean` | Show highlighted user on top of list |
| `canblock` | `attribute` | `Boolean` | When set, "lock" action is available |
| `withfilter` | `attribute` | `Boolean` | Show input field for filtering users by name |
| `sortby` | `attribute` | `String` | Allows to sort users in list by one or many properties with ordering |
| `groupby` | `attribute` | `String` | Allows to group users by value of specified key in [user object](#user-object) |

`sortby` format:
- attribute not set - without sorting
- `sortby="online,name,blocked"` - sort by key `online`, then by key `name` and finally by key `blocked` (default order is `desc`)
- `sortby="online,name:asc,blocked"` - sort by key `online`, then by key `name` with order `asc` and finally by key `blocked`

### Events:

| Name | Example | Description |
| --- | --- | --- |
| `toggle-user-lock` | `{detail: {id: 2}}` | Dispatched when user click on "lock" icon. `id` - id of user to witch the "lock" action was applied |

---
_Source: https://npm.io/package/@netology-group/wc-user-list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._