# be-counted

> Count events.

Latest version **0.0.21** (published 2024-09-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install be-counted
pnpm add be-counted
yarn add be-counted
bun add be-counted
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.21 |
| Published | 2024-09-28 |
| First published | 2022-09-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 14.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Bruce B Anderson |
| Maintainers | bahrus |
| Keywords | web components, web component, custom elements, custom element, built-in |

## Links

- npm: https://www.npmjs.com/package/be-counted
- Repository: https://github.com/bahrus/be-counted
- Homepage: https://github.com/bahrus/be-counted#readme
- Issues: https://github.com/bahrus/be-counted/issues
- npm.io page: https://npm.io/package/be-counted

## Dependencies (3)

- [be-hive](https://npm.io/package/be-hive.md) 0.0.221
- [be-enhanced](https://npm.io/package/be-enhanced.md) 0.0.144
- [trans-render](https://npm.io/package/trans-render.md) 0.0.843

## Alternatives

- [@progress/kendo-ooxml](https://npm.io/package/@progress/kendo-ooxml.md) — 152.1K weekly downloads
- [@progress/kendo-react-ripple](https://npm.io/package/@progress/kendo-react-ripple.md) — 8.0K weekly downloads
- [@progress/kendo-react-orgchart](https://npm.io/package/@progress/kendo-react-orgchart.md) — 4.3K weekly downloads
- [@praxisui/dynamic-fields](https://npm.io/package/@praxisui/dynamic-fields.md) — 2.4K weekly downloads
- [@progress/kendo-vue-listbox](https://npm.io/package/@progress/kendo-vue-listbox.md) — 932 weekly downloads

## Recent versions

- 0.0.21 (latest) — 2024-09-28
- 0.0.20 — 2024-09-28
- 0.0.19 — 2024-03-01
- 0.0.18 — 2024-01-08
- 0.0.17 — 2023-04-29
- 0.0.16 — 2022-12-18
- 0.0.15 — 2022-11-23
- 0.0.14 — 2022-11-14
- 0.0.13 — 2022-11-14
- 0.0.12 — 2022-11-13
- 0.0.11 — 2022-11-13
- 0.0.10 — 2022-11-13
- 0.0.9 — 2022-11-06
- 0.0.7 — 2022-10-16
- 0.0.6 — 2022-10-13
- … 6 more at https://npm.io/package/be-counted/versions

## README

# be-counted (🔢)

*be-counted* enables an HTML button (for example) to keep track of how many times it has been clicked.  

Or in twitterese - it provides a primitive signal on an island of interactivity, which reactively renders to the UI the number of times the button was clicked.

*be-counted* is one of many enhancements/decorators/behaviors based on [*be-enhanced*](https://github.com/bahrus/be-enhanced).

[![Playwright Tests](https://github.com/bahrus/be-counted/actions/workflows/CI.yml/badge.svg?branch=baseline)](https://github.com/bahrus/be-counted/actions/workflows/CI.yml)
[![NPM version](https://badge.fury.io/js/be-counted.png)](http://badge.fury.io/js/be-counted)
[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/be-counted?style=for-the-badge)](https://bundlephobia.com/result?p=be-counted)
<img src="http://img.badgesize.io/https://cdn.jsdelivr.net/npm/be-counted?compression=gzip">


## Example 1 - Counting silently 

```html
<button id=oButton be-counted>Count</button>
```


The value of the count can be obtained via (more or less):

```JavaScript
oButton.beEnhanced.beCounted.value;
oButton.beEnhanced.beCounted.addEventListener('value', e => {
    ...
})
```

"More or less" refers to needing to wait for the enhancement to load, which is a bit of a pain:

```JavaScript
await import('be-counted/behivior.js');
const beCounted = oButton.beEnhanced.whenResolved('be-counted');
console.log({value: beCounted.value});
beCounted.addEventListener('value', e => {
    // value has changed
})
```

To  alleviate that pain, be-counted has some built in mechanisms for sharing the value

## Example 2 - Sharing the value

```html
<span></span>
<button be-counted="and share value with ^{(*)}">Count</button>
```

Specifying the places to share the value with is done via [DSSArray notation](https://github.com/bahrus/trans-render/wiki/VIII.--Directed-Scoped-Specifiers-(DSS)).

## Full specification

The full [specification](https://github.com/bahrus/be-counted/blob/baseline/types.d.ts) for this enhancement is shown below:

```TypeScript
export interface EndUserProps {
    /**
     * How much to increment on each event
     */
    step?: number;
    /**
     * Don't allow count to exceed this number
     */
    ltOrEq?: number;
    /** Don't allow count to reach this number. */
    lt?: number;
    /**
     * Starting value of count, including after looping
     */
    min?: number;
    /**
     * Make count loop back to min value after hitting the ceiling set by ltOrEq or lt
     */
    loop?: boolean;

    /**
     * Slowly "awaken" a disabled element.  If the disabled attribute is not set to a number, or is set to "1", removes the disabled attribute.  If it is a larger number, decrements the number by 1. 
     */
    nudges?: boolean;
    /**
     * Event name to trigger count increment
     */
    incOn?: string;
    /**
     * Disable on max
     */
    disableOnMax?: boolean;
    /**
     * set lt = 1
     * and min = 0
     * and step = 1
     * and disableOnMax = true
     */
    once?: boolean
    
}
```

We can use this specification in one of two ways (or a combo of the two, as shown below).  JavaScriptObjectNotation, and/or attribute-based configuration

## Example 3 - Mixed Approach

```html
<span></span>
<button disabled 
    be-counted="and share value with ^{(*)}"
    be-counted-config='{"nudges": true, "min": 3, "loop": true}'
    be-counted-lt-or-eq=17
>Count</button>
```


## Example 4 - Using a shorter name

This package provides an alternative name for the rather long "be-counted", that could make it less painful to configure, especially if laying out the settings with individual attributes as opposed to JSON, especially in less formal settings, where conflicts with other libraries can be easily managed:


```html
<span></span>
<button disabled 
    🔢="and share value with ^{(*)}"
    🔢-config='{"nudges": true, "min": 3, "loop": true}'
    🔢-lt-or-eq=17
>Count</button>
```

Notice how much mental firepower it requires to [define a name to your liking](https://github.com/bahrus/be-counted/blob/baseline/%F0%9F%94%A2.js).


## Example 5 -  disable on click

One important use case for *be-counted* -- disabling a button once it's been clicked:

```html
<span></span>
<button disabled 
    🔢="and share value with ^{(*)}"
    🔢-once
>Count</button>
```

## Example 6 - share to property of adorned element

```html
<button 
    🔢="and share value with $0:dataset:count."
>Count</button>
```

## Running locally

1.  Do a git clone or a git fork of repository https://github.com/bahrus/be-committed
2.  Install node.js
3.  Run "npm install" from location of folder created in step 1.
4.  Run npm run serve.  Open browser to http://localhost:3030/demo/

## Using from ESM Module:

```JavaScript
import 'be-counted/be-counted.js';
```

## Using from CDN:

```html
<script type=module crossorigin=anonymous>
    import 'https://esm.run/be-counted';
</script>
```

---
_Source: https://npm.io/package/be-counted · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
