cssints 0.3.1 → 0.5.0

package/docs/API.md

@@ -1084,8 +1084,10 @@ More plugins on `scope()`, each a package of its own with its rules and limits i
 | [`@cssints/layout`](../packages/layout/README.md)           | `stack()`, `cluster()`, `sidebar()`, `switcher()`, `cover()`, `autoGrid()`                     | Every Layout primitives as chain members                                                                                                                                  |
 | [`@cssints/fonts`](../packages/fonts/README.md)             | `font(family, { provider, ... })` → `.family()`, `.trim()`                                     | `@font-face` and a metric-matched fallback face; cap-height trimming by `text-box`, else capsize's margins                                                                |
 | [`@cssints/reset`](../packages/reset/README.md)             | `reset({ media?, prose? })`                                                                    | A modern reset in a top-level `@layer reset` declared before the engine's, below every style; `@cssints/reset/<baseline group>` keeps only the declarations of that group |
-| [`@cssints/tokens`](../packages/tokens/README.md)           | `/open-props`, `/radix`, `/flexoki`, `/reasonable-colors`                                      | DTCG data for `createTokens`                                                                                                                                              |
+| [`@cssints/tokens`](../packages/tokens/README.md)           | `/open-props`, `/radix`, `/flexoki`, `/reasonable-colors`, `/madoromi`                         | DTCG data for `createTokens`                                                                                                                                              |
 | [`@cssints/gradient`](../packages/gradient/README.md)       | `gradient(kind, direction, from, to, easing?, stops?)`                                         | Eased colour stops mixed in oklab at build time                                                                                                                           |
+| [`@cssints/gradient-2d`](../packages/gradient-2d/README.md) | `meshGradient(mesh)`, `freeformGradient(points)`                                               | `mesh-gradient()` / `freeform-gradient()` where the browser has them, else a runtime's canvas (this package's algorithms; lines and shapes not yet)                       |
+| [`@cssints/color-names`](../packages/color-names/README.md) | `named(name)`, `colorNames.<sector>(name)`, `/nearest`                                         | The Color Name List (31,939 names) as hex colours; the ten sector members keep an editor's completion short, `nearest()` is the build-time reverse lookup                 |
 | [`@cssints/motion`](../packages/motion/README.md)           | `motion().preset().duration().delay().easing()`                                                | Animation presets over `keyframes()`, with reduced motion                                                                                                                 |
 | [`@cssints/squircle`](../packages/squircle/README.md)       | `squircle().radius()`                                                                          | `corner-shape: squircle`, else a CSS `mask` of the same shape                                                                                                             |
 | [`@cssints/reveal`](../packages/reveal/README.md)           | `reveal().preset().range().duration().easing()`                                                | motion's entrance presets on `animation-timeline: view()`; for other targets a script plays it once on entry (delivered by the runtime)                                   |
@@ -1267,7 +1269,15 @@ const { ratio, text } = await Effect.runPromise(contrast("#777", "white"));
 - **`contrast(foreground, background)`** is the WCAG 2.x ratio of `css.check.contrast` (see Themes): culori reads the colour, one outside sRGB is clipped to it. A colour it cannot read (`currentColor`, a `var()`) or a translucent one fails with a `ContrastError` (`colour`, `message`).
 - **`loweredOf(property, value, warning)`** answers what a build asks before it says a support warning ("No warning for what LightningCSS lowers", under Errors): the value of the first declaration LightningCSS writes for the targets of the warning, or `undefined` when it leaves the feature in place (`text-wrap`, a `var()` inside the value). `warning` is one of `support()` of `@cssints/css-grammar/support`; a custom property is `--name`. For `color: oklch(70% 0.2 330)` and chrome 100 it is a hex colour, so a build does not warn.
 
-### TUI: `cssints/tui` (decided 2026-10-10, cssints-3ff7)
+### TUI: `cssints/tui` (decided 2026-10-10, cssints-3ff7; deprecated 2026-10-21)
+
+> **Deprecated.** The members below still compile, and `@cssints/tui` still applies them, but importing it now prints
+> one warning, and the package will not get new members. A terminal app builds on
+> [cssints-native](https://github.com/alexeiaccio/cssints-native) instead: `terminal/` takes `cssints/clay` styles
+> (`generator/clay-header.ts` → a C header), lays them out with [Clay](https://github.com/nicbarker/clay) and draws them
+> into character cells on [termbox2](https://github.com/termbox/termbox2), with the keyboard focus layer in C
+> (`terminal/focus.c`). What carries over and what does not, and the commands that run it, are in
+> [packages/tui/README.md](../packages/tui/README.md); `docs/map.md` step 6 of that project is the full account.
 
 A terminal app writes its styles with `cssints/tui`, and the same Vite plugin compiles them to **prop objects** for terminal renderables, not to classes: there is no sheet and no cascade. `@cssints/tui` applies them (states, the mouse pointer, the caret, themes); its adapters are [OpenTUI](https://opentui.com) and [@bomb.sh/tty](https://bomb.sh/docs/tty/api/). The design, the full property table and what is out of scope are in [research/tui.md](research/tui.md).
 
@@ -1374,6 +1384,128 @@ process.stdin.on("data", (bytes) => dispatch(input.scan(follow.feed(bytes)).even
 - **Live in the browser** (cssints-ey13, 2026-10-11). [The TUI page](https://cssints.dev/tui) of this site runs apps/csssky-tui's styles on `@cssints/tui/bomb` in a real terminal: Ghostty's emulator compiled to WebAssembly (ghostty-web) draws csssky's feed and thread from its recorded fixtures, with keys and the mouse. The page is the terminal: it answers the system theme's queries (OSC 10, 11, 4, `CSI ? 996 n`) from the site's display settings and reports a change of them (mode 2031), so the theme is solved again as the palette or the mode changes. OpenTUI is not shown: its renderer is native Zig over `bun:ffi`. On a change notification, `followSystemTheme` of `@cssints/tui/bomb` asks the colours again (`COLOURS` of `@cssints/tui/system`), not the scheme report: its reply is the same sequence as a notification, and asking it looped with a terminal that answers it.
 - **Cost.** A colour member costs what the same web member costs in the types (the `color` grammar); `bench/tui.ts` is 184k instantiations (tsc) for 16 calls and a token set. No terminal HMR in this version. The system theme brings culori's rgb, oklab, oklch and okhsl modes to the app (45 kB unminified in csssky-tui's bundle).
 
+### Clay: `cssints/clay` (2026-10-19, cssints-iwey)
+
+A native UI laid out by [Clay](https://github.com/nicbarker/clay), with no browser and no JS where it runs (an ESP32's firmware), writes its styles with `cssints/clay`. The same Vite plugin compiles each site to an object literal shaped as Clay's own structs, and `header()` prints a module of them as C initializers:
+
+```ts
+import * as css from "cssints/clay" with { type: "cssints" };
+
+export const pill = css.cn(
+  css.width(200),
+  css.height(38),
+  css.justifyContent("center"),
+  css.alignItems("center"),
+  css.bg("rgb(36 40 52)"),
+  css.borderRadius(19),
+  css.border(1, "#969baa"),
+);
+export const label = css.cn(css.color("#ebebf0"), css.fontSize(14));
+css.width("10rem"); // error: Clay counts pixels
+css.boxShadow("0 0 1px red"); // error: no such member in Clay
+```
+
+```c
+static const Clay_ElementDeclaration pill = { .layout = { .sizing = { .width = { .size = { .minMax = { 200, 200 } }, .type = CLAY__SIZING_TYPE_FIXED }, ... }, .backgroundColor = { .r = 36, .g = 40, .b = 52, .a = 255 }, ... };
+static const Clay_TextElementConfig label_text = { .textColor = { .r = 235, .g = 235, .b = 240, .a = 255 }, .fontSize = 14 };
+```
+
+```c
+CLAY(CLAY_ID("Units"), pill) { CLAY_TEXT(CLAY_STRING("switch to g"), label_text); }
+```
+
+- **Members**: `width`, `height` (pixels, `N%`, `auto` for Clay's FIT, `stretch` for GROW), `padding`/`p` and the sides, `gap` (`childGap`), `flexDirection` (`row`, `column`), `justifyContent` and `alignItems` (start, center, end: Clay's `childAlignment`, the axis from `flexDirection`), `backgroundColor`/`bg`, `borderRadius`, `border(width, colour)`, `borderWidth`, `borderColor`, `overflow("hidden")` (`clip`), `float()` (`floating`, below), `image(src, { width, height, fit })` (`image`, below), and for text `color`, `fontSize`, `letterSpacing`, `lineHeight`, `textAlign`, `whiteSpace` (`wrapMode`); `cn` merges, a later prop wins. Any other property is not a member.
+- **Pixels.** A number or `"Npx"`; padding, gap and border widths are whole numbers (`uint16_t` in Clay). Another unit is a type error and a build error.
+- **Colours** are checked by the web's `color` grammar, or are colour tokens of cssints/clay's `createTokens`, and are written as 0-255 `r g b a`.
+- **`header(exports)`** prints a `Clay_ElementDeclaration` per export and, for one with text props, a `Clay_TextElementConfig` named `<name>_text`. A field it does not set is zero, which is Clay's default.
+- **States**: `hover`, `focus`, `active` wrap styles. Clay has no states, so the literal has an overlay per state (`":active": { backgroundColor }`, the fields the state sets, at their values over the base), and `header()` prints the whole declaration again, `<name>_active` (`<name>_hover_text` for text): the page asks Clay and picks one, nothing is merged in C. States do not nest.
+- **Tokens and themes**: `createTokens` and `createGlobalTheme(tokens, name, overrides)` of cssints/clay, on tables of their own (a web or terminal token is not a Clay one, and a theme of one is a build error). Resolved at build time: a site has its colours at the tokens' values and, under `themes`, what each theme changes. `header()` prints every style of a module with a theme again, the theme's name last (`units_light`, `units_active_light`, `title_text_light`), so a page switches at run time by a suffix. A style sees the themes evaluated before it: declare them first, or in a module it imports.
+- **Fonts**: `fonts("Roboto", "Mono")` is the order of the app's font array; `.Mono` is a style that sets Clay's `fontId` to 1, and `header()` prints the order as an enum, `font_Roboto = 0, font_Mono = 1` (the export's name, then the font's).
+
+```ts
+import * as css from "cssints/clay" with { type: "cssints" };
+
+export const t = css.createTokens({
+  color: { $type: "color", surface: { $value: "rgb(36 40 52)" }, pressed: { $value: "#ffc878" } },
+});
+css.createGlobalTheme(t, "light", { color: { surface: "white" } });
+export const font = css.fonts("Roboto", "Mono");
+
+export const units = css.cn(
+  css.width(200),
+  css.bg(t.color.surface),
+  css.active(css.bg(t.color.pressed)),
+);
+export const label = css.cn(font.Mono, css.fontSize(14));
+css.cn(font.Serif); // error: not one of the fonts
+```
+
+```c
+#define T(name) (light ? name##_light : name)
+CLAY(CLAY_ID("Units"), pressed ? T(units_active) : T(units)) { CLAY_TEXT(CLAY_STRING("switch to g"), label_text); }
+```
+
+- **Floating elements**: `float({ ... })` fills Clay's `floating`, the foundation of menus, popovers and dialogs. Every option is optional, and what it leaves out is Clay's own default, so `header()` prints only what is set (`float()` alone is `{ .attachTo = CLAY_ATTACH_TO_PARENT }`). The name is `float` as in CSS: it is a valid binding, and no other Clay member shares it.
+
+  | Option                        | Clay field                                                                                                                                                 | Default                                                   |
+  | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+  | `attach: { element, parent }` | `attachPoints`: which point of the float sits on which point of its parent, each `"left top"`, `"center center"`, `"right bottom"`, ... (x, then y)        | `left top` on `left top`                                  |
+  | `parent: "Units"`             | `parentId` and `attachTo = ELEMENT_WITH_ID`: the string of the parent's `CLAY_ID("Units")` (ASCII; a `CLAY_IDI` or local id is not one)                    | the element the float is a child of (`attachTo = PARENT`) |
+  | `root: true`                  | `attachTo = ROOT`: absolute positioning, a dialog on the screen (not with `parent`)                                                                        | off                                                       |
+  | `offset: { x, y }`            | `offset`: pixels from where `attach` puts it; a negative number goes left or up                                                                            | 0, 0                                                      |
+  | `expand: { width, height }`   | `expand`: pixels the float's own box grows by, its children's not; not negative                                                                            | 0, 0                                                      |
+  | `zIndex`                      | `zIndex`: a whole number, `int16_t`; floats draw in ascending order, with their children                                                                   | 0                                                         |
+  | `capture: false`              | `pointerCaptureMode = PASSTHROUGH`: the pointer reaches what lies under the float (`true` is `CAPTURE`)                                                    | `true`                                                    |
+  | `clip: "parent"`              | `clipTo = ATTACHED_PARENT`: clipped to the box its parent is clipped to (`"none"` is `CLIP_TO_NONE`; with `root` it has nothing to clip to, a build error) | `"none"`                                                  |
+
+  `parentId` is printed as a number, the hash of the id (`Clay__HashString(id, 0)` computed at build time), because `CLAY_ID()` is a call and a `static const` initializer takes constants. A misspelt id is Clay's own `FLOATING_CONTAINER_PARENT_NOT_FOUND` error at run time. A bad value, an option that does not exist, a negative `expand`, a non-ASCII id are build errors (the types catch what a type can: a point such as `"top left"`, an unknown option). Two floats merge in a `cn()` as the other members do: the later one's options win and the rest stay; a state (`hover(float(...))`) is a declaration of its own.
+
+```ts
+import * as css from "cssints/clay" with { type: "cssints" };
+
+export const menu = css.cn(
+  css.width(160),
+  css.bg("#242834"),
+  css.float({ parent: "Units", attach: { parent: "left bottom" }, offset: { y: 4 }, zIndex: 10 }),
+);
+export const dialog = css.float({
+  root: true,
+  attach: { element: "center center", parent: "center center" },
+});
+css.float({ attach: { element: "top left" } }); // error: a point is x, then y
+```
+
+```c
+static const Clay_ElementDeclaration menu = { .layout = { ... }, .backgroundColor = { ... }, .floating = { .offset = { .x = 0, .y = 4 }, .parentId = 3516868942u, .zIndex = 10, .attachPoints = { .element = CLAY_ATTACH_POINT_LEFT_TOP, .parent = CLAY_ATTACH_POINT_LEFT_BOTTOM }, .attachTo = CLAY_ATTACH_TO_ELEMENT_WITH_ID } };
+```
+
+- **Images**: `image(src, { width, height, fit })` fills Clay's `image`: the element that draws a picture, its children none. Clay 1.0's `Clay_ImageElementConfig` is one field, `void *imageData`, which Clay passes to the renderer untouched, so the path of the image travels in it (the desktop renderer loads it with ThorVG; the firmware's own renderer is still the app's to write). Older Clay also kept the image's `sourceDimensions` there; 1.0 has no such field, so the image's own size becomes the element's box, and `fit` is Clay's `aspectRatio`:
+
+  | Option                     | Clay field                                                                                                       | Default   |
+  | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------- |
+  | `"glyph.png"` (argument 1) | `image.imageData`: the path, printed as a C string, `(void *)"glyph.png"`                                        | —         |
+  | `width`, `height`          | `layout.sizing`: the image's size, `CLAY_SIZING_FIXED`, whole pixels (a later `width` of a `cn()` wins)          | —         |
+  | `fit: "contain"`           | `aspectRatio`: width / height, which Clay uses where it has one side to derive the other's (`"fill"` stretches)  | `"fill"`  |
+
+  A path that is not a non-empty string, a size that is not a positive whole number, an option that does not exist are build errors. `fit` is how the picture meets a box another style gives it: `fill` (CSS's `object-fit` default) stretches it, `contain` keeps the image's proportions.
+
+```ts
+import * as css from "cssints/clay" with { type: "cssints" };
+
+export const glyph = css.image("examples/sensors/glyph.png", { width: 32, height: 32 });
+export const logo = css.cn(
+  css.image("assets/logo.png", { width: 64, height: 32, fit: "contain" }),
+  css.width("stretch"),
+);
+css.image("logo.png", { width: 64, height: 32, fit: "cover" }); // error: fill or contain
+```
+
+```c
+static const Clay_ElementDeclaration glyph = { .layout = { .sizing = { .width = { .size = { .minMax = { 32, 32 } }, .type = CLAY__SIZING_TYPE_FIXED }, .height = { .size = { .minMax = { 32, 32 } }, .type = CLAY__SIZING_TYPE_FIXED } } }, .image = { .imageData = (void *)"examples/sensors/glyph.png" } };
+```
+
+- **Not yet**: min and max sizes, derived colour tokens (`color-mix()` of tokens: a colour Clay is given must parse as one), a theme under a condition (a theme is a name; `media()` has no meaning on a board).
+
 ### Export groups: `cssints/widely-available`, `cssints/css-grid-2`, … (decided 2026-10-11, cssints-n7z3)
 
 A group is a subpath of `cssints` that exports the members of `cssints` which a set of CSS features has, and refuses a value that holds a feature outside the set. It is the same import (`with { type: "cssints" }`), the same members, the same classes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssints",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "CSS in TypeScript: typed css.* calls compiled to atomic CSS at build time (a Vite plugin)",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,10 @@
       "types": "./dist/tui-types.d.mts",
       "default": "./dist/tui.mjs"
     },
+    "./clay": {
+      "types": "./dist/clay-types.d.mts",
+      "default": "./dist/clay.mjs"
+    },
     "./devtools-link": {
       "types": "./dist/devtools-link.d.mts",
       "default": "./dist/devtools-link.mjs"
@@ -64,7 +68,7 @@
     }
   },
   "dependencies": {
-    "@cssints/css-grammar": "^0.3.1",
+    "@cssints/css-grammar": "^0.5.0",
     "culori": "^4.0.2",
     "effect": "4.0.0",
     "happy-dom": "^20.14.5",

package/skills/cssints/references/plugins.md

@@ -62,6 +62,18 @@ a suggestion.
 **`@cssints/gradient`**: `backgroundImage(gradient("linear", "to bottom", "#000", "transparent", "ease-in-out", 5))`:
 eased stops mixed in oklab. Each argument its own string; the direction is one string (`"to bottom"`).
 
+**`@cssints/gradient-2d`**: `meshGradient("red, blue; green, yellow")` (rows from the top of the box down, separated by
+`;`, stops by `,`) and `freeformGradient("red top left, gold 4 60% 40%, yellow bottom right")` (points, an optional
+weight before the position). One string per call. Where the browser has `mesh-gradient()`, the declaration is native;
+elsewhere a runtime the build adds draws the same points on a canvas, so it needs a script.
+
+**`@cssints/color-names`**: `color(named("tangerine"))` is `#ff9300`. `colorNames.<sector>(name)` is the same name
+restricted to one sector (`red`, `orange`, `yellow`, `green`, `cyan`, `blue`, `purple`, `pink`, `brown`, `neutral`), so
+completion stays short; the colour word in the name picks the sector. An unknown name is a build error with the nearest
+one, and a name outside the sector is one that names the sectors it is in. The list's hex wins over the CSS keyword's
+(`named("green")` is `#00ff00`; `color("green")` is the CSS one). `@cssints/color-names/nearest` maps a hex to the
+closest name at build time.
+
 **`@cssints/placeholder`**: `backgroundImage(placeholder("src/hero.jpg"))` (a gradient of the image's colours) or
 `{ mode: "thumbhash" }` (a tiny PNG; pair it with `backgroundSize("cover")`). JPEG and PNG only; the path is relative
 to the working directory.

package/dist/group-common-9zpBxfUF.d.mts

@@ -1 +0,0 @@
-import "./theme-types-Bqv0Ggz_.mjs";