# Brightspot UI

<a id="readme-top"></a>

<div>
<h2 align="center">platform-ui</h2>
  <p align="center">
    A UI library optimized for rapid, standards-based Brightspot CMS component creation.
    <br/>
  </p>
</div>

<!-- TOC -->
<details>
  <summary>Table of Contents</summary>
  <ol>
  <li>
      <a href="#about">About</a>
    </li>
    <li>
      <a href="#getting-started">Getting Started</a>
    </li>
    <li><a href="#prerequisites">Prerequisites</a></li>
    <li><a href="#installation">Installation</a></li>
    <li>
      <a href="#using-plugins">Using Plugins</a>
    </li>
    <li>
      <a href="#examples">Examples</a>
    </li>
    <li>
      <a href="#development">Development</a>
    </li>
  </ol>
</details>

## About

Brightspot UI is a package of custom web components and styles to provide a basis for building new CMS components. It uses [TailwindCSS](https://v3.tailwindcss.com/) for styling and [LitElement](https://lit.dev/) for web components.

If you're developing a Brightspot CMS plugin or creating custom CMS UI for your project, then you've come to the right place!

<p align="right">(<a href="#readme-top">back to top</a>)</p>

## Getting Started

_Note:_ To get the best developer experience we recommend using VSCode editor. The marketplace of extensions that are available provide code formatting and intellisense for all the TailwindCSS classnames and our plugins, etc. The VSCode setup is documented [here](https://github.com/perfectsense/brightspot/tree/release/5.0/cms/tool-ui#visual-studio-code).

### Prerequisites

Your codebase needs to be compatible with

- TailwindCSS **v3**

### Installation

1. Install the Brightspot ui node module as a devDependency
   ```sh
   yarn add -D @brightspot/ui
   ```
2. Create a `tailwind.config` file and add Brightspot ui as a preset. More on TWCSS presets [here](https://v3.tailwindcss.com/docs/presets#presets).
   ```ts
   // (Typescript example) contents of tailwind.config.ts
    export default {
      ...
      presets: [require('@brightspot/ui')],
      ...
    }
   ```
   ```js
   // (Javascript example) contents of tailwind.config.js
    export default {
      ...
      presets: [require('@brightspot/ui/dist/tailwind.config.js')],
      ...
    }
   ```
3. Build your frontend

<p align="right">(<a href="#readme-top">back to top</a>)</p>

## Using Plugins

Brightspot UI comes with a variety of TailwindCSS plugins to make styling simpler and declarative. Visit the Storybook to see the available plugins.

To use our plugins, include them in your TailwindCSS config as usual. Plugin files are provided in both Typescript and Javascript variants and are available under the `dist` path in the platform-ui module.

An example of including a plugin:

```ts
// your tailwind.config.ts
  ...
  plugins: [
    require('@brightspot/ui/dist/tailwind-plugin-theme.ts'),
    ...
```

## Web Components

Brightspot UI includes custom web components built with LitElement. FOUC (Flash of Unstyled Content) prevention is handled automatically when you import the components.

Import components in your JavaScript/TypeScript:

```ts
import '@brightspot/ui/dist/components/widget/Widget'
```

See the Storybook documentation for detailed usage examples and API references.

## Examples

We use [Storybook](https://storybook.js.org/) for interactive previewing of our ui components. Launch that in the browser by running:

```sh
  yarn storybook
```

<p align="right">(<a href="#readme-top">back to top</a>)</p>

## Development

### Prerequisites

- Node.js v22+
- Yarn 1 (classic)

### Layout

This repo ships two surfaces inside one published `@brightspot/ui` npm package:

- `src/` — the modern design system (web components, Tailwind plugins, presets). Built by `yarn build` into `dist/`.
- `src/legacy/tool-ui/` — the brightspot CMS frontend (JS, CSS, webpack, tests). Has its own `package.json`. Built by `(cd src/legacy/tool-ui && yarn build)` into `src/legacy/tool-ui/src/main/webapp/dist/`.

The publish flow (`yarn prepack`) builds both.

### Component-only work (no CMS needed)

```sh
yarn storybook
```

Opens Storybook at http://localhost:6006. Iterate on `src/` components and Tailwind plugins without booting the CMS.

### CMS integration work

The brightspot CMS consumes `@brightspot/ui` from npm. Two workflows for local iteration:

#### Fast loop: webpack-dev-server (recommended for JS/CSS edits)

1. Start the CMS in docker as usual (from `brightspot/`):

   ```sh
   ./gradlew docker
   ```

2. Start the dev server (from `platform-ui/src/legacy/tool-ui/`):

   ```sh
   yarn server:local
   ```

   Proxies to `localhost` (or `~/.brightspot/local-url` if set), serves freshly compiled assets at `/cms/dist/`, and injects `x-brightspot-dev: 1` on proxied requests so the CMS returns unhashed asset paths.

3. Open the CMS at the dev-server URL (https://localhost:8080/cms/) instead of the docker URL. Edit files in `src/legacy/tool-ui/src/`; changes hot-reload in the browser.

#### Full WAR rebuild (for the modern `src/` surface, or final smoke)

`yarn server:local` only serves `src/legacy/tool-ui/`. For edits to the modern surface in `src/`, or to validate against the actual WAR build:

1. Link the package (once per machine, from `platform-ui/`):

   ```sh
   yarn link
   ```

2. Consume the link (in `brightspot/cms/tool-ui/`):

   ```sh
   yarn link @brightspot/ui
   ```

3. Edit, then rebuild whichever surface changed:

   ```sh
   yarn build                              # for src/ edits
   (cd src/legacy/tool-ui && yarn build)   # for src/legacy/tool-ui/ edits
   ```

4. Rebuild the CMS WAR and roll it into tomcat (from `brightspot/`):

   ```sh
   ./gradlew :cms-tool-ui:yarnBuild
   ./gradlew docker
   ```

5. Smoke at https://localhost/cms/ (apache, port 443).

### Unlink when done

```sh
# in brightspot/cms/tool-ui:
yarn unlink @brightspot/ui && yarn install --force

# in platform-ui:
yarn unlink
```

### Releases

`@brightspot/ui` ships via release-please. For migration-track prereleases (`-cms-ui-migration.N`), bump the version, publish to npm, then update the consumer pin in `brightspot/cms/tool-ui/package.json` and rerun `yarn install` there.

<p align="right">(<a href="#readme-top">back to top</a>)</p>
