@elastic/distillate 0.0.0 → 0.2.0

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 (292) hide show
  1. package/LICENSE.txt +93 -0
  2. package/NOTICE.txt +30 -0
  3. package/README.md +142 -0
  4. package/THIRD_PARTY_LICENSES.md +768 -0
  5. package/dist/cjs/collector.js +491 -0
  6. package/dist/cjs/collector.js.map +1 -0
  7. package/dist/cjs/css_scan.js +186 -0
  8. package/dist/cjs/css_scan.js.map +1 -0
  9. package/dist/cjs/dom_sink.js +40 -0
  10. package/dist/cjs/dom_sink.js.map +1 -0
  11. package/dist/cjs/emotion.js +189 -0
  12. package/dist/cjs/emotion.js.map +1 -0
  13. package/dist/cjs/engine.js +95 -0
  14. package/dist/cjs/engine.js.map +1 -0
  15. package/dist/cjs/environment.js +9 -0
  16. package/dist/cjs/environment.js.map +1 -0
  17. package/dist/cjs/hash.js +86 -0
  18. package/dist/cjs/hash.js.map +1 -0
  19. package/dist/cjs/idents.js +23 -0
  20. package/dist/cjs/idents.js.map +1 -0
  21. package/dist/cjs/index.js +44 -0
  22. package/dist/cjs/index.js.map +1 -0
  23. package/dist/cjs/instance.js +34 -0
  24. package/dist/cjs/instance.js.map +1 -0
  25. package/dist/cjs/local_vars.js +100 -0
  26. package/dist/cjs/local_vars.js.map +1 -0
  27. package/dist/cjs/minify.js +77 -0
  28. package/dist/cjs/minify.js.map +1 -0
  29. package/dist/cjs/names.js +77 -0
  30. package/dist/cjs/names.js.map +1 -0
  31. package/dist/cjs/nesting.js +406 -0
  32. package/dist/cjs/nesting.js.map +1 -0
  33. package/dist/cjs/package.json +3 -0
  34. package/dist/cjs/runtime.js +257 -0
  35. package/dist/cjs/runtime.js.map +1 -0
  36. package/dist/cjs/sink.js +9 -0
  37. package/dist/cjs/sink.js.map +1 -0
  38. package/dist/cjs/styles/authoring.js +169 -0
  39. package/dist/cjs/styles/authoring.js.map +1 -0
  40. package/dist/cjs/styles/declarations.js +139 -0
  41. package/dist/cjs/styles/declarations.js.map +1 -0
  42. package/dist/cjs/styles/index.js +32 -0
  43. package/dist/cjs/styles/index.js.map +1 -0
  44. package/dist/cjs/styles/module.js +233 -0
  45. package/dist/cjs/styles/module.js.map +1 -0
  46. package/dist/cjs/styles/registry.js +187 -0
  47. package/dist/cjs/styles/registry.js.map +1 -0
  48. package/dist/cjs/styles/types.js +9 -0
  49. package/dist/cjs/styles/types.js.map +1 -0
  50. package/dist/cjs/testing.js +37 -0
  51. package/dist/cjs/testing.js.map +1 -0
  52. package/dist/cjs/theme.js +249 -0
  53. package/dist/cjs/theme.js.map +1 -0
  54. package/dist/cjs/tokens/contextual_var.js +39 -0
  55. package/dist/cjs/tokens/contextual_var.js.map +1 -0
  56. package/dist/cjs/tokens/index.js +24 -0
  57. package/dist/cjs/tokens/index.js.map +1 -0
  58. package/dist/cjs/tokens/kind.js +14 -0
  59. package/dist/cjs/tokens/kind.js.map +1 -0
  60. package/dist/cjs/tokens/light_dark.js +42 -0
  61. package/dist/cjs/tokens/light_dark.js.map +1 -0
  62. package/dist/cjs/tokens/scale_token.js +28 -0
  63. package/dist/cjs/tokens/scale_token.js.map +1 -0
  64. package/dist/cjs/tokens/theme_token.js +28 -0
  65. package/dist/cjs/tokens/theme_token.js.map +1 -0
  66. package/dist/cjs/var_invariant.js +115 -0
  67. package/dist/cjs/var_invariant.js.map +1 -0
  68. package/dist/collector.d.ts +101 -0
  69. package/dist/collector.d.ts.map +1 -0
  70. package/dist/collector.js +487 -0
  71. package/dist/collector.js.map +1 -0
  72. package/dist/css_scan.d.ts +57 -0
  73. package/dist/css_scan.d.ts.map +1 -0
  74. package/dist/css_scan.js +180 -0
  75. package/dist/css_scan.js.map +1 -0
  76. package/dist/dom_sink.d.ts +23 -0
  77. package/dist/dom_sink.d.ts.map +1 -0
  78. package/dist/dom_sink.js +36 -0
  79. package/dist/dom_sink.js.map +1 -0
  80. package/dist/emotion.d.ts +44 -0
  81. package/dist/emotion.d.ts.map +1 -0
  82. package/dist/emotion.js +184 -0
  83. package/dist/emotion.js.map +1 -0
  84. package/dist/engine.d.ts +66 -0
  85. package/dist/engine.d.ts.map +1 -0
  86. package/dist/engine.js +91 -0
  87. package/dist/engine.js.map +1 -0
  88. package/dist/environment.d.ts +43 -0
  89. package/dist/environment.d.ts.map +1 -0
  90. package/dist/environment.js +8 -0
  91. package/dist/environment.js.map +1 -0
  92. package/dist/hash.d.ts +2 -0
  93. package/dist/hash.d.ts.map +1 -0
  94. package/dist/hash.js +82 -0
  95. package/dist/hash.js.map +1 -0
  96. package/dist/idents.d.ts +9 -0
  97. package/dist/idents.d.ts.map +1 -0
  98. package/dist/idents.js +19 -0
  99. package/dist/idents.js.map +1 -0
  100. package/dist/index.d.ts +11 -0
  101. package/dist/index.d.ts.map +1 -0
  102. package/dist/index.js +15 -0
  103. package/dist/index.js.map +1 -0
  104. package/dist/instance.d.ts +16 -0
  105. package/dist/instance.d.ts.map +1 -0
  106. package/dist/instance.js +30 -0
  107. package/dist/instance.js.map +1 -0
  108. package/dist/local_vars.d.ts +75 -0
  109. package/dist/local_vars.d.ts.map +1 -0
  110. package/dist/local_vars.js +92 -0
  111. package/dist/local_vars.js.map +1 -0
  112. package/dist/minify.d.ts +11 -0
  113. package/dist/minify.d.ts.map +1 -0
  114. package/dist/minify.js +73 -0
  115. package/dist/minify.js.map +1 -0
  116. package/dist/names.d.ts +39 -0
  117. package/dist/names.d.ts.map +1 -0
  118. package/dist/names.js +70 -0
  119. package/dist/names.js.map +1 -0
  120. package/dist/nesting.d.ts +59 -0
  121. package/dist/nesting.d.ts.map +1 -0
  122. package/dist/nesting.js +400 -0
  123. package/dist/nesting.js.map +1 -0
  124. package/dist/runtime.d.ts +36 -0
  125. package/dist/runtime.d.ts.map +1 -0
  126. package/dist/runtime.js +252 -0
  127. package/dist/runtime.js.map +1 -0
  128. package/dist/sink.d.ts +16 -0
  129. package/dist/sink.d.ts.map +1 -0
  130. package/dist/sink.js +8 -0
  131. package/dist/sink.js.map +1 -0
  132. package/dist/styles/authoring.d.ts +59 -0
  133. package/dist/styles/authoring.d.ts.map +1 -0
  134. package/dist/styles/authoring.js +155 -0
  135. package/dist/styles/authoring.js.map +1 -0
  136. package/dist/styles/declarations.d.ts +10 -0
  137. package/dist/styles/declarations.d.ts.map +1 -0
  138. package/dist/styles/declarations.js +132 -0
  139. package/dist/styles/declarations.js.map +1 -0
  140. package/dist/styles/index.d.ts +7 -0
  141. package/dist/styles/index.d.ts.map +1 -0
  142. package/dist/styles/index.js +12 -0
  143. package/dist/styles/index.js.map +1 -0
  144. package/dist/styles/module.d.ts +5 -0
  145. package/dist/styles/module.d.ts.map +1 -0
  146. package/dist/styles/module.js +229 -0
  147. package/dist/styles/module.js.map +1 -0
  148. package/dist/styles/registry.d.ts +48 -0
  149. package/dist/styles/registry.d.ts.map +1 -0
  150. package/dist/styles/registry.js +182 -0
  151. package/dist/styles/registry.js.map +1 -0
  152. package/dist/styles/types.d.ts +211 -0
  153. package/dist/styles/types.d.ts.map +1 -0
  154. package/dist/styles/types.js +8 -0
  155. package/dist/styles/types.js.map +1 -0
  156. package/dist/testing.d.ts +10 -0
  157. package/dist/testing.d.ts.map +1 -0
  158. package/dist/testing.js +31 -0
  159. package/dist/testing.js.map +1 -0
  160. package/dist/theme.d.ts +85 -0
  161. package/dist/theme.d.ts.map +1 -0
  162. package/dist/theme.js +240 -0
  163. package/dist/theme.js.map +1 -0
  164. package/dist/tokens/contextual_var.d.ts +35 -0
  165. package/dist/tokens/contextual_var.d.ts.map +1 -0
  166. package/dist/tokens/contextual_var.js +33 -0
  167. package/dist/tokens/contextual_var.js.map +1 -0
  168. package/dist/tokens/index.d.ts +5 -0
  169. package/dist/tokens/index.d.ts.map +1 -0
  170. package/dist/tokens/index.js +11 -0
  171. package/dist/tokens/index.js.map +1 -0
  172. package/dist/tokens/kind.d.ts +2 -0
  173. package/dist/tokens/kind.d.ts.map +1 -0
  174. package/dist/tokens/kind.js +10 -0
  175. package/dist/tokens/kind.js.map +1 -0
  176. package/dist/tokens/light_dark.d.ts +20 -0
  177. package/dist/tokens/light_dark.d.ts.map +1 -0
  178. package/dist/tokens/light_dark.js +37 -0
  179. package/dist/tokens/light_dark.js.map +1 -0
  180. package/dist/tokens/scale_token.d.ts +20 -0
  181. package/dist/tokens/scale_token.d.ts.map +1 -0
  182. package/dist/tokens/scale_token.js +23 -0
  183. package/dist/tokens/scale_token.js.map +1 -0
  184. package/dist/tokens/theme_token.d.ts +20 -0
  185. package/dist/tokens/theme_token.d.ts.map +1 -0
  186. package/dist/tokens/theme_token.js +23 -0
  187. package/dist/tokens/theme_token.js.map +1 -0
  188. package/dist/var_invariant.d.ts +25 -0
  189. package/dist/var_invariant.d.ts.map +1 -0
  190. package/dist/var_invariant.js +108 -0
  191. package/dist/var_invariant.js.map +1 -0
  192. package/docs/concepts/authoring.md +115 -0
  193. package/docs/concepts/collection.md +66 -0
  194. package/docs/concepts/distillery.md +47 -0
  195. package/docs/concepts/index.md +18 -0
  196. package/docs/concepts/naming-and-output.md +123 -0
  197. package/docs/concepts/ordering.md +61 -0
  198. package/docs/concepts/single-copy.md +103 -0
  199. package/docs/concepts/tokens.md +99 -0
  200. package/docs/docset.yml +53 -0
  201. package/docs/examples/01-stylesheet.ts +20 -0
  202. package/docs/examples/02-artifact.ts +26 -0
  203. package/docs/examples/03-variants.ts +40 -0
  204. package/docs/examples/04-emotion.ts +33 -0
  205. package/docs/examples/05-var-invariant.ts +31 -0
  206. package/docs/examples/06-payload.ts +85 -0
  207. package/docs/examples/fixture.ts +22 -0
  208. package/docs/getting-started/index.md +14 -0
  209. package/docs/getting-started/installation.md +30 -0
  210. package/docs/getting-started/quick-start.md +61 -0
  211. package/docs/getting-started/your-first-stylesheet.md +57 -0
  212. package/docs/guides/compact-artifacts.md +87 -0
  213. package/docs/guides/emotion-migration.md +60 -0
  214. package/docs/guides/index.md +17 -0
  215. package/docs/guides/name-collisions.md +37 -0
  216. package/docs/guides/non-css-surfaces.md +73 -0
  217. package/docs/guides/react-renderer.md +202 -0
  218. package/docs/guides/theming.md +107 -0
  219. package/docs/guides/var-invariant.md +24 -0
  220. package/docs/guides/vs-emotion.md +61 -0
  221. package/docs/index.md +73 -0
  222. package/docs/logo.svg +7 -0
  223. package/docs/playground/index.html +12 -0
  224. package/docs/playground/package.json +23 -0
  225. package/docs/playground/src/app/app.tsx +109 -0
  226. package/docs/playground/src/app/css_panel.tsx +119 -0
  227. package/docs/playground/src/app/editor_panel.tsx +87 -0
  228. package/docs/playground/src/app/index.ts +8 -0
  229. package/docs/playground/src/app/monaco_css_editor.tsx +84 -0
  230. package/docs/playground/src/app/monaco_source_editor.tsx +132 -0
  231. package/docs/playground/src/app/preview_panel.tsx +99 -0
  232. package/docs/playground/src/app/tokens_panel.tsx +117 -0
  233. package/docs/playground/src/app/types.ts +10 -0
  234. package/docs/playground/src/examples/snippets.test.ts +28 -0
  235. package/docs/playground/src/examples/snippets.ts +418 -0
  236. package/docs/playground/src/lib/compile.test.ts +157 -0
  237. package/docs/playground/src/lib/compile.ts +242 -0
  238. package/docs/playground/src/lib/demo_environment.test.ts +123 -0
  239. package/docs/playground/src/lib/demo_environment.ts +140 -0
  240. package/docs/playground/src/lib/editor_lib.test.ts +39 -0
  241. package/docs/playground/src/lib/editor_lib.ts +142 -0
  242. package/docs/playground/src/lib/format_css.test.ts +41 -0
  243. package/docs/playground/src/lib/format_css.ts +71 -0
  244. package/docs/playground/src/main.tsx +25 -0
  245. package/docs/playground/src/setup/chrome.test.ts +47 -0
  246. package/docs/playground/src/setup/chrome.ts +365 -0
  247. package/docs/playground/src/setup/monaco_env.ts +64 -0
  248. package/docs/playground/tsconfig.json +22 -0
  249. package/docs/playground/vite.config.ts +37 -0
  250. package/docs/playground/vitest.config.ts +35 -0
  251. package/docs/playground.md +28 -0
  252. package/docs/reference/api/emotion.md +290 -0
  253. package/docs/reference/api/index-1.md +2387 -0
  254. package/docs/reference/api/index.md +9 -0
  255. package/docs/reference/api/testing.md +92 -0
  256. package/docs/reference/api.md +12 -0
  257. package/docs/reference/entry-points.md +139 -0
  258. package/docs/reference/environment.md +60 -0
  259. package/docs/reference/index.md +11 -0
  260. package/docs/reference/okf-map.md +93 -0
  261. package/package.json +127 -4
  262. package/src/collector.ts +612 -0
  263. package/src/css_scan.ts +263 -0
  264. package/src/dom_sink.ts +64 -0
  265. package/src/emotion.ts +308 -0
  266. package/src/engine.ts +241 -0
  267. package/src/environment.ts +56 -0
  268. package/src/hash.ts +111 -0
  269. package/src/idents.ts +21 -0
  270. package/src/index.ts +106 -0
  271. package/src/instance.ts +49 -0
  272. package/src/local_vars.ts +220 -0
  273. package/src/minify.ts +87 -0
  274. package/src/names.ts +129 -0
  275. package/src/nesting.ts +596 -0
  276. package/src/runtime.ts +428 -0
  277. package/src/sink.ts +25 -0
  278. package/src/styles/authoring.ts +244 -0
  279. package/src/styles/declarations.ts +172 -0
  280. package/src/styles/index.ts +58 -0
  281. package/src/styles/module.ts +396 -0
  282. package/src/styles/registry.ts +261 -0
  283. package/src/styles/types.ts +283 -0
  284. package/src/testing.ts +48 -0
  285. package/src/theme.ts +454 -0
  286. package/src/tokens/contextual_var.ts +72 -0
  287. package/src/tokens/index.ts +17 -0
  288. package/src/tokens/kind.ts +13 -0
  289. package/src/tokens/light_dark.ts +58 -0
  290. package/src/tokens/scale_token.ts +41 -0
  291. package/src/tokens/theme_token.ts +42 -0
  292. package/src/var_invariant.ts +147 -0
@@ -0,0 +1,9 @@
1
+ # @elastic/distillate
2
+
3
+ ## Modules
4
+
5
+ | Module | Description |
6
+ | ------ | ------ |
7
+ | [emotion](emotion.md) | - |
8
+ | [index](index-1.md) | - |
9
+ | [testing](testing.md) | - |
@@ -0,0 +1,92 @@
1
+ # testing
2
+
3
+ ## Interfaces
4
+
5
+ ### VarInvariantViolation [#varinvariantviolation]
6
+
7
+ Defined in: [var\_invariant.ts:14](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L14)
8
+
9
+ A `var(...)` whose custom property is never declared in the same CSS text.
10
+
11
+ #### Properties
12
+
13
+ | Property | Modifier | Type | Description | Defined in |
14
+ | ------ | ------ | ------ | ------ | ------ |
15
+ | $$$context$$$ `context` | `readonly` | `string` | Surrounding CSS text for error reporting. | [var\_invariant.ts:18](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L18) |
16
+ | $$$reference$$$ `reference` | `readonly` | `string` | The undeclared custom property name (e.g. `--aui-color-bg`). | [var\_invariant.ts:16](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L16) |
17
+
18
+ ## Functions
19
+
20
+ ### assertVarRefsHaveDeclarations() [#assertvarrefshavedeclarations]
21
+
22
+ ```ts
23
+ function assertVarRefsHaveDeclarations(css): void;
24
+ ```
25
+
26
+ Defined in: [var\_invariant.ts:135](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L135)
27
+
28
+ Throws if any `var(...)` in `css` has no matching custom-property declaration.
29
+
30
+ #### Parameters
31
+
32
+ | Parameter | Type | Description |
33
+ | ------ | ------ | ------ |
34
+ | `css` | `string` | Full CSS text to scan. |
35
+
36
+ #### Returns
37
+
38
+ `void`
39
+
40
+ #### Throws
41
+
42
+ If any reference has no declaration in the same text.
43
+
44
+ ***
45
+
46
+ ### findVarRefViolations() [#findvarrefviolations]
47
+
48
+ ```ts
49
+ function findVarRefViolations(css): readonly VarInvariantViolation[];
50
+ ```
51
+
52
+ Defined in: [var\_invariant.ts:109](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L109)
53
+
54
+ Returns all `var(...)` references whose custom property is never declared in `css`.
55
+
56
+ #### Parameters
57
+
58
+ | Parameter | Type | Description |
59
+ | ------ | ------ | ------ |
60
+ | `css` | `string` | Full CSS text to scan. |
61
+
62
+ #### Returns
63
+
64
+ readonly [`VarInvariantViolation`](#varinvariantviolation)[]
65
+
66
+ ***
67
+
68
+ ### tokenTreeDts() [#tokentreedts]
69
+
70
+ ```ts
71
+ function tokenTreeDts(
72
+ typeName,
73
+ tree,
74
+ leafType?
75
+ ): string;
76
+ ```
77
+
78
+ Defined in: [testing.ts:23](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/testing.ts#L23)
79
+
80
+ Emits a TypeScript `interface` for a derived token tree, for Monaco extraLib text.
81
+
82
+ #### Parameters
83
+
84
+ | Parameter | Type | Default value | Description |
85
+ | ------ | ------ | ------ | ------ |
86
+ | `typeName` | `string` | `undefined` | Interface identifier. |
87
+ | `tree` | `object` | `undefined` | Derived CssToken / ScaleToken tree. |
88
+ | `leafType` | `string` | `'CssInterpolable'` | Identifier used for every leaf. Defaults to `CssInterpolable`. |
89
+
90
+ #### Returns
91
+
92
+ `string`
@@ -0,0 +1,12 @@
1
+ ---
2
+ navigation_title: Generated API
3
+ description: TypeDoc output for the three public entry points.
4
+ ---
5
+
6
+ # Generated API
7
+
8
+ Per-symbol pages are generated by TypeDoc from the source JSDoc and written to `docs/reference/api/` at build time (`pnpm docs:api`). They are not committed.
9
+
10
+ On the published site those pages appear in this section's sidebar. Locally, `pnpm docs:dev` generates the folder and serves it with live reload.
11
+
12
+ When browsing this repo on GitHub, use [entry points](entry-points.md): runtime vs type tables, import examples, and signatures for `createDistillery`, collectors, `createEmotion`, and the testing helpers. The JSDoc on `src/index.ts`, `src/emotion.ts`, and `src/testing.ts` is the source of truth for those pages.
@@ -0,0 +1,139 @@
1
+ ---
2
+ navigation_title: Entry points
3
+ description: Root, emotion, and testing exports.
4
+ ---
5
+
6
+ # Entry points
7
+
8
+ Runtime values are importable at runtime. Type-only names exist in `.d.ts` only.
9
+
10
+ ## `@elastic/distillate`
11
+
12
+ ```ts
13
+ import {
14
+ createDistillery,
15
+ combineClassNames,
16
+ type Distillery,
17
+ type DistilleryEnvironment,
18
+ type StyleHandle,
19
+ } from '@elastic/distillate';
20
+ ```
21
+
22
+ | Export | Kind | Role |
23
+ | ------ | ---- | ---- |
24
+ | `createDistillery` | runtime | Bind prefix and a theme tree. |
25
+ | `cssVarName` | runtime | `--${prefix}-${path}` with `/` joined on `-`; strips a leading `vars/`. |
26
+ | `lightDark` / `cq` | runtime | Theme-tree leaves. `cq` aliases `scaleToken`. |
27
+ | `zipSchemes` | runtime | Fold two per-scheme trees. Differing strings become `lightDark`. |
28
+ | `resolveThemeValues` | runtime | Nested literal values for one scheme. Prefer `distillery.resolveValues`. |
29
+ | `themeToken` / `scaleToken` / `contextualVar` | runtime | Token factories. Derivation calls `themeToken` / `scaleToken`. |
30
+ | `isCssToken` / `isScaleToken` / `isContextualCssVar` / `isContextualCssVarName` | runtime | Type guards. |
31
+ | `css` / `decls` | runtime | Handle and declaration templates. Also on the `createStyleModule` factory argument. |
32
+ | `rule` / `media` / `container` / `variants` / `mapDomain` | runtime | Root-entry authoring helpers. `mapDomain` has no collector side effect. |
33
+ | `combineClassNames` | runtime | `context.resolveClassName(...handles)`. |
34
+ | `StylesCollector` | runtime | Class; `artifactCollector` / `stylesheetCollector` / `liveCollection` return or wrap instances. `subscribe` reports growth. |
35
+ | `createDomSink` | runtime | One `<style>` element in `document.head` or a given `parent` (e.g. a `ShadowRoot`), flushed per turn. Also exported from `./emotion`. |
36
+ | `renderStyles` | runtime | Unbound renderer; prefer `distillery.renderStyles`. |
37
+ | `createStyleNameResolver` | runtime | Standalone compact/readable name map. |
38
+ | `StyleRegistry` | runtime | Module registry class. |
39
+ | `Distillery` / `DistilleryOptions` / `DistilleryEnvironment` / `ThemeVarDefinition` | type | Bindings. |
40
+ | `TokensOf` / `ValuesOf` / `PathsOf` / `ThemeTree` / `SchemePair` / `ThemeVariation` / `ResolvedThemeVariation` / `ThemeAlternate` / `RenderStylesOptions` | type | Theme derivation and render selection. |
41
+ | `StyleHandle` / `StylesModule` / `StyleNameResolver` / `StyleNameMode` / `StyleTarget` | type | Handles, modules, naming. |
42
+ | `LiveCollection` / `LiveCollectionOptions` | type | `distillery.liveCollection` result and options. |
43
+ | `StyleSink` / `CreateDomSinkOptions` / `DocumentLike` / `StyleElementLike` / `StyleParentLike` | type | Sink surface. |
44
+
45
+ ### Key signatures
46
+
47
+ ```ts
48
+ createDistillery<const TTheme extends ThemeTree>(
49
+ options: DistilleryOptions<TTheme>
50
+ ): Distillery<TokensOf<TTheme>, TTheme>;
51
+
52
+ distillery.resolveValues(scheme: 'light' | 'dark', variation?: string): ValuesOf<TTheme>;
53
+
54
+ distillery.createStyleModule(name, ({ css, tokens }) => ({ ... }));
55
+ distillery.artifactCollector(
56
+ names: 'compact' | 'readable',
57
+ options?: { warn?: (message: string) => void }
58
+ ): StylesCollector;
59
+ distillery.stylesheetCollector(
60
+ names?: 'compact' | 'readable',
61
+ options?: { warn?: (message: string) => void }
62
+ ): StylesCollector;
63
+ distillery.liveCollection(options?: {
64
+ sink?: StyleSink;
65
+ render?: RenderStylesOptions;
66
+ warn?: (message: string) => void;
67
+ }): LiveCollection; // { collector, resolveClassName(...handles), css() }
68
+ distillery.renderStyles(
69
+ collector: StylesCollector,
70
+ resolver?: StyleNameResolver,
71
+ options?: RenderStylesOptions
72
+ ): string;
73
+
74
+ collector.use(module | entry | entries): void;
75
+ collector.useHandles(handles: readonly StyleHandle[]): readonly StyleHandle[];
76
+ collector.createResolver(): StyleNameResolver;
77
+ collector.subscribe(listener: () => void): () => void; // once per outermost call that grows
78
+ createDomSink(options: {
79
+ document: DocumentLike;
80
+ parent?: StyleParentLike;
81
+ schedule?: (flush: () => void) => void;
82
+ }): StyleSink;
83
+ ```
84
+
85
+ Field-level environment types: [Environment](environment.md).
86
+
87
+ ## `@elastic/distillate/emotion`
88
+
89
+ ```ts
90
+ import {
91
+ createEmotion,
92
+ createDomSink,
93
+ type Emotion,
94
+ } from '@elastic/distillate/emotion';
95
+
96
+ const { css, cx, injectGlobal, stylesheet, globalModules } = createEmotion(
97
+ distillery,
98
+ { sink: createDomSink({ document }) }
99
+ );
100
+ ```
101
+
102
+ | Export | Kind | Role |
103
+ | ------ | ---- | ---- |
104
+ | `createEmotion` | runtime | `css` / `cx` / `injectGlobal` over the distillery registry. |
105
+ | `createDomSink` | runtime | One `<style>` element, flushed per turn. Re-exported from the root entry. |
106
+ | `Emotion` / `EmotionCss` / `CreateEmotionOptions` / `StyleSink` | type | Return and option types. |
107
+ | `CreateDomSinkOptions` / `DocumentLike` / `StyleElementLike` / `StyleParentLike` | type | DOM sink surface. Same as the root entry. |
108
+
109
+ ```ts
110
+ createEmotion(distillery, options?: { sink?: StyleSink }): Emotion;
111
+ createDomSink(options: { document: DocumentLike; parent?: StyleParentLike; schedule?: (flush: () => void) => void }): StyleSink;
112
+ ```
113
+
114
+ The string form of a `css` template is readable and does not collect. The wrapper is still a `StyleHandle` for `useHandles` / `resolveClassName`.
115
+
116
+ ## `@elastic/distillate/testing`
117
+
118
+ ```ts callouts=false
119
+ import {
120
+ assertVarRefsHaveDeclarations,
121
+ findVarRefViolations,
122
+ tokenTreeDts,
123
+ type VarInvariantViolation,
124
+ } from '@elastic/distillate/testing';
125
+
126
+ findVarRefViolations(css: string): VarInvariantViolation[];
127
+ assertVarRefsHaveDeclarations(css: string): void; // throws on violations
128
+ ```
129
+
130
+ | Export | Kind | Role |
131
+ | ------ | ---- | ---- |
132
+ | `findVarRefViolations` | runtime | Returns `{ reference, context }[]`. |
133
+ | `assertVarRefsHaveDeclarations` | runtime | Throws if any `var(...)` is undeclared in the same text. |
134
+ | `tokenTreeDts` | runtime | Emits a TypeScript `interface` for a derived token tree (Monaco extraLib). |
135
+ | `VarInvariantViolation` | type | `reference` plus nearby `context`. |
136
+
137
+ No `stylis` import. Safe to use from tests that must not pull the compiler.
138
+
139
+ Generated per-symbol docs are under [Generated API](api.md) after `pnpm docs:api`.
@@ -0,0 +1,60 @@
1
+ ---
2
+ navigation_title: Environment
3
+ description: DistilleryOptions, DistilleryEnvironment, and ThemeVarDefinition fields.
4
+ ---
5
+
6
+ # Environment
7
+
8
+ `createDistillery` takes `DistilleryOptions`. `Distillery.environment` is the resolved form: derived `themeVars` and `tokens`.
9
+
10
+ ## `DistilleryOptions`
11
+
12
+ | Field | Type | Required | Notes |
13
+ | ------------ | -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
14
+ | `prefix` | `string` | yes | CSS identifier segment. Used in readable class and CSS-variable names. |
15
+ | `themeScope` | `string` | yes | Selector wrapping the theme-variable block. |
16
+ | `theme` | `ThemeTree` | yes | Nested value tree. Strings and `lightDark` become theme vars; `cq` / `scaleToken` inline. |
17
+ | `variations` | `Record<string, ThemeVariation>` | no | Named value-only diffs of `theme`. Declaring a variation does not emit it. See [theming](../guides/theming.md). |
18
+ | `sharedVars` | `readonly \`vars/${string}\`[]` | no | Cross-module contextual-var paths. Names follow `cssVarName`. |
19
+ | `dev` | `boolean` | no | When `true`, collectors warn about no-op handles. Default `false`. Does not affect the single-copy guard. |
20
+
21
+ Theme-tree keys must match `/^[A-Za-z_][A-Za-z0-9_]*$/`. Hyphens are rejected so hyphen-joined custom properties reverse uniquely.
22
+
23
+ ## `DistilleryEnvironment`
24
+
25
+ | Field | Type | Notes |
26
+ | ------------ | ---------------------------------------- | -------------------------------------------------------------- |
27
+ | `prefix` | `string` | Copied from options. |
28
+ | `themeScope` | `string` | Copied from options. |
29
+ | `themeVars` | `Record<string, ThemeVarDefinition>` | Derived. Emission sorts paths. |
30
+ | `sharedVars` | `ReadonlySet<\`vars/${string}\`>` | Optional. Path set from options. |
31
+ | `tokens` | `TTokens` | Derived. Surfaced as `tokens` on the authoring API. |
32
+ | `variations` | `Record<string, ResolvedThemeVariation>` | Optional. Resolved variations; absent when none were declared. |
33
+
34
+ `Distillery.tokens` aliases `environment.tokens`. `Distillery.themeVars` aliases `environment.themeVars`. `Distillery.resolveValues(scheme, variation?)` reshapes the theme into a nested literal tree for one scheme. See [read values outside CSS](../guides/non-css-surfaces.md).
35
+
36
+ ## `ThemeVarDefinition`
37
+
38
+ | Field | Type | Notes |
39
+ | -------- | ------------------- | ----------------------------------------------------------------------------- |
40
+ | `path` | `string` | Theme-tree path this definition was derived from. |
41
+ | `cssVar` | `` `--${string}` `` | Equal to `cssVarName(prefix, path)`. |
42
+ | `light` | `string` | Light color-scheme value. |
43
+ | `dark` | `string` | Dark color-scheme value. Equal to `light` when the token is scheme-invariant. |
44
+
45
+ Differing `light` / `dark` fold into `light-dark(light, dark)`.
46
+
47
+ ## `RenderStylesOptions`
48
+
49
+ Passed as the third argument to `distillery.renderStyles` / `renderStyles`.
50
+
51
+ | Field | Type | Notes |
52
+ | --------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
53
+ | `flatten` | `string` | Flatten this declared variation into `themeScope`. Default is the base. A media variation does not replace the primary block. |
54
+ | `scheme` | `'light' \| 'dark'` | Emit one scheme's literal instead of `light-dark(...)`. Applies to every emitted block. `themeValueOverrides` wins. |
55
+ | `alternates` | `readonly ThemeAlternate[]` | Extra blocks for runtime switching. Each entry emits only the variation's diff. `ThemeAlternate.variation` is the declared name. |
56
+ | `themeValueOverrides` | `Partial<Record<string, string>>` | Replace a collected token's emitted value. Wins over the flattened variation and over `scheme`. |
57
+
58
+ A non-media alternate requires `selector`. A media-conditioned alternate may omit it and uses `themeScope`. See [declare and select variations](../guides/theming.md).
59
+
60
+ Paths are `themeVars` keys (`colors/ink`), not dotted paths.
@@ -0,0 +1,11 @@
1
+ ---
2
+ navigation_title: Reference
3
+ description: Entry points, environment fields, generated API, and the OKF map.
4
+ ---
5
+
6
+ # Reference
7
+
8
+ - [Entry points](entry-points.md) — root, emotion, and testing exports
9
+ - [Environment](environment.md) — `DistilleryOptions` and the resolved environment
10
+ - [Generated API](api.md) — TypeDoc pages for the three public entry points
11
+ - [OKF map](okf-map.md) — generated map of the Distillate OKF concept graph
@@ -0,0 +1,93 @@
1
+ ---
2
+ navigation_title: OKF map
3
+ description: Generated map of the Distillate OKF concept graph.
4
+ ---
5
+
6
+ # OKF map
7
+
8
+ Generated from `.okf/distillate` by `pnpm okf:map`. Do not edit by hand.
9
+
10
+ - Concepts: 19
11
+ - Links: 30
12
+ - Isolated concepts: 0
13
+
14
+ ## Graph
15
+
16
+ ```mermaid
17
+ flowchart LR
18
+ concepts_authoring["Authoring"]:::concept
19
+ concepts_collection["Reachability collection"]:::concept
20
+ concepts_distillery["The distillery"]:::concept
21
+ concepts_naming["Naming and output"]:::concept
22
+ concepts_ordering["Ordering"]:::concept
23
+ concepts_single_copy["Single-copy invariant"]:::concept
24
+ concepts_tokens["Tokens and vars"]:::concept
25
+ entry_points_emotion["Emotion"]:::entrypoint
26
+ entry_points_root["Root"]:::entrypoint
27
+ entry_points_testing["Testing"]:::entrypoint
28
+ playbooks_bind_a_library["Bind a library"]:::playbook
29
+ playbooks_maintain_okf["Maintain OKF"]:::playbook
30
+ playbooks_migrate_from_emotion["Migrate from Emotion"]:::playbook
31
+ playbooks_read_theme_values["Read theme values"]:::playbook
32
+ playbooks_ship_an_artifact["Ship an artifact"]:::playbook
33
+ playbooks_use_the_playground["Use the playground"]:::playbook
34
+ playbooks_vs_emotion["Distillate vs CSS-in-JS"]:::playbook
35
+ reference_glossary["Glossary"]:::reference
36
+ reference_public_contract["Public contract"]:::reference
37
+ concepts_authoring --> concepts_collection
38
+ concepts_authoring --> concepts_tokens
39
+ concepts_authoring --> playbooks_use_the_playground
40
+ concepts_distillery --> playbooks_bind_a_library
41
+ concepts_naming --> concepts_distillery
42
+ concepts_naming --> playbooks_ship_an_artifact
43
+ concepts_ordering --> concepts_authoring
44
+ concepts_ordering --> concepts_naming
45
+ concepts_tokens --> concepts_distillery
46
+ concepts_tokens --> reference_public_contract
47
+ entry_points_emotion --> entry_points_root
48
+ entry_points_emotion --> playbooks_migrate_from_emotion
49
+ entry_points_root --> entry_points_emotion
50
+ entry_points_root --> entry_points_testing
51
+ playbooks_bind_a_library --> concepts_distillery
52
+ playbooks_maintain_okf --> entry_points_root
53
+ playbooks_maintain_okf --> reference_public_contract
54
+ playbooks_migrate_from_emotion --> entry_points_emotion
55
+ playbooks_migrate_from_emotion --> playbooks_bind_a_library
56
+ playbooks_read_theme_values --> concepts_distillery
57
+ playbooks_read_theme_values --> concepts_tokens
58
+ playbooks_ship_an_artifact --> concepts_naming
59
+ playbooks_use_the_playground --> concepts_authoring
60
+ playbooks_use_the_playground --> concepts_tokens
61
+ playbooks_use_the_playground --> playbooks_ship_an_artifact
62
+ playbooks_vs_emotion --> concepts_single_copy
63
+ playbooks_vs_emotion --> playbooks_migrate_from_emotion
64
+ reference_glossary --> concepts_distillery
65
+ reference_glossary --> reference_public_contract
66
+ reference_public_contract --> concepts_single_copy
67
+ classDef concept fill:#e7f5ff,stroke:#1971c2,color:#102a43
68
+ classDef entrypoint fill:#fff4e6,stroke:#e67700,color:#2d1600
69
+ classDef playbook fill:#ebfbee,stroke:#2b8a3e,color:#102a12
70
+ classDef reference fill:#f8f0fc,stroke:#9c36b5,color:#2b1033
71
+ ```
72
+
73
+ ## Concepts
74
+
75
+ - Authoring (Concept): `concepts/authoring`
76
+ - Reachability collection (Concept): `concepts/collection`
77
+ - The distillery (Concept): `concepts/distillery`
78
+ - Naming and output (Concept): `concepts/naming`
79
+ - Ordering (Concept): `concepts/ordering`
80
+ - Single-copy invariant (Concept): `concepts/single-copy`
81
+ - Tokens and vars (Concept): `concepts/tokens`
82
+ - Emotion (Entry Point): `entry-points/emotion`
83
+ - Root (Entry Point): `entry-points/root`
84
+ - Testing (Entry Point): `entry-points/testing`
85
+ - Bind a library (Playbook): `playbooks/bind-a-library`
86
+ - Maintain OKF (Playbook): `playbooks/maintain-okf`
87
+ - Migrate from Emotion (Playbook): `playbooks/migrate-from-emotion`
88
+ - Read theme values (Playbook): `playbooks/read-theme-values`
89
+ - Ship an artifact (Playbook): `playbooks/ship-an-artifact`
90
+ - Use the playground (Playbook): `playbooks/use-the-playground`
91
+ - Distillate vs CSS-in-JS (Playbook): `playbooks/vs-emotion`
92
+ - Glossary (Reference): `reference/glossary`
93
+ - Public contract (Reference): `reference/public-contract`
package/package.json CHANGED
@@ -1,6 +1,129 @@
1
1
  {
2
- "name": "@elastic/distillate",
3
- "version": "0.0.0",
4
- "description": "Placeholder to enable Trusted Publisher configuration.",
5
- "repository": { "type": "git", "url": "https://github.com/elastic/distillate" }
2
+ "name": "@elastic/distillate",
3
+ "version": "0.2.0",
4
+ "description": "Theme-agnostic CSS style engine: typed authoring with dependency capture, render-driven reachability collection, and dual readable/compact output targets. One runtime dependency: stylis.",
5
+ "license": "Elastic-2.0",
6
+ "author": "Elastic",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/elastic/distillate.git"
10
+ },
11
+ "homepage": "https://elastic.github.io/distillate/",
12
+ "bugs": {
13
+ "url": "https://github.com/elastic/distillate/issues"
14
+ },
15
+ "type": "module",
16
+ "sideEffects": [
17
+ "**/instance.ts",
18
+ "**/instance.js"
19
+ ],
20
+ "main": "./dist/cjs/index.js",
21
+ "module": "./dist/index.js",
22
+ "types": "./dist/index.d.ts",
23
+ "exports": {
24
+ ".": {
25
+ "types": "./dist/index.d.ts",
26
+ "import": "./dist/index.js",
27
+ "require": "./dist/cjs/index.js"
28
+ },
29
+ "./emotion": {
30
+ "types": "./dist/emotion.d.ts",
31
+ "import": "./dist/emotion.js",
32
+ "require": "./dist/cjs/emotion.js"
33
+ },
34
+ "./testing": {
35
+ "types": "./dist/testing.d.ts",
36
+ "import": "./dist/testing.js",
37
+ "require": "./dist/cjs/testing.js"
38
+ }
39
+ },
40
+ "files": [
41
+ "dist",
42
+ "docs",
43
+ "src",
44
+ "!src/**/*.test.ts",
45
+ "!docs/examples/**/*.test.ts",
46
+ "!src/types",
47
+ "!docs/playground/node_modules",
48
+ "!docs/playground/dist",
49
+ "LICENSE.txt",
50
+ "NOTICE.txt",
51
+ "THIRD_PARTY_LICENSES.md"
52
+ ],
53
+ "publishConfig": {
54
+ "access": "public"
55
+ },
56
+ "packageManager": "pnpm@10.17.0",
57
+ "engines": {
58
+ "node": ">=20"
59
+ },
60
+ "scripts": {
61
+ "build": "pnpm build:clean && pnpm build:compile && pnpm build:specifiers && pnpm build:compile:cjs && pnpm build:cjs-manifest",
62
+ "build:clean": "rm -rf ./dist",
63
+ "build:compile": "tsc -p tsconfig.build.json",
64
+ "build:specifiers": "tsc-alias -p tsconfig.build.json",
65
+ "build:compile:cjs": "tsc -p tsconfig.build.cjs.json",
66
+ "build:cjs-manifest": "node scripts/write_cjs_manifest.js",
67
+ "prepack": "pnpm docs:api && pnpm build",
68
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p docs/playground/tsconfig.json --noEmit",
69
+ "lint": "pnpm lint:es && pnpm lint:md",
70
+ "lint:es": "eslint .",
71
+ "lint:fix": "pnpm lint:es --fix",
72
+ "lint:md": "markdownlint-cli2",
73
+ "okf:check": "okf validate .okf/distillate && node scripts/check_okf_anchors.js && node scripts/write_okf_map.js --check",
74
+ "okf:index": "okf index .okf/distillate && pnpm okf:map",
75
+ "okf:map": "node scripts/write_okf_map.js",
76
+ "test": "vitest run && pnpm --filter @elastic/distillate-playground test",
77
+ "test:coverage": "vitest run --coverage",
78
+ "docs:api": "typedoc && node scripts/docs_api_anchors.js",
79
+ "docs:build": "pnpm docs:api && docs-builder",
80
+ "docs:dev": "pnpm docs:api && node scripts/docs_dev.js",
81
+ "docs:serve": "pnpm docs:dev",
82
+ "playground:dev": "pnpm --filter @elastic/distillate-playground dev",
83
+ "playground:build": "pnpm --filter @elastic/distillate-playground build",
84
+ "smoke:exports": "node scripts/smoke_exports.js",
85
+ "smoke:declarations": "node scripts/check_declarations.js",
86
+ "licenses:report": "node scripts/licenses_report.js",
87
+ "verify": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm smoke:exports && pnpm smoke:declarations && pnpm licenses:report --check",
88
+ "semantic-release": "node scripts/run_semantic_release.js",
89
+ "prepare": "husky"
90
+ },
91
+ "dependencies": {
92
+ "stylis": "4.4.0"
93
+ },
94
+ "devDependencies": {
95
+ "@commitlint/cli": "^19.8.1",
96
+ "@commitlint/config-conventional": "^19.8.1",
97
+ "@eslint/js": "^9.25.1",
98
+ "@rmenke/css-tokenizer-tests": "^1.2.0",
99
+ "@types/node": "^24.13.5",
100
+ "@types/stylis": "^4.2.7",
101
+ "@vitest/coverage-v8": "^4.1.11",
102
+ "eslint": "^9.25.1",
103
+ "eslint-config-prettier": "^10.1.8",
104
+ "eslint-plugin-license-header": "^0.9.0",
105
+ "eslint-plugin-prettier": "^5.5.5",
106
+ "eslint-plugin-simple-import-sort": "^14.0.0",
107
+ "globals": "^17.12.0",
108
+ "husky": "^9.1.7",
109
+ "lint-staged": "^16.1.2",
110
+ "markdownlint-cli2": "^0.23.2",
111
+ "prettier": "^3.5.3",
112
+ "semantic-release": "^25.0.9",
113
+ "tsc-alias": "^1.8.16",
114
+ "typedoc": "^0.28.13",
115
+ "typedoc-plugin-markdown": "^4.9.0",
116
+ "typescript": "^5.8.3",
117
+ "typescript-eslint": "^8.31.0",
118
+ "vitest": "^4.1.11"
119
+ },
120
+ "pnpm": {
121
+ "onlyBuiltDependencies": [
122
+ "esbuild"
123
+ ],
124
+ "overrides": {
125
+ "smol-toml": ">=1.7.1",
126
+ "dompurify": ">=3.4.13"
127
+ }
128
+ }
6
129
  }