# @planningcenter/add-ons

This package allows Planning Center apps to build hooks, called UI Extensions,
to extend their UI. These UI Extensions are utilized by Planning Center add-ons
(integrator apps) to enhance a Planning Center product with their own functionality.

## Usage in Planning Center Products

To make Add-ons available in a Planning Center product, you'll need a few things:

1.  Install this package:

    ```sh
    yarn add @planningcenter/add-ons
    ```

2.  Create a UI Extension "Insertion Point" and add it to the list of valid
    Insertion Points [here](https://github.com/planningcenter/api/blob/main/app/models/ui_extension.rb#L11).
    (You'll have to make a Pull Request.)

    ```ruby
    INSERTION_POINTS = %w[
      people.profile.custom_tab
      people.profile.info_section
    ].freeze
    ```

    Insertion points follow the format: `PRODUCT_NAME.GENERAL_MODULE.SPECIFIC_PLACE`

    Though there is no validation for the name, try to follow the format. :-)

3.  Import add-ons styles

    ```jsx
    import "@planningcenter/add-ons/dist/styles.css"
    ```

4.  Insert a React component in your product view to render the UI Extensions for
    the new Insertion Point:

    ```jsx
    import React from "react"
    import {
      UiExtensionDataContext,
      UiExtensionItems,
    } from "@planningcenter/add-ons"

    export default function profileTabs({ personId, openTab }) {
      return (
        <UiExtensionDataContext>
          <UiExtensionItems name="people.profile.custom_tab">
            {({ id, iconUrl, title }) => (
              <li key={id}>
                <div onClick={openTab}>
                  <img className="symbol" src={iconUrl} />
                  {title}
                </div>
              </li>
            )}
          </UiExtensionItems>
        </UiExtensionDataContext>
      )
    }
    ```

    How you render the UI Extension here is completely up to you; no third
    party code runs here.

5.  Add another React component that renders the Add-on third-party content
    once it is triggered by your product:

    ```jsx
    import React from "react"

    import {
      UiExtensionDataContext,
      UiExtensionThirdPartyComponent,
    } from "@planningcenter/add-ons"

    export default function ProfileTabContent({ extensionId }) {
      return (
        <UiExtensionDataContext currentExtensionId={extensionId}>
          <UiExtensionThirdPartyComponent />
        </UiExtensionDataContext>
      )
    }
    ```

## Usage by Add-ons

This library takes care of rendering third-party React components, i.e. UI Extensions, in
the remote-ui sandbox. There is a bit of boilerplate that every UI Extension will need to
use to cooperate with the rendering process. Here is an example UI Extension component:

```jsx
// people.profile.custom_tab.jsx

import React, { useEffect, useState } from "react"
import { render } from "@remote-ui/react"

const Text = "Text"

function App() {
  return <Text>Hello world</Text>
}

self.onRender((root, args) => {
  render(<App {...args} />, root, () => root.mount())
})
```

This boilerplate _should_ be generated by [add-ons-cli](https://github.com/planningcenter/add-ons-cli).

### Arguments

Each UI Extension component get passed arguments, including any callbacks, from the
host application. These arguments can be used to give the component additional needed
context to do its job (remember that the sandboxed component runs in a Web Worker
and has no access to the host environment).

On the host:

```jsx
<UiExtensionThirdPartyComponent
  extensionId={extensionId}
  args={{
    hostOnClick: () => console.log("callback on host"),
  }}
/>
```

In the Add-on:

```jsx
function App({ hostOnClick }) {
  return (
    <>
      <Button onClick={() => hostOnClick()} text="click me" />
    </>
  )
}
```

### authenticatedFetch

A special function is made available on `self` inside the Add-on: `authentictedFetch`.
The function can be used to make authenticated API calls to the **Planning Center** API, e.g.:

```jsx
function App() {
  const [person, setPerson] = useState("")

  useEffect(async () => {
    if (!person.attributes) {
      authenticatedFetch("/people/v2/me")
        .then(({ data }) => {
          setPerson(data.attributes.first_name)
        })
        .catch((err) => {
          console.error(err)
          setPerson("error fetching person")
        })
    }
  }, [authenticatedFetch])

  return (
    <>
      <Text>person: {person}</Text>
    </>
  )
}
```

### authenticatedIntegratorFetch

Another special function is made available on `self` inside the add-on: `authentictedIntegratorFetch`.
The function can be used to make authenticated API calls to the Integrator's (the add-on author's) API, e.g.:

```jsx
authenticatedIntegratorFetch("https://api.example.com/some/endpoint")
  .then(({ data }) => {
    // do something with response data
  })
  .catch((err) => {
    console.error(err)
  })
}
```

## Development

In this directory:

```sh
yarn global add yalc
yarn run build
yalc publish
```

In the consuming product directory:

```sh
yalc add @planningcenter/add-ons
```

### Automatically Updating Components

To shorten the feedback cycle when testing components in a product, you can use the following command (requires [entr](http://eradman.com/entrproject/), which can be installed with brew or apt):

```sh
APP=people
find src -type f | entr -c -s "yarn run build && yalc publish && cd ../$APP && yalc update"
```

### Putting Things Back

Depending on the product, it can be hard to undo what Yalc has done. The following one-liner seems to work in all cases:

```sh
# in the product directory
git checkout package.json; rm -rf node_modules; rm -rf .yalc; rm -f yalc.lock; rm -rf tmp/cache; rm -rf public/packs; yarn
```

## Storybook

Running Storybook locally:

```sh
yarn storybook
```

Deploying Storybook to Github Pages:

```sh
yarn storybook:deploy
```

## Production

To publish a new release:

1. Ensure `yarn build` succeeds.
2. Update the CHANGELOG.
3. Update the version in `package.json`. See [versioning guidelines](https://www.notion.so/planningcenter/Package-handling-at-Planning-Center-aka-How-we-npm-b1c78de88e124f7ca41955e0b082f55f?pvs=4#9bc8c7658fcf4db586e1e43549ebb61a).
4. Create a new tagged release using `pco make-github-release`.

To publish a pre-release:

1. Check out the `next` branch and do a `git reset --hard {your-branch}`.
2. Update the version in `package.json` with a version like `1.4.0-rc.1`.
3. Add that same version heading to the top of the changelog and commit those changes (on the `next` branch).
4. Force push the branch to GitHub: `git push -f` 
5. Run `pco make-github-release --prerelease --target next`