@elastic/distillate 0.0.0 → 0.1.0

package/LICENSE.txt

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/NOTICE.txt

@@ -0,0 +1,30 @@
+Distillate
+Copyright 2026 Elasticsearch B.V.
+
+This NOTICE includes the notices and license texts of runtime dependencies shipped alongside this product.
+
+---
+
+This product depends on stylis@4.4.0, licensed under MIT.
+
+MIT License
+
+Copyright (c) 2016-present Sultan Tarimo
+
+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,142 @@
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <img src="docs/logo.svg" alt="Distillate" width="96" height="96">
+</p>
+<h1 align="center">@elastic/distillate</h1>
+<p align="center"><strong>distillate</strong> <i>n.</i> — concentrated CSS; the pure, fractionated styles extracted for a render.</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@elastic/distillate"><img src="https://img.shields.io/npm/v/@elastic/distillate.svg" alt="npm version"></a>
+  <a href="https://github.com/elastic/distillate/actions/workflows/ci.yml"><img src="https://github.com/elastic/distillate/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/elastic/distillate/blob/main/LICENSE.txt"><img src="https://img.shields.io/badge/License-Elastic%202.0-blue.svg" alt="License: Elastic License 2.0"></a>
+</p>
+<!-- markdownlint-enable MD033 -->
+
+A small, theme-agnostic engine for portable component-library artifacts where render-reachable CSS matters.
+
+Distillate is a theme-agnostic CSS style engine for component library authors who need one authored style system to emit two forms: a readable stylesheet for host applications, and a compact, tree-shaken, render-reachable CSS payload for self-contained artifacts such as emails, SVG renders, agent replies, and exported HTML. It has one runtime dependency, [stylis](https://github.com/thysultan/stylis.js) 4.4.0, and no brand assumptions: prefixes, theme tokens, and scope selectors all come from the environment you provide.
+
+If you are styling an application directly, or need per-render dynamic class names, `styled.*`, keyframes, or object styles, see the [comparison guide](https://elastic.github.io/distillate/guides/vs-emotion.html) to decide whether Distillate fits.
+
+- **Docs:** [elastic.github.io/distillate](https://elastic.github.io/distillate/)
+- **Playground:** [elastic.github.io/distillate/playground](https://elastic.github.io/distillate/playground/)
+- **Examples:** [`docs/examples/`](https://github.com/elastic/distillate/tree/main/docs/examples) (executed by the test suite, so the CSS output shown below is real)
+
+## Install
+
+```sh
+npm install @elastic/distillate
+```
+
+Requires Node.js 20 or later. The package ships as ESM (`import`) with a parallel CommonJS build (`require`) for consumers that cannot load ESM directly — see [Installation](https://elastic.github.io/distillate/getting-started/installation.html).
+
+## Quick start
+
+Bind the engine to your library with `createDistillery`. The snippets use an EUI-flavored environment to show that the engine carries no brand of its own.
+
+```ts
+import { createDistillery, cq, lightDark } from '@elastic/distillate';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: {
+      ink: lightDark('#111', '#eee'),
+      accent: lightDark('#06c', '#8cf'),
+    },
+    gap: cq('8px', '2cqi'),
+  },
+});
+```
+
+Author modules against the distillery. The derived token tree is `tokens`, typed by `TokensOf`:
+
+```ts
+const demo = distillery.createStyleModule('demo', ({ css, tokens }) => ({
+  root: css`
+    color: ${tokens.colors.ink};
+    padding: ${tokens.gap};
+  `,
+}));
+```
+
+Emit a compact artifact payload (only what a render reached) or the full readable stylesheet:
+
+```ts
+const collector = distillery.artifactCollector('compact');
+collector.use(demo.handles.root);
+distillery.renderStyles(collector);
+// => '.eui-view{--a:light-dark(#111,#eee)}.a{color:var(--a);padding:8px}'
+
+distillery.renderStyles(distillery.stylesheetCollector());
+// => '.eui-view{--eui-colors-ink:light-dark(#111,#eee)}.demo-root{color:var(--eui-colors-ink);padding:8px}'
+```
+
+## Output matrix
+
+The same source emits four kinds of CSS. Pick a **target** and a **name mode**:
+
+|                  | `readable`                                                                        | `compact`                                                                                             |
+| ---------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **`stylesheet`** | Public stylesheet: `.demo-root`, `--eui-colors-ink`. Use `stylesheetCollector()`. | Minified names for the full sheet. Rare; compact names only pay off when HTML and CSS ship together.  |
+| **`artifact`**   | Readable names, tree-shaken to the handles a render collected.                    | Minimal payload: `.a`, `--b`, unused variants and tokens dropped. Use `artifactCollector('compact')`. |
+
+Collection is a side effect of rendering: resolving a handle pulls it in, which auto-activates any `rule` / `media` / `container` whose selector dependencies are all collected. Variant entries stay off always-on collection until a renderer names them. See [Naming and output](https://elastic.github.io/distillate/concepts/naming-and-output.html).
+
+## Entry points
+
+| Import                        | What it is                                                                                                                         |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `@elastic/distillate`         | Engine: `createDistillery`, authoring (`css`, `rule`, `media`, `container`, `variants`, `mapDomain`), tokens, collector, renderer. |
+| `@elastic/distillate/emotion` | `@emotion/css`-shaped `css` / `cx` / `injectGlobal` over the same registry, plus `createDomSink`.                                  |
+| `@elastic/distillate/testing` | `assertVarRefsHaveDeclarations` / `findVarRefViolations`. No third-party dependency.                                               |
+
+`./testing` is the only entry that does not reach `stylis`. Nested `css` templates walk stylis `compile()` output; the pin is **4.4.0** exactly.
+
+## Emotion-style authoring
+
+```ts
+import { createEmotion } from '@elastic/distillate/emotion';
+
+const { css, cx, injectGlobal } = createEmotion(distillery);
+
+const card = css`
+  color: var(--eui-colors-ink);
+  &:hover {
+    color: var(--eui-colors-accent);
+  }
+  @media (min-width: 600px) {
+    padding: 8px;
+  }
+`;
+
+// <div className={cx('surface', card)} />
+```
+
+`String(card)` is the readable class name and does not collect. Passing the same handle through a collector's `resolveClassName` collects and compacts like a native handle. `createDomSink` manages one `<style>` element for the readable stylesheet.
+
+To override, compose by interpolating a base handle into a new tagged template so declarations re-target the composing class (last wins). Render order is sort order, not registration order. Object styles, `keyframes`, and `@container` inside a `css` template are not supported; use the `container(...)` factory for container queries.
+
+## Single-copy requirement
+
+The engine keeps module-scope caches (variant markers, dependent-entry maps, and the emotion per-registry state), so exactly one copy of `@elastic/distillate` may load at runtime. Consumers that bundle must externalize the package.
+
+A second copy with a different identity token registers a console warning at import (`Symbol.for('elastic.distillate.instance')`). It warns rather than throws because two copies degrade output — `variants(...)` tree-shaking silently fails — without crashing. The `sideEffects` field lists `**/instance.ts` and `**/instance.js` so the guard survives both source and built consumption. HMR and a fresh test registry can also warn, because the token is regenerated on every load.
+
+## Public contract
+
+- `prefix`, module names, handle-path keys, and `vars(...)` group and key names must each be a CSS identifier segment: a letter or underscore, then letters, digits, hyphens, or underscores. Theme-tree keys omit hyphens: `/^[A-Za-z_][A-Za-z0-9_]*$/`.
+- Readable class names are `${moduleName}-${path.join('-')}`. Readable custom properties are `cssVarName(prefix, path)`. Distinct authored paths that join to the same string throw at `createDistillery` or `registerModule`.
+- Template interpolations are spliced into CSS verbatim. Authored CSS must never be bound to untrusted input.
+- Differing `lightDark` values fold into `light-dark(...)`.
+
+## Docs and examples
+
+- [Getting started](https://elastic.github.io/distillate/getting-started/index.html)
+- [Concepts](https://elastic.github.io/distillate/concepts/index.html)
+- [Guides](https://elastic.github.io/distillate/guides/index.html) — including [Distillate vs CSS-in-JS](https://elastic.github.io/distillate/guides/vs-emotion.html) and [React renderer integration](https://elastic.github.io/distillate/guides/react-renderer.html)
+- [API reference](https://elastic.github.io/distillate/reference/index.html)
+- [Playground](https://elastic.github.io/distillate/playground/)
+- Runnable samples: [`docs/examples/`](https://github.com/elastic/distillate/tree/main/docs/examples)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Support: [`SUPPORT.md`](SUPPORT.md)