# Installable Kit

These components can be previewed at https://storybook.vestaboard.com

## Build-time configuration (service URLs)

Host apps must inject Vestaboard service base URLs at **webpack/build time** (via `DefinePlugin`, `environment`, etc.). Values are read from `process.env` when the bundle is built—not at runtime from PHP or server `.env` unless your build step loads those into the webpack process.

### Env vars (monorepo `config/.env.*`)

| Variable                   | Used for                                                                                 |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| `PLATFORM_ENDPOINT`        | Platform REST, subscription config token, media upload, deeplinks, visual editor session |
| `MESSAGE_SERVICE_ENDPOINT` | Message service favorites (add/remove)                                                   |
| `VESTABOARD_API_ENDPOINT`  | GraphQL (share message, JWT exchange)                                                    |
| `APP_ENDPOINT`             | Web app links (e.g. board simulator)                                                     |

Run `yarn env:prod` / `yarn env:staging` (or copy the matching `config/.env.*` to root `.env`) before building so webpack sees these values in `process.env`.

Blank or whitespace-only env values are skipped (the next name in the precedence list is used).

### Backwards-compatible env aliases

| Monorepo var               | Legacy alias           |
| -------------------------- | ---------------------- |
| `PLATFORM_ENDPOINT`        | `V1_PLATFORM_ENDPOINT` |
| `MESSAGE_SERVICE_ENDPOINT` | `V2_MESSAGE_ENDPOINT`  |

Exports `PLATFORM_ENDPOINT` and `V2_MESSAGE_ENDPOINT` remain available as resolved constants for existing imports. Deeplink and API paths should use `platformHttpUrl()` / `platformWsUrl()` so trailing slashes on the base URL are handled consistently.

### Example (webpack)

Pass monorepo env vars through at build time:

```js
new webpack.DefinePlugin({
  'process.env.PLATFORM_ENDPOINT': JSON.stringify(
    process.env.PLATFORM_ENDPOINT || 'https://platform.vestaboard.com',
  ),
  'process.env.MESSAGE_SERVICE_ENDPOINT': JSON.stringify(
    process.env.MESSAGE_SERVICE_ENDPOINT ||
      'https://message-service.vestaboard.com',
  ),
  'process.env.VESTABOARD_API_ENDPOINT': JSON.stringify(
    process.env.VESTABOARD_API_ENDPOINT || 'https://api.vestaboard.com',
  ),
  'process.env.APP_ENDPOINT': JSON.stringify(
    process.env.APP_ENDPOINT || 'https://web.vestaboard.com',
  ),
})
```

## Installation

The current version of Installable kit requires these peer dependencies to be installed in your project:

```json
{
  "peerDependencies": {
    "@mui/icons-material": "^5.11.13",
    "@mui/material": "^5.11.13",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}
```

With those in place, just run:

```bash
yarn @vestaboard/installables
```

or

```bash
npm install @vestaboard/installables
```

## Available Scripts

In the project directory, you can run:

### `yarn start`

Opens storybook and allows you to view and edit the components

### `yarn test`

Runs the tests using jest

### `yarn build`

Builds the typescript files

## Releasing a new version

For a new version release, just bump the patch "version" number in package.json. This will trigger the publish job during CI, when merged into main.

ex:

```
maj.min.patch
4.0.0 => 4.0.1
```

```
git switch -c feature/my-changes
git add --all
git commit -m "changed _ components css"
git push
# make a PR to main, and the new changes will be deployed when reviewed and merged
```

PRs should be made targeting the default branch

```
feature/my-changes => main
```

## Migrating away from @mui/styles makeStyles, use MUI System or SX prop

[@mui/styles deprecation notice](https://mui.com/system/styles/api/)

```tsx
# Old ❌ installable kit < 3.0.46
import { makeStyles } from '@mui/styles';

const useStyles = makeStyles({
  button: (props) => ({
    padding: 4,
    marginLeft: 4,
    borderRadius:  6
  })
})
...
<Button className={classes.button}/>
```

```tsx
# New ✅ ^4.0.0
import { makeVestaboardStyles } from '@vestaboard/installables/lib/hooks/useVestaboardStyles';

const useVestaboardStyles = makeVestaboardStyles((props) => ({
  button: {
    // have to specify unit type now
    padding: '4px',
    marginLeft: '4px',
    borderRadius: '6px'
  }
}))
// or w/o props
const useVestaboardStyles = makeVestaboardStyles({
  button: {
    // have to specify unit type now
    padding: '4px',
    marginLeft: '4px',
    borderRadius: '6px'
  }
})
...
<Button sx={classes.button}/>
```