# kv-editor

> a reusable element for editing small lists of items

Latest version **4.0.0** (published 2017-02-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install kv-editor
pnpm add kv-editor
yarn add kv-editor
bun add kv-editor
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2017-02-05 |
| First published | 2017-02-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 15 |
| Author | sethvincent |
| Maintainers | sethvincent |

## Links

- npm: https://www.npmjs.com/package/kv-editor
- Repository: https://github.com/editdata/kv-editor
- Homepage: https://github.com/editdata/kv-editor#readme
- Issues: https://github.com/editdata/kv-editor/issues
- npm.io page: https://npm.io/package/kv-editor

## Dependencies (5)

- [bel](https://npm.io/package/bel.md) ^4.5.1
- [dom-css](https://npm.io/package/dom-css.md) ^2.1.0
- [isarray](https://npm.io/package/isarray.md) ^2.0.1
- [is-object](https://npm.io/package/is-object.md) ^1.0.1
- [object-array-converter](https://npm.io/package/object-array-converter.md) ^1.0.0

## Recent versions

- 4.0.0 (latest) — 2017-02-05

## README

# kv-editor

A reusable UI element for editing lists of key/value data.

[![npm][npm-image]][npm-url]
[![travis][travis-image]][travis-url]
[![standard][standard-image]][standard-url]
[![conduct][conduct]][conduct-url]

[npm-image]: https://img.shields.io/npm/v/kv-editor.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/kv-editor
[travis-image]: https://img.shields.io/travis/sethvincent/kv-editor.svg?style=flat-square
[travis-url]: https://travis-ci.org/sethvincent/kv-editor
[standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square
[standard-url]: http://npm.im/standard
[conduct]: https://img.shields.io/badge/code%20of%20conduct-contributor%20covenant-green.svg?style=flat-square
[conduct-url]: CONDUCT.md

## About

The goal of kv-editor is to make it easy to add an editable list of key/value pairs or just values to a page.

This editor only works with arrays or flat objects. No objects with nested properties will work.

## Install

```sh
npm install --save kv-editor
```

## Usage

Here's a basic example:

```js
var keyValueEditor = require('kv-editor')
var kvEditor = keyValueEditor()

var params = {
  items: ['a', 'b', 'c'],
  onAdd: function (data) {
    console.log(data.key, data.value)
  },
  onChange: function (data) {
    console.log(data.key, data.previousKey, data.value)
  },
  onRemove: function (data) {
    console.log(data.key)
  }
}

var tree = kvEditor(params)
document.body.appendChild(tree)
```

### Adding to the DOM

You can use `document.body.appendChild()` to add the return value of `kvEditor` to the DOM like in the above example.

You might also want to use this component inside other HTML. Here's an example of using `kvEditor()` with [bel](https://github.com/shama/bel):

```js
var html = require('bel')
var keyValueEditor = require('kv-editor')
var kvEditor = keyValueEditor()

var params = {
  items: {
    a: 1,
    b: 2,
    c: 3
  },
  onAdd: function (data) {
    console.log(data.key, data.value)
  },
  onChange: function (data) {
    console.log(data.key, data.previousKey, data.value)
  },
  onRemove: function (data) {
    console.log(data.key)
  }
}

function render (params) {
  return html`<div class="list-wrapper">
    ${kvEditor(params)}
  </div>`
}

var tree = render(params)
document.body.appendChild(tree)
```

### Using state management helpers

For every event handler in kv-editor, there is a corresponding state management helper in the `kv-editor/helpers.js` file that simplifies manipulating state. If you have unusual needs these helpers may not work for you. Otherwise, the helpers can be a great starting point for setting up state management for this component.

Each helper takes the items object or array, and the data object sent with the corresponding action.

### `var helpers = require('kv-editor/helpers')`

#### `helpers.add(items, data)`
Returns `items` array or object with added item.

#### `helpers.remove(items, data)`
Returns `items` array or object with item removed.

#### `helpers.change(items, data)`
Returns `items` array or object with modified item key & value

## Examples

### Array of items
For an example of usage with an array of items, see [examples/array.js](examples/array.js).

### Flat object of key/value pairs
For an example of usage with a flat object, see [examples/object.js](examples/object.js).


## Documentation
- [Getting started](docs/getting-started.md)
- [Related modules](docs/related-modules.md)
- [API](docs/api.md)
- [Tests](tests/)

### Examples
- [Basic example](examples/basic-usage.js)

## Contributing

Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.

## Conduct

It's important that this project contributes to a friendly, safe, and welcoming environment for all, particularly for folks that are historically underrepresented in technology. Read this project's [code of conduct](CONDUCT.md)

## Change log

Read about the changes to this project in [CHANGELOG.md](CHANGELOG.md). The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).

## Contact

- **chat** – You can chat about this project at [http://gitter.im/sethvincent/ask](http://gitter.im/sethvincent/ask)
- **issues** – Please open issues in the [issues queue](https://github.com/sethvincent/kv-editor/issues)
- **twitter** – [@sethdvincent](https://twitter.com/sethdvincent)
- **email** – Need in-depth support via paid contract? Send an email to sethvincent@gmail.com

## License

[ISC](LICENSE.md)

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