@unpunnyfuns/swatchbook-blocks 0.19.7 → 0.19.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +20 -74
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,107 +1,53 @@
1
1
  # swatchbook-blocks
2
2
 
3
- Published as `@unpunnyfuns/swatchbook-blocks`. Storybook MDX doc blocks for DTCG design tokens. React components for rendering token documentation inside `.mdx` pages or regular stories. Self-mount the addon's CSS and react to axis changes from the toolbar; work inside the docs container even though story decorators don't.
3
+ React MDX doc blocks for [swatchbook](https://github.com/unpunnyfuns/swatchbook).
4
4
 
5
- > **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`.
5
+ Render your DTCG tokens in `.mdx` stories — swatch grids, type-specific previews, per-token inspectors. The blocks react to the toolbar's axis flips without any wiring in your story code.
6
6
 
7
- ## Install
7
+ Most consumers pick this up transitively via [`@unpunnyfuns/swatchbook-addon`](../addon); `import { TokenTable } from '@unpunnyfuns/swatchbook-addon'` works out of the box. Install this package directly when you want blocks *without* the Storybook addon — unit tests, a standalone React app wrapping tokens in a custom surface.
8
8
 
9
- Most consumers pick this up transitively via `@unpunnyfuns/swatchbook-addon` — the addon re-exports the full blocks API, so `import { TokenTable } from '@unpunnyfuns/swatchbook-addon'` works and you don't need a second install line. Reach for this package directly when you want blocks *without* the Storybook addon (unit tests, a standalone React app wrapping tokens in a custom surface):
9
+ ## Install
10
10
 
11
11
  ```sh
12
12
  npm install @unpunnyfuns/swatchbook-blocks
13
13
  ```
14
14
 
15
- Blocks read the token graph from a `SwatchbookProvider`. Inside Storybook, the addon's preview decorator mounts the provider automatically. Outside Storybook, wrap your tree in `SwatchbookProvider` and pass a `ProjectSnapshot` directly (see [Outside Storybook](#outside-storybook) below).
16
-
17
- ## Blocks
18
-
19
- | Block | What |
20
- | ------------------- | ----------------------------------------------------------------------------------- |
21
- | `TokenTable` | Searchable table of tokens, filterable by path glob and `$type`. |
22
- | `TokenNavigator` | Expandable tree view of the token graph keyed on dot-path segments, with inline per-type previews. |
23
- | `ColorPalette` | Swatch grid grouped by sub-path. Auto-groups from the filter; `groupBy` overrides. |
24
- | `TypographyScale` | Each typography composite token rendered as a sample line using its own value. |
25
- | `FontFamilySample` | Pangram rendered per `fontFamily` primitive. |
26
- | `FontWeightScale` | Same sample text rendered at each `fontWeight` primitive, sorted ascending. |
27
- | `StrokeStyleSample` | Border rendered per `strokeStyle` primitive. |
28
- | `GradientPalette` | Wide swatch per `gradient` token with stop breakdown (linear-gradient default). |
29
- | `MotionSample` | Animated ball + track for one `transition` / `duration` / `cubicBezier` token. Accepts `speed` / `runKey`. |
30
- | `ShadowSample` | Surface rectangle with one `shadow` token applied as `box-shadow`. |
31
- | `BorderSample` | Surface rectangle with one `border` token applied as `border`. |
32
- | `DimensionBar` | Width-driven bar (or square / radius sample, via `kind`) for one `dimension` token. |
33
- | `TokenDetail` | Single-token inspector — composition of the subcomponents below. |
34
- | `TokenHeader` | Heading + `$type` pill + cssVar + `$description`, or a missing-token empty state. |
35
- | `CompositePreview` | Type-dispatched live preview (typography, shadow, border, transition, dimension, duration, cubicBezier, fontFamily, fontWeight, strokeStyle, gradient, color). |
36
- | `CompositeBreakdown`| Labelled sub-value grid for composite types (typography / border / transition / shadow / gradient). |
37
- | `AliasChain` | Forward alias chain (`path → alias → …`). Renders nothing for non-aliases. |
38
- | `AliasedBy` | Aliased-by tree (backward). Truncates at depth 6. |
39
- | `AxisVariance` | Per-axis value table — constant, one-axis, or two-axis matrix view. |
40
- | `TokenUsageSnippet` | Copy-ready `color: var(--…);` snippet. |
41
-
42
- Shared: every block accepts a `caption` override and renders against the addon's `var(--<prefix>-…)` output.
43
-
44
15
  ## Usage
45
16
 
46
- ### Inside Storybook
47
-
48
- The addon's preview decorator wraps every story in a `SwatchbookProvider` for you, so MDX and story authors drop blocks in directly:
17
+ Inside Storybook the addon mounts a `SwatchbookProvider` for you:
49
18
 
50
19
  ```mdx
51
- import { TokenTable, ColorPalette, TokenDetail } from '@unpunnyfuns/swatchbook-addon';
52
-
53
- # Color tokens
20
+ import { ColorPalette, TokenTable, TokenDetail } from '@unpunnyfuns/swatchbook-addon';
54
21
 
55
22
  <ColorPalette filter="color.*" />
56
-
57
- ## Every color token
58
-
59
23
  <TokenTable filter="color.*" type="color" />
60
-
61
- ## Inspect one
62
-
63
24
  <TokenDetail path="color.accent.bg" />
64
25
  ```
65
26
 
66
- ### Outside Storybook
67
-
68
- Blocks are pure presentation — given a `ProjectSnapshot` they render without any Storybook or Vite plugin. Mount a `SwatchbookProvider` at the top of your tree:
27
+ Outside Storybook, wrap your tree in `SwatchbookProvider` and pass a `ProjectSnapshot`:
69
28
 
70
29
  ```tsx
71
30
  import { SwatchbookProvider, TokenTable } from '@unpunnyfuns/swatchbook-blocks';
72
31
  import snapshot from './tokens-snapshot.json';
73
32
 
74
- export function TokenDocs() {
75
- return (
76
- <SwatchbookProvider value={snapshot}>
77
- <TokenTable filter='color.*' />
78
- </SwatchbookProvider>
79
- );
80
- }
33
+ <SwatchbookProvider value={snapshot}>
34
+ <TokenTable filter='color.*' />
35
+ </SwatchbookProvider>
81
36
  ```
82
37
 
83
- `SwatchbookProvider` is the canonical integration point. The `virtual:swatchbook/tokens` module is the Storybook addon's internal wiring, not a public API.
38
+ Block catalogue, props, and composition patterns live in the [blocks reference](https://unpunnyfuns.github.io/swatchbook/reference/blocks) and the [authoring guide](https://unpunnyfuns.github.io/swatchbook/guides/authoring-doc-stories).
84
39
 
85
- ## Props
40
+ ## Boundaries
86
41
 
87
- ```ts
88
- <TokenTable filter="color.*" type="color" />
89
- <ColorPalette filter="color.*" />
90
- <TypographyScale filter="typography" sample="The quick brown fox" />
91
- <TokenDetail path="color.accent.bg" />
92
- ```
42
+ - ✅ Compose multiple blocks per page — each mounts independently.
43
+ - ✅ Render outside Storybook with a hand-built or loaded `ProjectSnapshot`.
44
+ - ❌ Don't import from `virtual:swatchbook/tokens` — it's the addon's internal wiring, not a public API. Use `SwatchbookProvider`.
45
+ - ❌ Don't use `useGlobals` / `useArgs` from `storybook/preview-api` inside custom blocks — those hooks throw in docs context.
93
46
 
94
- ## Do / don't
47
+ ## Credits
95
48
 
96
- - ✅ React to the active swatchbook theme — switching in the toolbar updates resolved values live, even on MDX docs pages.
97
- - ✅ Compose multiple blocks per MDX page — each mounts independently.
98
- - ✅ Render blocks outside Storybook by wrapping them in `SwatchbookProvider` with a hand-built or loaded `ProjectSnapshot`.
99
- - ❌ Don't import from `virtual:swatchbook/tokens` directly — it's the addon's internal wiring, not a public API. Use `SwatchbookProvider` instead.
100
- - ❌ Don't use `useGlobals` / `useArgs` from `storybook/preview-api` inside custom blocks you write — those are story-only hooks and throw in docs context. Subscribe to `addons.getChannel()` directly for globals reactivity.
49
+ Token parsing and resolver evaluation come from [Terrazzo](https://terrazzo.app/) by the [Terrazzo team](https://github.com/terrazzoapp) via `@unpunnyfuns/swatchbook-core`.
101
50
 
102
- ## See also
51
+ ## Documentation
103
52
 
104
- - [`@unpunnyfuns/swatchbook-addon`](../addon) — required peer. Registers the virtual module and the toolbar.
105
- - [`@unpunnyfuns/swatchbook-core`](../core) — underlying loader.
106
- - [Project README](../../README.md) — install and wiring flow for the whole toolchain.
107
- - [Documentation](https://unpunnyfuns.github.io/swatchbook/) — concepts, guides, and full API reference.
53
+ [unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/) — concepts, guides, and full API reference.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unpunnyfuns/swatchbook-blocks",
3
- "version": "0.19.7",
3
+ "version": "0.19.9",
4
4
  "description": "Storybook MDX doc blocks for DTCG design tokens — TokenTable, ColorPalette, TypographyScale, TokenDetail.",
5
5
  "license": "MIT",
6
6
  "author": "unpunnyfuns <unpunnyfuns@gmail.com>",
@@ -68,7 +68,7 @@
68
68
  "@terrazzo/token-tools": "^2.0.3",
69
69
  "clsx": "^2.1.1",
70
70
  "colorjs.io": "0.6.1",
71
- "@unpunnyfuns/swatchbook-core": "0.19.7"
71
+ "@unpunnyfuns/swatchbook-core": "0.19.9"
72
72
  },
73
73
  "scripts": {
74
74
  "build": "tsdown",