reakit-system/README.md

Reakit System utils

# reakit-system

<a href="https://npmjs.org/package/reakit-system"><img alt="NPM version" src="https://img.shields.io/npm/v/reakit-system.svg" /></a>

> **This is experimental** and may have breaking changes in minor versions.

## Installation

npm:

```sh
npm i reakit-system
```

Yarn:

```sh
yarn add reakit-system
```

## Usage

```jsx
import { useRole } from "reakit/Role";
import { createHook } from "reakit-system";

const useA = createHook({ name: "A", compose: useRole });
```

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

-   [createComponent](#createcomponent)
-   [createHook](#createhook)
-   [mergeSystem](#mergesystem)
-   [SystemProvider](#systemprovider)
-   [useCreateElement](#usecreateelement)
-   [useOptions](#useoptions)
-   [useProps](#useprops)
-   [useToken](#usetoken)

### createComponent

Creates a React component.

#### Parameters

-   `options` **Options&lt;T, O>** 
    -   `options.as`  
    -   `options.useHook`  
    -   `options.memo`  
    -   `options.propsAreEqual`   (optional, default `useHook?.unstable_propsAreEqual`)
    -   `options.keys`   (optional, default `useHook?.__keys||[]`)
    -   `options.useCreateElement`   (optional, default `defaultUseCreateElement`)

#### Examples

```javascript
import { createComponent } from "reakit-system";

const A = createComponent({ as: "a" });
```

### createHook

Creates a React custom hook that will return component props.

#### Parameters

-   `options` **CreateHookOptions&lt;O, P>** 

#### Examples

```javascript
import { createHook } from "reakit-system";

const useA = createHook({
  name: "A",
  keys: ["url"], // custom props/options keys
  useProps(options, htmlProps) {
    return {
      ...htmlProps,
      href: options.url,
    };
  },
});

function A({ url, ...htmlProps }) {
  const props = useA({ url }, htmlProps);
  return <a {...props} />;
}
```

### mergeSystem

Merges multiple system objects into a single system object.

#### Parameters

-   `systems` **...T** 

#### Examples

```javascript
import { Provider } from "reakit";
import { mergeSystem } from "reakit-system";
import * as bootstrapSystem from "reakit-system-bootstrap";

const mySystem = {
  useButtonProps() {},
};

const system = mergeSystem(bootstrapSystem, mySystem);

function App() {
  return (
    <Provider unstable_system={system}>
      <div>App</div>
    </Provider>
  );
}
```

### SystemProvider

Provider component that is used by `reakit`'s `Provider` underneath.

#### Parameters

-   `props` **SystemProviderProps** 
    -   `props.children`  
    -   `props.unstable_system`  

#### Examples

```javascript
// instead of using
import { Provider } from "reakit";
// you can use this
import { SystemProvider } from "reakit-system";
// reakit's Provider has more features, such as ID generation
import * as system from "reakit-system-bootstrap";

function App() {
  return (
    <SystemProvider unstable_system={system}>
      <div>App</div>
    </SystemProvider>
  );
}
```

### useCreateElement

Custom hook that will call `children` if it's a function. If
`useCreateElement` has been passed to the context, it'll be used instead.

#### Parameters

-   `type` **T** 
-   `props` **Record&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), any>** 
-   `children` **React.ReactNode**  (optional, default `props.children`)

#### Examples

```javascript
import React from "react";
import { SystemProvider, useCreateElement } from "reakit-system";

const system = {
  useCreateElement(type, props, children = props.children) {
    // very similar to what `useCreateElement` does already
    if (typeof children === "function") {
      const { children: _, ...rest } = props;
      return children(rest);
    }
    return React.createElement(type, props, children);
  },
};

function Component(props) {
  return useCreateElement("div", props);
}

function App() {
  return (
    <SystemProvider unstable_system={system}>
      <Component url="url">{({ url }) => <a href={url}>link</a>}</Component>
    </SystemProvider>
  );
}
```

Returns **JSX.Element** 

### useOptions

React custom hook that returns the options returned by a given
`use${name}Options` in the SystemContext.

#### Parameters

-   `name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `options` **T**  (optional, default `{}as T`)
-   `htmlProps` **any**  (optional, default `{}`)

#### Examples

```javascript
import React from "react";
import { SystemProvider, useOptions } from "reakit-system";

const system = {
  useAOptions(options, htmlProps) {
    return {
      ...options,
      url: htmlProps.href,
    };
  },
};

function A({ url, ...htmlProps }) {
  const options = useOptions("A", { url }, htmlProps);
  return <a href={options.url} {...htmlProps} />;
}

function App() {
  return (
    <SystemProvider unstable_system={system}>
      <A href="url">
        It will convert href into url in useAOptions and then url into href in A
      </A>
    </SystemProvider>
  );
}
```

Returns **T** 

### useProps

React custom hook that returns the props returned by a given
`use${name}Props` in the SystemContext.

#### Parameters

-   `name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `options` **Record&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), any>**  (optional, default `{}`)
-   `htmlProps` **any**  (optional, default `{}`)

#### Examples

```javascript
import { SystemProvider, useProps } from "reakit-system";

const system = {
  useAProps(options, htmlProps) {
    return {
      ...htmlProps,
      href: options.url,
    };
  },
};

function A({ url, ...htmlProps }) {
  const props = useProps("A", { url }, htmlProps);
  return <a {...props} />;
}

function App() {
  return (
    <SystemProvider unstable_system={system}>
      <A url="url">It will convert url into href in useAProps</A>
    </SystemProvider>
  );
}
```

Returns **any** 

### useToken

React custom hook that returns the value of any token defined in the
SystemContext. It's mainly used internally in [`useOptions`](#useoptions)
and [`useProps`](#useprops).

#### Parameters

-   `token` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `defaultValue` **T?** 

#### Examples

```javascript
import { SystemProvider, useToken } from "reakit-system";

const system = {
  token: "value",
};

function Component(props) {
  const token = useToken("token", "default value");
  return <div {...props}>{token}</div>;
}

function App() {
  return (
    <SystemProvider unstable_system={system}>
      <Component />
    </SystemProvider>
  );
}
```

Returns **T** 

## License

MIT © [Diego Haz](https://github.com/diegohaz)