cssints 0.4.0 → 0.5.0

package/README.md

@@ -148,7 +148,7 @@ export const Row = ({ wide, on }: { wide?: boolean; on?: boolean }) => (
 
 ### In a terminal
 
-`import * as css from "cssints/tui" with { type: "cssints" }` gives the members a terminal has (cells, colours, borders, flex, states, `cursor`), and the plugin compiles them to prop objects for [OpenTUI](https://opentui.com) renderables instead of classes; `@cssints/tui` applies their states and themes: [packages/tui](packages/tui/README.md), docs/API.md "TUI".
+`import * as css from "cssints/tui" with { type: "cssints" }` gives the members a terminal has (cells, colours, borders, flex, states, `cursor`), and the plugin compiles them to prop objects for [OpenTUI](https://opentui.com) renderables instead of classes; `@cssints/tui` applies their states and themes: [packages/tui](packages/tui/README.md), docs/API.md "TUI". The package to apply them, `@cssints/tui`, is **deprecated** in favour of [cssints-native](https://github.com/alexeiaccio/cssints-native)'s `terminal/` target (Clay in cells, termbox2); its README says what carries over and how to run the replacement.
 
 More in [docs/API.md](docs/API.md): property names and short names, `flex()` and `grid()` chains, conditions and layers, tokens and themes, `cn` and `cv`, and the errors you can get.
 
@@ -181,6 +181,7 @@ and Cursor. The skills use it when it is configured and work without it.
 | `packages/css-grammar`          | Type-level recognizer and its runtime twin over mdn-data grammars, Typed OM values, browser support and prose rules                                     |
 | `packages/icons`                | `@cssints/icons`: icons from iconify JSON collections or SVG folders, a mask style with no runtime                                                      |
 | `packages/mise-en-mode`         | `@cssints/mise-en-mode`: looks as themes in the layers app < author < viewer, on `data-mode` scopes, checked against the tokens and by `check.contrast` |
+| `packages/tui`                  | `@cssints/tui` (**deprecated**): the runtime of `cssints/tui` styles on OpenTUI and @bomb.sh/tty; cssints-native's `terminal/` replaces it              |
 | `apps/demo`                     | React demo of every 0.1 feature                                                                                                                         |
 | `apps/docs`                     | The documentation site: this file and `docs/API.md` as pages, with search and type hovers (`cd apps/docs && bun run dev`)                               |
 | `docs/research`, `docs/archive` | Comparisons with other libraries; outdated plans                                                                                                        |

package/dist/clay-types.d.mts

@@ -40,6 +40,18 @@ export type FloatOptions = {
   root?: boolean;
   parent?: never;
 });
+/** The options of `image()`: the image's size in pixels, and how it fills its box. */
+export type ImageOptions = {
+  /** The image's width in whole pixels: the element's box starts at the image's own size. */
+  width: Px;
+  /** The image's height in whole pixels. */
+  height: Px;
+  /**
+   * `"fill"` stretches the image into a box another style gives it; `"contain"` sets Clay's `aspectRatio` to the
+   * image's, so a box that grows keeps its proportions. Default: `"fill"`, as CSS's `object-fit`.
+   */
+  fit?: "fill" | "contain";
+};
 interface Rgba {
   r: number;
   g: number;
@@ -88,6 +100,13 @@ export interface ClayFields {
     horizontal: number;
     vertical: number;
   };
+  /** `Clay_ImageElementConfig`: `imageData` is the path of the image, which the renderer loads. */
+  image?: {
+    imageData: string;
+  };
+  aspectRatio?: {
+    aspectRatio: number;
+  };
   floating?: {
     offset?: {
       x: number;
@@ -181,6 +200,12 @@ export declare const whiteSpace: One<"normal" | "pre-line" | "nowrap">;
  * the one `parent` names, or to the root. A float is out of the flow of its siblings and of its parent's size.
  */
 export declare const float: (options?: FloatOptions) => ClayStyle;
+/**
+ * An image element: the path it is loaded from, and its size in whole pixels, which is the element's box. `fit`
+ * `"contain"` keeps its proportions in a box another style grows (Clay's `aspectRatio`); the path is passed to the
+ * renderer as `imageData`.
+ */
+export declare const image: (src: string, options: ImageOptions) => ClayStyle;
 /** Merges styles in argument order: a later prop wins. */
 export declare const cn: (...styles: ClayStyle[]) => ClayStyle;
 /** Under the pointer: header() prints the style with it as `<name>_hover`. States do not nest. */

package/dist/clay.d.mts

@@ -25,7 +25,7 @@ export declare const active: (...styles: unknown[]) => ClayNode;
  * @returns {Record<string, unknown>} a style per font, by name, and the list
  */
 export declare const fonts: (...names: unknown[]) => Record<string, unknown>;
-export declare const backgroundColor: ((...parts: unknown[]) => ClayNode) | undefined, bg: ((...parts: unknown[]) => ClayNode) | undefined, color: ((...parts: unknown[]) => ClayNode) | undefined, borderColor: ((...parts: unknown[]) => ClayNode) | undefined, width: ((...parts: unknown[]) => ClayNode) | undefined, height: ((...parts: unknown[]) => ClayNode) | undefined, padding: ((...parts: unknown[]) => ClayNode) | undefined, p: ((...parts: unknown[]) => ClayNode) | undefined, paddingInline: ((...parts: unknown[]) => ClayNode) | undefined, paddingBlock: ((...parts: unknown[]) => ClayNode) | undefined, paddingTop: ((...parts: unknown[]) => ClayNode) | undefined, paddingRight: ((...parts: unknown[]) => ClayNode) | undefined, paddingBottom: ((...parts: unknown[]) => ClayNode) | undefined, paddingLeft: ((...parts: unknown[]) => ClayNode) | undefined, pt: ((...parts: unknown[]) => ClayNode) | undefined, pr: ((...parts: unknown[]) => ClayNode) | undefined, pb: ((...parts: unknown[]) => ClayNode) | undefined, pl: ((...parts: unknown[]) => ClayNode) | undefined, gap: ((...parts: unknown[]) => ClayNode) | undefined, flexDirection: ((...parts: unknown[]) => ClayNode) | undefined, justifyContent: ((...parts: unknown[]) => ClayNode) | undefined, alignItems: ((...parts: unknown[]) => ClayNode) | undefined, borderRadius: ((...parts: unknown[]) => ClayNode) | undefined, borderWidth: ((...parts: unknown[]) => ClayNode) | undefined, border: ((...parts: unknown[]) => ClayNode) | undefined, overflow: ((...parts: unknown[]) => ClayNode) | undefined, fontSize: ((...parts: unknown[]) => ClayNode) | undefined, letterSpacing: ((...parts: unknown[]) => ClayNode) | undefined, lineHeight: ((...parts: unknown[]) => ClayNode) | undefined, textAlign: ((...parts: unknown[]) => ClayNode) | undefined, whiteSpace: ((...parts: unknown[]) => ClayNode) | undefined, float: ((...parts: unknown[]) => ClayNode) | undefined;
+export declare const backgroundColor: ((...parts: unknown[]) => ClayNode) | undefined, bg: ((...parts: unknown[]) => ClayNode) | undefined, color: ((...parts: unknown[]) => ClayNode) | undefined, borderColor: ((...parts: unknown[]) => ClayNode) | undefined, width: ((...parts: unknown[]) => ClayNode) | undefined, height: ((...parts: unknown[]) => ClayNode) | undefined, padding: ((...parts: unknown[]) => ClayNode) | undefined, p: ((...parts: unknown[]) => ClayNode) | undefined, paddingInline: ((...parts: unknown[]) => ClayNode) | undefined, paddingBlock: ((...parts: unknown[]) => ClayNode) | undefined, paddingTop: ((...parts: unknown[]) => ClayNode) | undefined, paddingRight: ((...parts: unknown[]) => ClayNode) | undefined, paddingBottom: ((...parts: unknown[]) => ClayNode) | undefined, paddingLeft: ((...parts: unknown[]) => ClayNode) | undefined, pt: ((...parts: unknown[]) => ClayNode) | undefined, pr: ((...parts: unknown[]) => ClayNode) | undefined, pb: ((...parts: unknown[]) => ClayNode) | undefined, pl: ((...parts: unknown[]) => ClayNode) | undefined, gap: ((...parts: unknown[]) => ClayNode) | undefined, flexDirection: ((...parts: unknown[]) => ClayNode) | undefined, justifyContent: ((...parts: unknown[]) => ClayNode) | undefined, alignItems: ((...parts: unknown[]) => ClayNode) | undefined, borderRadius: ((...parts: unknown[]) => ClayNode) | undefined, borderWidth: ((...parts: unknown[]) => ClayNode) | undefined, border: ((...parts: unknown[]) => ClayNode) | undefined, overflow: ((...parts: unknown[]) => ClayNode) | undefined, fontSize: ((...parts: unknown[]) => ClayNode) | undefined, letterSpacing: ((...parts: unknown[]) => ClayNode) | undefined, lineHeight: ((...parts: unknown[]) => ClayNode) | undefined, textAlign: ((...parts: unknown[]) => ClayNode) | undefined, whiteSpace: ((...parts: unknown[]) => ClayNode) | undefined, float: ((...parts: unknown[]) => ClayNode) | undefined, image: ((...parts: unknown[]) => ClayNode) | undefined;
 /**
  * The styles of a module as C: a `Clay_ElementDeclaration` per export, and a `Clay_TextElementConfig` named
  * `<name>_text` for one that sets text props, for `CLAY(id, name)` and `CLAY_TEXT(s, name_text)`. A state is a whole

package/dist/clay.mjs

@@ -176,6 +176,27 @@ const floating = (prop, parts) => {
 	if (o.clip !== void 0) set("floatClip", keyword("none", "parent")(`${prop}.clip`, o.clip) === "none" ? "NONE" : "ATTACHED_PARENT");
 	return out;
 };
+const IMAGE_OPTIONS = [
+	"width",
+	"height",
+	"fit"
+];
+const imageOf = (prop, parts) => {
+	if (parts.length < 1 || parts.length > 2) throw fail(`cssints: ${prop} takes the path of an image and its { width, height, fit }, got ${parts.length} values`);
+	const src = parts[0];
+	if (typeof src !== "string" || !src || /\p{Cc}/u.test(src)) throw fail(`cssints: ${prop}: unexpected ${say(src)}, expected the path of an image (a string, not empty, no control characters)`);
+	const o = options(prop, parts[1] ?? {}, IMAGE_OPTIONS);
+	if (o.width === void 0 || o.height === void 0) throw fail(`cssints: ${prop}: unexpected ${say(parts[1] ?? {})}, expected the image's width and height in pixels`);
+	const w = whole(`${prop}.width`, o.width);
+	const h = whole(`${prop}.height`, o.height);
+	if (!w || !h) throw fail(`cssints: ${prop}: unexpected ${say(w)}x${say(h)}, expected a positive whole number of pixels for each side`);
+	return [
+		["imageSrc", src],
+		["width", w],
+		["height", h],
+		["aspectRatio", keyword("fill", "contain")(`${prop}.fit`, o.fit ?? "fill") === "contain" ? w / h : 0]
+	];
+};
 const PADDING = [
 	"paddingTop",
 	"paddingRight",
@@ -235,7 +256,8 @@ const MEMBERS = {
 	lineHeight: one("lineHeight", whole),
 	textAlign: one("textAlign", keyword("left", "center", "right")),
 	whiteSpace: one("whiteSpace", keyword("normal", "pre-line", "nowrap")),
-	float: floating
+	float: floating,
+	image: imageOf
 };
 const member = (name, build) => (...parts) => {
 	if (parts.some(isClay)) throw fail(`cssints: ${name}: a style is not a value`);
@@ -288,7 +310,7 @@ const fonts = (...names) => {
 		]])]))
 	};
 };
-const { backgroundColor, bg, color, borderColor, width, height, padding, p, paddingInline, paddingBlock, paddingTop, paddingRight, paddingBottom, paddingLeft, pt, pr, pb, pl, gap, flexDirection, justifyContent, alignItems, borderRadius, borderWidth, border, overflow, fontSize, letterSpacing, lineHeight, textAlign, whiteSpace, float } = Object.fromEntries(Object.entries(MEMBERS).map(([k, b]) => [k, member(k, b)]));
+const { backgroundColor, bg, color, borderColor, width, height, padding, p, paddingInline, paddingBlock, paddingTop, paddingRight, paddingBottom, paddingLeft, pt, pr, pb, pl, gap, flexDirection, justifyContent, alignItems, borderRadius, borderWidth, border, overflow, fontSize, letterSpacing, lineHeight, textAlign, whiteSpace, float, image } = Object.fromEntries(Object.entries(MEMBERS).map(([k, b]) => [k, member(k, b)]));
 const rgba = (prop, text, values) => {
 	const flat = text.replace(VAR, (m, n) => valueOf(tables, n, values) ?? m);
 	const c = flat.includes("var(") ? void 0 : parseColor(flat);
@@ -404,6 +426,8 @@ const shapeOf = (entries, values) => {
 	};
 	if (p.has("overflow")) out.clip = get("overflow") === "hidden" ? HIDDEN : VISIBLE;
 	if (FLOATING.some((k) => p.has(k))) out.floating = floatingOf(p);
+	if (p.has("imageSrc")) out.image = { imageData: get("imageSrc") };
+	if (p.get("aspectRatio")) out.aspectRatio = { aspectRatio: get("aspectRatio") };
 	const text = {};
 	if (p.has("color")) text.textColor = colourOf("color");
 	for (const k of [
@@ -491,9 +515,10 @@ const ENUM = {
 	attachTo: (v) => `CLAY_ATTACH_TO_${v}`,
 	clipTo: (v) => `CLAY_CLIP_TO_${v}`
 };
+const cString = (s) => `"${s.replace(/[\\"]/g, "\\$&")}"`;
 const c = (key, v) => {
 	if (typeof v === "number") return key === "parentId" ? `${v}u` : String(v);
-	if (typeof v === "string") return ENUM[key](v);
+	if (typeof v === "string") return key === "imageData" ? `(void *)${cString(v)}` : ENUM[key](v);
 	if (v.type !== void 0) return `{ .size = { ${v.percent !== void 0 ? `.percent = ${c("", v.percent)}` : `.minMax = { ${c("", v.min ?? 0)}, ${c("", v.max ?? 0)} }`} }, .type = ${c("type", v.type)} }`;
 	return `{ ${Object.entries(v).map(([k, x]) => `.${k} = ${c(k, x)}`).join(", ")} }`;
 };
@@ -504,6 +529,8 @@ const SHAPE = /* @__PURE__ */ new Set([
 	"border",
 	"clip",
 	"floating",
+	"image",
+	"aspectRatio",
 	"text",
 	"themes",
 	...STATES
@@ -547,4 +574,4 @@ const header = (styles) => {
 	return `${lines.join("\n")}\n`;
 };
 //#endregion
-export { active, alignItems, backgroundColor, bg, border, borderColor, borderRadius, borderWidth, cn, color, createGlobalTheme, createTokens, flexDirection, float, focus, fontSize, fonts, gap, header, height, hover, justifyContent, letterSpacing, lineHeight, overflow, p, padding, paddingBlock, paddingBottom, paddingInline, paddingLeft, paddingRight, paddingTop, pb, pl, pr, pt, textAlign, whiteSpace, width };
+export { active, alignItems, backgroundColor, bg, border, borderColor, borderRadius, borderWidth, cn, color, createGlobalTheme, createTokens, flexDirection, float, focus, fontSize, fonts, gap, header, height, hover, image, justifyContent, letterSpacing, lineHeight, overflow, p, padding, paddingBlock, paddingBottom, paddingInline, paddingLeft, paddingRight, paddingTop, pb, pl, pr, pt, textAlign, whiteSpace, width };

package/docs/API.md

@@ -1269,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).
 
@@ -1406,7 +1414,7 @@ static const Clay_TextElementConfig label_text = { .textColor = { .r = 235, .g =
 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), and for text `color`, `fontSize`, `letterSpacing`, `lineHeight`, `textAlign`, `whiteSpace` (`wrapMode`); `cn` merges, a later prop wins. Any other property is not a member.
+- **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.
@@ -1471,6 +1479,31 @@ css.float({ attach: { element: "top left" } }); // error: a point is x, then y
 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssints",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CSS in TypeScript: typed css.* calls compiled to atomic CSS at build time (a Vite plugin)",
   "license": "MIT",
   "repository": {
@@ -68,7 +68,7 @@
     }
   },
   "dependencies": {
-    "@cssints/css-grammar": "^0.4.0",
+    "@cssints/css-grammar": "^0.5.0",
     "culori": "^4.0.2",
     "effect": "4.0.0",
     "happy-dom": "^20.14.5",