@stackbit/annotations/README.md

Stackbit annotations utils

# Stackbit Annotations

This package includes several utilities to work with Stackbit [annotations](https://docs.stackbit.com/reference/annotations/) in React. 

Stackbit annotations enable on-page editing experience for your site. Click [here](https://www.stackbit.com/) to learn more about Stackbit.

## Install

```shell
npm install @stackbit/annotations
```

## Usage

```jsx
import * as React from 'react';
import { toObjectId, toFieldPath } from '@stackbit/annotations';

export function MyComponent(props) {
  return (
    <div {...toObjectId(props.id)}>
       <h1 {...toFieldPath('title')}>{props.title}</h1>
       <img src={props.image} {...toFieldPath('image#@src')} />
       {props.link && (
         <a href={props.link.url} {...toFieldPath('link.url#@href', 'link.text')}>
           {props.link.text}
         </a>
       )}
    </div>
  );
}
```

Output:

```html
<div data-sb-object-id="...">
   <h1 data-sb-field-path="title">...</h1>
   <img src="..." data-sb-field-path="image#@src" />
   <a href="..." data-sb-field-path="link.url#@href link.text">...</a>
</div>
```

When `NODE_ENV` is set to `production`, `toObjectIds` and `toFieldPath` will return empty objects, effectively removing any Stackbit annotations.

## Utilities

### `toObjectId`

Takes a string and returns an object with that string inside the `data-sb-object-id` property. When `NODE_ENV` is set to `production`, this function returns an empty object.

```javascript
toObjectId('xyz');
// result: { 'data-sb-object-id': 'xyz' }
```

### `toFieldPath`

Takes field-path and returns an object with all field-paths concatenated into the `data-sb-field-path` property. Each field-path can be a string or a `FieldPathDescriptor`. When `NODE_ENV` is set to `production`, this function returns an empty object.

```javascript
toFieldPath('title', { objectId: 'xyz', fieldPath: 'url', xpath: '@href' });
// result: { 'data-sb-field-path': 'title xyz:url#@href' }
```

### `getObjectId`

Takes an object and returns the value of the `data-sb-object-id` property if it exists, otherwise returns undefined.

```javascript
getObjectId({ 'data-sb-object-id': 'xyz' });
// result: 'xyz'
```

### `getFieldPath`

Takes an object and returns the value of the `data-sb-field-path` property if it exists, otherwise returns undefined.

```javascript
getFieldPath({ 'data-sb-field-path': 'title' });
// result: 'title'
```

### `pickDataAttrs`

Takes an object and returns a new object with only the properties that start with `data-`

```javascript
getFieldPath({
    foo: 'bar',
    bar: 'foo',
    'data-sb-object-id': 'xyz',
    'data-sb-field-path': 'title'
});
// result:
// {
//   'data-sb-object-id': 'xyz',
//   'data-sb-field-path': 'title'
// }
```