@unpunnyfuns/swatchbook-switcher 0.10.2 → 0.11.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unpunny Funs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# swatchbook-switcher
+
+Published as `@unpunnyfuns/swatchbook-switcher`. Framework-agnostic theme-switcher UI for swatchbook — axis pills, preset pills, color-format selector. Consumed by the Storybook addon toolbar and by any React host that knows how to set `data-*` attributes on the document to drive per-theme CSS.
+
+> **Documentation:** [unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/). Token parsing powered by [Terrazzo](https://terrazzo.app/) by the [Terrazzo team](https://github.com/terrazzoapp) via `@unpunnyfuns/swatchbook-core`.
+
+## Install
+
+Most consumers pick this up transitively via `@unpunnyfuns/swatchbook-addon` — the addon re-exports the full switcher API, so `import { ThemeSwitcher } from '@unpunnyfuns/swatchbook-addon'` works and you don't need a second install line. Reach for this package directly when you want the switcher *without* the Storybook addon (a docs-site navbar, a standalone React app using swatchbook tokens):
+
+```sh
+npm install @unpunnyfuns/swatchbook-switcher
+```
+
+## Usage
+
+```tsx
+import { ThemeSwitcher } from '@unpunnyfuns/swatchbook-switcher';
+
+function SiteHeader({ axes, presets, themes }) {
+  return (
+    <ThemeSwitcher
+      axes={axes}
+      presets={presets}
+      themes={themes}
+      activeAxes={{ mode: 'Dark' }}
+      colorFormat="oklch"
+      onAxisChange={(axis, context) => {
+        document.documentElement.setAttribute(`data-sb-${axis}`, context);
+      }}
+      onColorFormatChange={(format) => {
+        document.documentElement.setAttribute('data-sb-color-format', format);
+      }}
+    />
+  );
+}
+```
+
+The component is pure — it doesn't read or write to storage, and it doesn't bake in any particular way of applying the active tuple. The caller decides how to translate `onAxisChange` into DOM updates, routing changes, or global state.
+
+## Exports
+
+| Name | Shape |
+| --- | --- |
+| `ThemeSwitcher` | The popover component. |
+| `ThemeSwitcherProps` | Prop types — axes, presets, themes, active axis tuple, color format, change callbacks, optional `className`. |
+| `SwitcherAxis` / `SwitcherPreset` / `SwitcherTheme` | JSON-friendly shapes the component accepts. Cross-compatible with `@unpunnyfuns/swatchbook-core`'s `Project.axes` / `.presets` / `.themes` — pass them through directly. |
+
+## Where it's used inside this repo
+
+- The Storybook addon's toolbar popover (`packages/addon/src/manager/toolbar.ts`).
+- The docs site's navbar (`apps/docs/src/theme/Navbar/SwatchbookSwitcher/index.tsx`).
+
+Both cases feed `ThemeSwitcher` a snapshot of the active `Project` and wire the callbacks to `document.documentElement.setAttribute` calls. If you're rendering swatchbook tokens on a site that isn't Storybook, mirror that pattern.
+
+## See also
+
+- [`@unpunnyfuns/swatchbook-addon`](../addon) — Storybook addon. Re-exports `ThemeSwitcher` along with the full blocks surface.
+- [`@unpunnyfuns/swatchbook-blocks`](../blocks) — MDX doc blocks that the switcher-driven axis changes propagate to.
+- [`@unpunnyfuns/swatchbook-core`](../core) — the DTCG loader whose output feeds this component.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unpunnyfuns/swatchbook-switcher",
-  "version": "0.10.2",
+  "version": "0.11.2",
   "description": "Framework-agnostic theme-switcher UI for swatchbook — axis pills, preset pills, color-format selector. Consumed by the Storybook addon toolbar and any React host that knows how to set data-attributes on the document.",
   "license": "MIT",
   "author": "unpunnyfuns <unpunnyfuns@gmail.com>",
@@ -43,15 +43,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsdown",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "oxlint --deny-warnings -c ../../.oxlintrc.json src test",
-    "format": "oxfmt -c ../../.oxfmtrc.json src test",
-    "format:check": "oxfmt --check -c ../../.oxfmtrc.json src test"
-  },
   "peerDependencies": {
     "react": ">=18"
   },
@@ -69,5 +60,14 @@
   },
   "dependencies": {
     "clsx": "^2.1.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint --deny-warnings -c ../../.oxlintrc.json src test",
+    "format": "oxfmt -c ../../.oxfmtrc.json src test",
+    "format:check": "oxfmt --check -c ../../.oxfmtrc.json src test"
   }
-}
+}