# Big Mugs Hero Header

> PixiJS-powered hero header that ships as an npm package and is consumed on the Big Mugs WordPress site through a CDN.

## ✨ Overview

- **Tech stack:** [PixiJS](https://pixijs.com/) rendered inside a Vite + Solid project.
- **Goal:** Develop the hero header in isolation, publish it to npm, and load it on WordPress via an npm CDN (jsDelivr, unpkg, etc.).
- **Output:** A production-ready bundle in `dist/` that auto-mounts the Pixi widget from a CDN script while exposing an opt-in JavaScript API for manual control.

## 🧑‍💻 Local development

```bash
npm install
npm run dev
```

Visit [`http://localhost:5173`](http://localhost:5173) to iterate on the header independently of WordPress. Keep the public API of the entry file stable so the published bundle can be safely updated without changing the WordPress integration code.

## 🏗️ Project layout

| Path | Purpose |
| --- | --- |
| `src/` | Source files for the PixiJS scene and Solid entry point. |
| `public/` | Static assets copied as-is into the build. |
| `dist/` | Generated output after running `npm run build`; this is what gets published to npm/CDN. |
| `scripts/` | Helper scripts for build or deployment tasks. |

## 🚀 Publishing to npm

1. **Prepare `package.json`**
   - Select an npm-safe name (e.g. `@big-mugs/hero-header`).
   - Remove the `"private": true` flag.
   - Fill in `version`, `description`, `author`, `license`, and `repository`.
   - Ensure `main`, `module`, and `types` (if shipping TypeScript types) point to the files under `dist/`.
   - Optionally define an `exports` map to control the public surface area.
2. **Verify the entry point**
   - Confirm the build exports a function that mounts the header into a provided DOM node.
   - Bundle any required CSS or static assets.
3. **Build the package**
   - Run `npm run build` to emit the production bundle into `dist/`.
   - Test locally by opening `index.html` or importing the bundle into a sandbox page.
4. **Authenticate & publish**
   - Run `npm login` (ensure you have rights to the chosen scope).
   - Bump the version following semantic versioning: `npm version patch|minor|major`.
   - Publish with `npm publish --access public`.
   - Create a git tag once the publish succeeds.

## ☁️ Loading from an npm CDN

Example using jsDelivr (the script self-mounts anywhere it finds the widget attribute or fallback ID):

```html
<div data-big-mugs-widget="homepage-header"></div>
<script
  src="https://cdn.jsdelivr.net/npm/@big-mugs/hero-header@1.0.0/dist/big-mugs-widgets.js"
  defer
></script>
```

Pin the URL to the published version you want to serve. When the script executes it automatically mounts the Pixi application into any element matching `[data-big-mugs-widget="homepage-header"]` or `#homepage-header-widget`.

If you need manual control, the bundle assigns helpers to `window.BigMugsWidgets.homepageHeader`:

```js
window.BigMugsWidgets.homepageHeader.mountAll();
// or mount a specific element
window.BigMugsWidgets.homepageHeader.mount(document.querySelector('#custom-container'));
```

### Funky burger menu widget

The package also exposes a Pixi-powered burger menu button that can replace a standard mobile menu trigger. Add an element with the
`data-big-mugs-widget="funky-burger-menu"` attribute and the CDN script will auto-mount the animated button. Manual control is
available via `window.BigMugsWidgets.funkyBurgerMenu`:

```js
const handle = await window.BigMugsWidgets.funkyBurgerMenu.mount(document.querySelector('#menu-toggle'));
handle.onToggle((isOpen) => {
  document.body.classList.toggle('nav-open', isOpen);
});
```

The widget handle exposes `open()`, `close()`, `toggle(forceState?)`, and `isOpen()` helpers along with an `onToggle` listener for
synchronising the menu state with the rest of your application.

## 🧩 Integrating with WordPress

1. Add the mount element where the animation should appear, e.g. `<div data-big-mugs-widget="homepage-header"></div>`.
2. Enqueue the CDN bundle in your theme or plugin:

   ```php
   function big_mugs_enqueue_hero_header() {
       wp_enqueue_script(
           'big-mugs-hero-header',
           'https://cdn.jsdelivr.net/npm/@big-mugs/hero-header@1.0.0/dist/big-mugs-widgets.js',
           [],
           null,
           true
       );
   }
   add_action( 'wp_enqueue_scripts', 'big_mugs_enqueue_hero_header' );
   ```

3. (Optional) Trigger `window.BigMugsWidgets.homepageHeader.mountAll()` from your script if you prefer to mount after custom logic (the auto-mount will simply no-op if it already ran).
4. Update the CDN URL version whenever you publish a new release to ensure cache busting.

## 🔁 Release checklist

- [ ] Update source assets and confirm the public API has not changed unexpectedly.
- [ ] Run `npm run build` and smoke test the generated bundle.
- [ ] Update `CHANGELOG.md` (if present) and bump the version.
- [ ] Publish to npm and tag the release in git.
- [ ] Update the WordPress CDN reference to the new version and verify the site in production.

Happy shipping! 🚢