@cssints/mise-en-mode 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+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

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @cssints/mise-en-mode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The look layer of Mise en Mode for [cssints](../../README.md): a **look** is a theme set on a `data-mode` scope, and looks
+from three sources are resolved by the Mode Contract. It is one call member of `cssints/plugin` `scope()` (positional
+arguments `$tokens` and `$overrides`, returning themes), so a look is checked against your token set, and `check.contrast` sees it.
+No runtime.
+
+```ts
+import { createTokens } from "cssints" with { type: "cssints" };
+import { look } from "@cssints/mise-en-mode" with { type: "cssints" };
+
+const t = createTokens({
+  color: { $type: "color", bg: { $value: "#ffffff" }, fg: { $value: "#111111" } },
+});
+
+// look(tokens, expression, source, overrides, { scope? })
+look(t, "dark", "app", { color: { bg: "#0b0b0f", fg: "#f3f4f6" } });
+look(t, "dark", "viewer", { color: { bg: "#101018" } });
+look(t, "hero", "author", { color: { bg: "#123456" } }, { scope: "article.post" });
+```
+
+```css
+@layer app, author, viewer;
+@layer app {
+  :where([data-mode="dark"], [data-mode~="dark/color"]) {
+    --color-bg: #0b0b0f;
+    --color-fg: #f3f4f6;
+  }
+}
+@layer viewer {
+  :where([data-mode="dark"], [data-mode~="dark/color"]) {
+    --color-bg: #101018;
+  }
+}
+@layer author {
+  @scope (article.post) {
+    :where([data-mode="hero"], [data-mode~="hero/color"]) {
+      --color-bg: #123456;
+    }
+  }
+}
+```
+
+## The contract, as the package does it
+
+- **Sources (Rule 5).** `source` is `"app"`, `"author"` or `"viewer"`: the layers `app < author < viewer`, declared once
+  after the engine's own (`layers()` of cssints), so a look beats the engine's `:root` fallbacks and a viewer's look beats an
+  author's over the app's. Each variable fills from the most preferred source that sets it: the viewer look above sets only
+  `--color-bg`, and `--color-fg` still comes from the app look.
+- **Aspects and fragments (Rule 4).** An aspect is a top-level group of the token set (`color`, `typography`). A look's
+  `overrides` are split by it, one rule per aspect, and each rule matches the bare marker or its fragment:
+  `data-mode="dark"` applies every aspect, `data-mode="dark/color"` only the color group.
+- **Expressions.** `expression` is a `<custom-ident>` or a string; a dotted reverse-DNS key is quoted at the call,
+  `look(t, '"com.alice.midnight"', "author", …)`, and matched exactly.
+- **Containment (Rule 7).** `{ scope: "article.post" }` wraps the rule in `@scope (article.post) { … }`, so a foreign look
+  cannot repaint the host's chrome. It is a selector, checked by the build.
+- **Overrides** are `createGlobalTheme`'s: values by token path, each of the token's type, `{color.bg}` references allowed,
+  checked in the types as you type and again at build time (`color.bg value "blu" is not a <color>`, located at the call).
+  The aliases that depend on an overridden token are declared again on the scope.
+- **Contrast.** The looks of one expression and aspect are one cascade to `check.contrast`: they are laid over each other in
+  layer order, so a viewer look that sets only the text colour is checked on the _app_ look's background, and a poor
+  combination fails the build.
+
+A look prints no class: call it at a module's top level, like `createGlobalTheme`. Its types are inferred from the `scope()`
+definition in `src/index.ts`: there is no types file.
+
+Changed from `cssints/mise-en-mode`, which this package replaces: `look(expression, source, declarations, { scope })` took
+raw custom-property declarations (`"--color-bg": "#000"`) that nothing checked; it is now `look(tokens, expression, source,
+overrides, { scope })` with the token set first and the overrides by token path, so the declarations are checked, the
+aliases are re-derived and contrast sees them. Aspects are the groups of the tokens, no longer a table of `--color-` and
+`--typography-` prefixes, and a look emits themes, no longer globals.
+
+```bash
+cd packages/mise-en-mode && bun run test   # fixtures through the engine (output, errors, contrast), and the type test via bun run typecheck
+```
+
+## Credits
+
+Mise en Mode is an open style standard on AT Protocol (<https://standard.mode.place>), and the Mode Contract is its
+rules: `data-mode` scopes, the layers `app < author < viewer`, aspects. This package is an implementation of the
+contract on `scope()`; no code of the standard's site is copied.

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+//#region src/index.d.ts
+declare const mise: import("cssints/plugin").Scope<"mise-en-mode", {
+  readonly "#sources": {
+    readonly layers: readonly ["app", "author", "viewer"];
+  };
+  readonly look: {
+    readonly args: readonly ["$tokens", "<custom-ident> | <string>", "app | author | viewer", "$overrides", {
+      readonly "scope?": "$selector";
+    }];
+    readonly uses: readonly ["sources"];
+  };
+}>;
+/**
+ * `look(tokens, expression, source, overrides, { scope? })`: the theme of one `data-mode` expression, in the layer of its
+ * `source` (`"app"`, `"author"` or `"viewer"`), so a viewer's look fills over an author's over the app's, value by value.
+ * `overrides` are values by token path, split by their top-level groups (aspects): `data-mode="dark"` takes every aspect,
+ * `data-mode="dark/color"` only the color group. They are checked against `tokens` in the types and at build time, and
+ * `check.contrast` reads them with the other looks of the expression. With `scope` the look is confined to that subtree
+ * (`@scope`, Rule 7). A dotted reverse-DNS expression is quoted: `look(t, '"com.alice.midnight"', "author", { … })`. Call it
+ * at a module's top level; it prints no class.
+ */
+export declare const look: ReturnType<typeof mise.export>["look"];
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,37 @@
+import { scope } from "cssints/plugin";
+//#region src/index.ts
+const selector = (expression, aspect) => `:where([data-mode="${expression}"], [data-mode~="${expression}/${aspect}"])`;
+/**
+* `look(tokens, expression, source, overrides, { scope? })`: the theme of one `data-mode` expression, in the layer of its
+* `source` (`"app"`, `"author"` or `"viewer"`), so a viewer's look fills over an author's over the app's, value by value.
+* `overrides` are values by token path, split by their top-level groups (aspects): `data-mode="dark"` takes every aspect,
+* `data-mode="dark/color"` only the color group. They are checked against `tokens` in the types and at build time, and
+* `check.contrast` reads them with the other looks of the expression. With `scope` the look is confined to that subtree
+* (`@scope`, Rule 7). A dotted reverse-DNS expression is quoted: `look(t, '"com.alice.midnight"', "author", { … })`. Call it
+* at a module's top level; it prints no class.
+*/
+const look = scope("mise-en-mode", {
+	"#sources": { layers: [
+		"app",
+		"author",
+		"viewer"
+	] },
+	look: {
+		args: [
+			"$tokens",
+			"<custom-ident> | <string>",
+			"app | author | viewer",
+			"$overrides",
+			{ "scope?": "$selector" }
+		],
+		uses: ["sources"]
+	}
+}).build({ look: (tokens, expression, source, overrides, options) => ({ themes: Object.entries(overrides).map(([aspect, values]) => ({
+	tokens,
+	overrides: { [aspect]: values },
+	selector: selector(expression.replace(/^"|"$/g, ""), aspect),
+	layer: source,
+	scope: options.scope
+})) }) }).export().look;
+//#endregion
+export { look };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@cssints/mise-en-mode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Mise en Mode for cssints: looks are themes in the layers app < author < viewer, set on data-mode scopes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/mise-en-mode"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}