addon-stack · atldays · Aug 10, 2026 · Mar 13, 2026 · Mar 13, 2026 · Aug 10, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -57,54 +57,6 @@ jobs:
           npm install -g npm@11.7.0
           npm -v
 
-      - name: Diagnostic info
-        run: |
-          echo "node=$(node -v)"
-          echo "npm=$(npm -v)"
-          if [ -n "${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" ]; then
-            echo "oidc=available"
-          else
-            echo "oidc=missing"
-          fi
-
-      - name: Inspect OIDC claims
-        run: |
-          if [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL}" ]; then
-            echo "OIDC token request env vars are missing"
-            exit 1
-          fi
-
-          RESPONSE="$(curl -sSf -H "Authorization: bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=npm:registry.npmjs.org")"
-          OIDC_TOKEN="$(node -e 'const fs = require("fs"); const input = fs.readFileSync(0, "utf8"); process.stdout.write(JSON.parse(input).value);' <<< "$RESPONSE")"
-
-          node - <<'EOF' "$OIDC_TOKEN"
-          const token = process.argv[2];
-          const payload = token.split(".")[1];
-
-          if (!payload) {
-            throw new Error("Unable to decode OIDC token payload");
-          }
-
-          const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-          const out = {
-            aud: claims.aud,
-            repository: claims.repository,
-            repository_owner: claims.repository_owner,
-            ref: claims.ref,
-            sha: claims.sha,
-            event_name: claims.event_name,
-            workflow: claims.workflow,
-            workflow_ref: claims.workflow_ref,
-            job_workflow_ref: claims.job_workflow_ref,
-            runner_environment: claims.runner_environment,
-            environment: claims.environment,
-            actor: claims.actor,
-            sub: claims.sub,
-          };
-
-          console.log(JSON.stringify(out, null, 2));
-          EOF
-
       - name: Install dependencies
         run: npm ci
 

diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@ lerna-debug.log*
 node_modules
 dist
 dist-types
+coverage
 addon
 storybook-static
 .adnbn

diff --git a/.release-it.cjs b/.release-it.cjs
@@ -107,7 +107,71 @@ const types = new Map([
 const normalizeRepoUrl = url => url.replace(/^git\+/, "").replace(/\.git$/, "");
 const repoUrl = pkg?.repository?.url ? normalizeRepoUrl(pkg.repository.url) : null;
 
-module.exports = () => {
+const breakingChangePattern = /\bBREAKING(?: |-)?CHANGE\b/i;
+
+function hasBreakingChange(commit) {
+    if (commit.breaking) {
+        return true;
+    }
+
+    const type = String(commit.type || "").trim();
+
+    if (type.endsWith("!")) {
+        return true;
+    }
+
+    if (typeof commit.header === "string" && /^\w+(?:\([^)]+\))?!:/.test(commit.header)) {
+        return true;
+    }
+
+    if (
+        commit.notes?.some(note =>
+            [note.title, note.text].some(value => typeof value === "string" && breakingChangePattern.test(value))
+        )
+    ) {
+        return true;
+    }
+
+    return typeof commit.footer === "string" && breakingChangePattern.test(commit.footer);
+}
+
+function whatBump(commits, currentVersion = pkg.version) {
+    let isBreaking = false;
+    let isMinor = false;
+    let isPatch = false;
+
+    for (const commit of commits) {
+        if (hasBreakingChange(commit)) {
+            isBreaking = true;
+        }
+
+        const type = String(commit.type || "")
+            .trim()
+            .toLowerCase()
+            .replace(/!+$/, "");
+
+        if (type === "feat") {
+            isMinor = true;
+        }
+
+        if (["fix", "perf", "refactor", "ci"].includes(type)) {
+            isPatch = true;
+        }
+    }
+
+    if (isBreaking) {
+        const currentMajor = Number.parseInt(String(currentVersion).replace(/^v/i, "").split(".")[0], 10);
+
+        return {level: Number.isNaN(currentMajor) || currentMajor >= 1 ? 0 : 1};
+    }
+
+    if (isMinor) return {level: 1};
+    if (isPatch) return {level: 2};
+
+    return null;
+}
+
+const createReleaseConfig = () => {
     const contributors = getContributors();
 
     return {
@@ -151,14 +215,6 @@ module.exports = () => {
 
                 presetConfig: {
                     types: [...types.entries()].map(([type, section]) => ({type, section, hidden: false})),
-                    releaseRules: [
-                        {breaking: true, release: "major"},
-                        {type: "feat", release: "minor"},
-                        {type: "fix", release: "patch"},
-                        {type: "perf", release: "patch"},
-                        {type: "refactor", release: "patch"},
-                        {type: "ci", release: "patch"},
-                    ],
                 },
 
                 context: {
@@ -168,39 +224,7 @@ module.exports = () => {
                     contributors,
                 },
 
-                recommendedBump: true,
-                whatBump: commits => {
-                    let isMajor = false;
-                    let isMinor = false;
-                    let isPatch = false;
-
-                    for (const commit of commits) {
-                        const hasBreaking =
-                            Boolean(commit.breaking) ||
-                            (commit.notes &&
-                                commit.notes.some(n => /BREAKING[ -]CHANGE/i.test(n.title || n.text || "")));
-                        if (hasBreaking) {
-                            isMajor = true;
-                            break;
-                        }
-
-                        const type = (commit.type || "").toLowerCase().replace(/!+$/, "");
-
-                        if (type === "feat") {
-                            isMinor = true;
-                        }
-
-                        if (["fix", "perf", "refactor", "ci"].includes(type)) {
-                            isPatch = true;
-                        }
-                    }
-
-                    if (isMajor) return {level: 0};
-                    if (isMinor) return {level: 1};
-                    if (isPatch) return {level: 2};
-
-                    return null;
-                },
+                whatBump,
                 writerOpts: {
                     headerPartial:
                         "## 🚀 Release {{#if name}}`{{name}}` {{else}}{{#if @root.pkg}}`{{@root.pkg.name}}` {{/if}}{{/if}}v{{version}} ({{date}})\n\n",
@@ -259,3 +283,5 @@ module.exports = () => {
         },
     };
 };
+
+module.exports = Object.assign(createReleaseConfig, {whatBump});
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing to addon-ui
+
+## Workflow
+
+- Create feature branches from `develop` and open pull requests back into `develop`.
+- Merge the intended release changes from `develop` into `main`.
+- A push to `main` runs the release workflow, which creates the version commit, tag, GitHub Release, npm publication, and
+  sync back to `develop`.
+
+## Commit messages
+
+Use Conventional Commits:
+
+```text
+<type>(<optional scope>): <subject>
+```
+
+Mark a breaking change with `!` after the type/scope, or with a `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer.
+
+```text
+refactor!: remove deprecated API
+
+BREAKING CHANGE: Consumers must use the replacement API.
+```
+
+## Version policy
+
+Release-it derives the next version from commit history. The highest applicable bump wins.
+
+- Before `1.0.0`, a breaking change produces a minor release (`0.y.0`).
+- Starting at `1.0.0`, a breaking change produces a major release (`x.0.0`).
+- `feat` produces a minor release.
+- `fix`, `perf`, `refactor`, and `ci` produce a patch release.
+- `docs`, `test`, `chore`, and `build` do not produce a release on their own.
+
+## Documentation and validation
+
+- Keep canonical user documentation in `docs/` in sync with public props and CSS variables.
+- Update Storybook stories when a visual component change needs review.
+- Before opening a pull request, run the relevant checks: `npm run lint`, `npm run typecheck`, `npm test`, and
+  `npm run build:types`.
diff --git a/README.md b/README.md
@@ -1,14 +1,17 @@
 # addon-ui
 
-[![npm version](https://img.shields.io/npm/v/addon-ui.svg)](https://www.npmjs.com/package/addon-ui)
-[![npm downloads](https://img.shields.io/npm/dm/addon-ui.svg)](https://www.npmjs.com/package/addon-ui)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+A React UI toolkit for Addon Bone browser-extension applications.
 
-Addon UI - A comprehensive UI component library designed for the Addon Bone framework.
-This library provides a set of customizable React components with theming capabilities to build modern,
-responsive user interfaces.
+[![npm version](https://img.shields.io/npm/v/addon-ui.svg?logo=npm&style=for-the-badge)](https://www.npmjs.com/package/addon-ui)
+[![npm downloads](https://img.shields.io/npm/dm/addon-ui.svg?style=for-the-badge&color=blue)](https://www.npmjs.com/package/addon-ui)
+[![CI](https://img.shields.io/github/actions/workflow/status/addon-stack/addon-ui/ci.yml?branch=develop&style=for-the-badge)](https://github.com/addon-stack/addon-ui/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE.md)
 
-## Features
+Build consistent browser-extension interfaces with React components, typed UI
+configuration, theme customization, and an Addon Bone plugin for shared and
+app-specific UI files.
+
+## Why addon-ui
 
 - 🎨 **Customizable Theming**: Easily customize the look and feel of components through theme configuration
 - 🧩 **Rich Component Set**: Includes buttons, forms, layouts, modals, and more
@@ -18,9 +21,11 @@ responsive user interfaces.
 
 ## Table of Contents
 
+- [Why addon-ui](#why-addon-ui)
 - [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Package Entry Points](#package-entry-points)
 - [Components](#components)
-- [Basic Usage](#basic-usage)
 - [Integration](#integration)
 - [Customization](#customization)
 - [Using Extra Props](#using-extra-props)
@@ -32,24 +37,53 @@ responsive user interfaces.
 
 ## Installation
 
-### npm:
+`addon-ui` is designed to be used with [Addon Bone](https://addonbone.com). Your host application must provide
+compatible `adnbn`, `react`, and `react-dom` peer dependencies.
 
 ```bash
-npm install addon-ui
+npm i addon-ui
 ```
 
-### pnpm:
+With pnpm or Yarn:
 
 ```bash
 pnpm add addon-ui
+yarn add addon-ui
 ```
 
-### yarn:
+## Quick Start
 
-```bash
-yarn add addon-ui
+```jsx
+import React from "react";
+import {Button, ButtonColor, ButtonVariant, TextField, UIProvider} from "addon-ui";
+
+function App() {
+    return (
+        <UIProvider>
+            <div>
+                <TextField label="Username" placeholder="Enter your username" />
+                <Button color={ButtonColor.Primary} variant={ButtonVariant.Contained}>
+                    Submit
+                </Button>
+            </div>
+        </UIProvider>
+    );
+}
+
+export default App;
 ```
 
+## Package Entry Points
+
+| Import            | Use it for                                                    |
+| :---------------- | :------------------------------------------------------------ |
+| `addon-ui`        | React components, UI providers, and theme types.              |
+| `addon-ui/config` | The typed `defineConfig()` helper for UI configuration files. |
+| `addon-ui/plugin` | Addon Bone plugin setup and UI-file discovery.                |
+| `addon-ui/theme`  | Sass mixins for extending theme styles.                       |
+
+See [Plugin Setup](#plugin-setup) to connect the package to an Addon Bone application.
+
 ## Components
 
 This library now ships with dedicated documentation files for each component in the docs/ directory. Start here:
@@ -94,28 +128,6 @@ Notes:
   .module.scss file.
 - Where a component wraps a Radix UI primitive, the doc links to the official Radix docs and lists common props.
 
-## Basic Usage
-
-```jsx
-import React from "react";
-import {Button, ButtonColor, ButtonVariant, TextField, UIProvider} from "addon-ui";
-
-function App() {
-    return (
-        <UIProvider>
-            <div>
-                <TextField label="Username" placeholder="Enter your username" />
-                <Button color={ButtonColor.Primary} variant={ButtonVariant.Contained}>
-                    Submit
-                </Button>
-            </div>
-        </UIProvider>
-    );
-}
-
-export default App;
-```
-
 ## Integration
 
 **Addon UI** is designed exclusively for the [Addon Bone](https://addonbone.com) framework and does not have a standalone build as it's connected
@@ -152,11 +164,11 @@ export default defineConfig({
 | Option        | Type                                               | Default       | Description                                                                                            |
 | :------------ | :------------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------------------- |
 | `themeDir`    | `string`                                           | `"."`         | Directory path where plugin configuration and style files are located.                                 |
-| `configName`  | `string`                                           | `"config.ui"` | Name of the configuration file.                                                                        |
-| `styleName`   | `string`                                           | `"style.ui"`  | Name of the SCSS style file.                                                                           |
+| `configName`  | `string`                                           | `"ui.config"` | Name of the configuration file.                                                                        |
+| `styleName`   | `string`                                           | `"ui.style"`  | Name of the SCSS style file.                                                                           |
 | `mergeConfig` | `boolean`                                          | `true`        | Whether to merge configuration files from different directories.                                       |
 | `mergeStyles` | `boolean`                                          | `true`        | Whether to merge style files from different directories.                                               |
-| `splitChunks` | `boolean \| (name: string) => string \| undefined` | `true`        | Enables automatic chunk splitting. If a function is provided, it can be used to customize chunk names. |
+| `splitChunks` | `boolean \| (name: string) => string \| undefined` | `false`       | Enables automatic chunk splitting. If a function is provided, it can be used to customize chunk names. |
 
 #### Customizing Chunk Names
 
@@ -508,6 +520,7 @@ for full type safety.
 
 ## Contributing
 
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for the branch, commit, and release policy.
 - Keep canonical end-user documentation in the `docs/` directory. When adding or changing CSS variables in a component’s
   `*.module.scss`, update the corresponding doc table.
 - Where a component wraps a Radix primitive, keep the “Radix UI props” section in sync if the underlying package