cssints 0.3.1 → 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                                                                                                        |
@@ -191,7 +192,7 @@ and Cursor. The skills use it when it is configured and work without it.
 bun install
 bun run test    # all packages (vp run -r test, cached where possible); includes the type-check of the code in docs/API.md and this file
 bun run bench   # type instantiation budgets (tsc and tsgo)
-bun run check   # format, lint, type-check (vp check), then the Effect diagnostics (bun run typecheck)
+bun run check   # format, lint, type-check (vp check), then tsc 7 with the Effect diagnostics (bun run typecheck)
 bun run diff:check   # the added lines against master: anti-slop rules, key-file changes (tools/ai-automation)
 cd apps/demo && bun run dev
 cd apps/docs && bun run dev   # the documentation site, on the pages of README.md and docs/API.md

package/dist/check.mjs

@@ -1,5 +1,5 @@
-import { s as ContrastError } from "./registry-BUSEO32-.mjs";
-import { t as fallbackOf } from "./lowered-aJVapQT6.mjs";
+import { s as ContrastError } from "./registry-ByrYF2v5.mjs";
+import { t as fallbackOf } from "./lowered-CKSYUc0i.mjs";
 import { i as shown, r as ratio, t as luminance } from "./color-BYIxVLlS.mjs";
 import { Effect } from "effect";
 //#region src/check.ts

package/dist/clay-types.d.mts

@@ -0,0 +1,232 @@
+import { d as createTokens, om as Part, rm as Check, s as Overrides, t as CheckOverrides } from "./theme-types-BY0mRf3K.mjs";
+//#region src/clay-types.d.ts
+/** A number of pixels, or `"Npx"`. */
+export type Px = number | `${number}px`;
+/** Pixels, `N%` of the parent, `auto` (Clay's FIT) or `stretch` (Clay's GROW). */
+export type Size = Px | `${number}%` | "auto" | "stretch";
+export type Align = "flex-start" | "start" | "center" | "flex-end" | "end";
+/** A point of an element: `"left top"`, `"center center"`, `"right bottom"`, ... (Clay's `CLAY_ATTACH_POINT_LEFT_TOP`). */
+export type AttachPoint = `${"left" | "center" | "right"} ${"top" | "center" | "bottom"}`;
+type AttachPointType = "LEFT_TOP" | "LEFT_CENTER" | "LEFT_BOTTOM" | "CENTER_TOP" | "CENTER_CENTER" | "CENTER_BOTTOM" | "RIGHT_TOP" | "RIGHT_CENTER" | "RIGHT_BOTTOM";
+/** The options of `float()`: every one is optional. */
+export type FloatOptions = {
+  /** Which point of the floating element sits on which point of its parent. Default: `left top` on `left top`. */
+  attach?: {
+    element?: AttachPoint;
+    parent?: AttachPoint;
+  };
+  /** Moves the element from where `attach` puts it, in pixels (a negative one goes left or up). Default: 0, 0. */
+  offset?: {
+    x?: Px;
+    y?: Px;
+  };
+  /** Grows the element's own box, not its children's, in pixels (not negative). Default: 0, 0. */
+  expand?: {
+    width?: Px;
+    height?: Px;
+  };
+  /** Drawn in ascending order, with all the element's children. Default: 0. A whole number of `int16_t`. */
+  zIndex?: number;
+  /** `false` lets the pointer through to what lies under the element. Default: `true`. */
+  capture?: boolean;
+  /** `"parent"` clips the element to the box its parent is clipped to. Default: `"none"`. */
+  clip?: "none" | "parent";
+} & ({
+  /** The string of the element's `CLAY_ID("...")`, ASCII. Default: the element the float is a child of. */
+  parent?: string;
+  root?: never;
+} | {
+  /** Attach to the layout's root: absolute positioning, or a dialog centred on the screen. */
+  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;
+  b: number;
+  a: number;
+}
+interface Axis {
+  type: "FIT" | "GROW" | "PERCENT" | "FIXED";
+  min?: number;
+  max?: number;
+  percent?: number;
+}
+interface Sides {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+/** The fields of `Clay_ElementDeclaration`, and of `Clay_TextElementConfig` under `text`. */
+export interface ClayFields {
+  layout?: {
+    sizing?: {
+      width?: Axis;
+      height?: Axis;
+    };
+    padding?: Sides;
+    childGap?: number;
+    childAlignment?: {
+      x?: "LEFT" | "CENTER" | "RIGHT";
+      y?: "TOP" | "CENTER" | "BOTTOM";
+    };
+    layoutDirection?: "LEFT_TO_RIGHT" | "TOP_TO_BOTTOM";
+  };
+  backgroundColor?: Rgba;
+  cornerRadius?: {
+    topLeft: number;
+    topRight: number;
+    bottomRight: number;
+    bottomLeft: number;
+  };
+  border?: {
+    color?: Rgba;
+    width: Sides;
+  };
+  clip?: {
+    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;
+      y: number;
+    };
+    expand?: {
+      width: number;
+      height: number;
+    };
+    parentId?: number;
+    zIndex?: number;
+    attachPoints?: {
+      element: AttachPointType;
+      parent: AttachPointType;
+    };
+    pointerCaptureMode?: "CAPTURE" | "PASSTHROUGH";
+    attachTo: "PARENT" | "ELEMENT_WITH_ID" | "ROOT";
+    clipTo?: "NONE" | "ATTACHED_PARENT";
+  };
+  text?: {
+    textColor?: Rgba;
+    fontId?: number;
+    fontSize?: number;
+    letterSpacing?: number;
+    lineHeight?: number;
+    textAlignment?: "LEFT" | "CENTER" | "RIGHT";
+    wrapMode?: "WORDS" | "NEWLINES" | "NONE";
+  };
+}
+type Partly<T> = { [K in keyof T]?: T[K] extends Rgba | Axis ? T[K] : Partly<T[K]>; };
+/** What a state sets over the base: the fields it touches, at their values there. */
+export type ClayOverlay = Partly<ClayFields>;
+/** Clay's fields with the overlay of each state. */
+export interface ClayLayer extends ClayFields {
+  ":hover"?: ClayOverlay;
+  ":focus"?: ClayOverlay;
+  ":active"?: ClayOverlay;
+}
+/** What a Clay style compiles to: its fields, its state overlays, and per theme (by name) the colours it changes. */
+export interface ClayShape extends ClayLayer {
+  themes?: Record<string, Partly<ClayLayer>>;
+}
+/** What every member of cssints/clay returns. */
+export type ClayStyle = ClayShape & {
+  readonly "~clay": true;
+};
+type Colour = <const A extends readonly Part[]>(...parts: Check<"color", A>) => ClayStyle;
+type One<V> = (value: V) => ClayStyle;
+type Four<V> = (...values: [V] | [V, V] | [V, V, V] | [V, V, V, V]) => ClayStyle;
+type Pair<V> = (...values: [V] | [V, V]) => ClayStyle;
+export declare const backgroundColor: Colour;
+/** `background-color`. */
+export declare const bg: Colour;
+/** The colour of the text in the element (Clay's `textColor`). */
+export declare const color: Colour;
+export declare const borderColor: Colour;
+export declare const width: One<Size>;
+export declare const height: One<Size>;
+export declare const padding: Four<Px>;
+export declare const p: Four<Px>;
+export declare const paddingInline: Pair<Px>;
+export declare const paddingBlock: Pair<Px>;
+export declare const paddingTop: One<Px>;
+export declare const paddingRight: One<Px>;
+export declare const paddingBottom: One<Px>;
+export declare const paddingLeft: One<Px>;
+export declare const pt: One<Px>;
+export declare const pr: One<Px>;
+export declare const pb: One<Px>;
+export declare const pl: One<Px>;
+/** Clay's `childGap`. */
+export declare const gap: One<Px>;
+export declare const flexDirection: One<"row" | "column">;
+export declare const justifyContent: One<Align>;
+export declare const alignItems: One<Align>;
+/** 1 to 4 radii: top-left, top-right, bottom-right, bottom-left, as in CSS. */
+export declare const borderRadius: Four<Px>;
+export declare const borderWidth: Four<Px>;
+/** A border of that width and colour on every side. */
+export declare const border: <const A extends readonly Part[]>(width: Px, ...color: Check<"color", A>) => ClayStyle;
+/** `hidden` clips the children (Clay's `clip`). */
+export declare const overflow: One<"visible" | "hidden">;
+export declare const fontSize: One<Px>;
+export declare const letterSpacing: One<Px>;
+export declare const lineHeight: One<Px>;
+export declare const textAlign: One<"left" | "center" | "right">;
+/** `normal` wraps words, `pre-line` only at newlines, `nowrap` never. */
+export declare const whiteSpace: One<"normal" | "pre-line" | "nowrap">;
+/**
+ * Makes the element float above the others (Clay's `floating`), and sets `attachTo`: to the element it is a child of, to
+ * 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. */
+export declare const hover: (...styles: ClayStyle[]) => ClayStyle;
+/** Focused: `<name>_focus`. */
+export declare const focus: (...styles: ClayStyle[]) => ClayStyle;
+/** Pressed: `<name>_active`. */
+export declare const active: (...styles: ClayStyle[]) => ClayStyle;
+/**
+ * The app's fonts in the order of its font array: a style per name that sets Clay's `fontId`, and the list, which
+ * header() prints as an enum `<export>_<font>`. Each name is a C identifier.
+ */
+export declare const fonts: <const N extends readonly [string, ...string[]]>(...names: N) => { readonly [K in N[number]]: ClayStyle; } & {
+  readonly fonts: N;
+};
+/**
+ * A theme of cssints/clay's tokens, by a name that is a C identifier: header() prints every style again, the name
+ * appended (`<style>_<name>`, `<style>_hover_<name>`, `<style>_text_<name>`). It applies to the styles evaluated after it.
+ */
+export declare const createGlobalTheme: <const X extends object, const O extends Overrides<X>>(tokens: X, name: string, overrides: O & CheckOverrides<X, O>) => void;
+/** The styles of a built module as a C header: `CLAY(id, name)` and `CLAY_TEXT(s, name_text)`. */
+export declare const header: (styles: Record<string, unknown>) => string;
+//#endregion
+export { createTokens };

package/dist/clay.d.mts

@@ -0,0 +1,40 @@
+//#region src/clay.d.ts
+export declare const createTokens: (...args: unknown[]) => unknown;
+export declare const createGlobalTheme: (...args: unknown[]) => Readonly<{
+  __done: true;
+}>;
+type Value = string | number;
+type State = "" | ":hover" | ":focus" | ":active";
+type Entry = [key: string, value: Value, state: State];
+interface ClayNode {
+  __clay: Entry[];
+}
+/**
+ * Merges styles in argument order: a later prop wins.
+ *
+ * @returns {ClayNode} the merged style
+ */
+export declare const cn: (...styles: unknown[]) => ClayNode;
+export declare const hover: (...styles: unknown[]) => ClayNode;
+export declare const focus: (...styles: unknown[]) => ClayNode;
+export declare const active: (...styles: unknown[]) => ClayNode;
+/**
+ * The fonts of the app, in the order of its font array: `fonts("Roboto", "Mono").Mono` is a style that sets Clay's
+ * `fontId` to 1, and header() prints the order as an enum, `<name>_Mono`.
+ *
+ * @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, 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
+ * declaration of its own, `<name>_hover` (`_focus`, `_active`, and `<name>_hover_text`); a theme is a whole set of
+ * them again, its name last (`<name>_<theme>`, `<name>_hover_<theme>`, `<name>_text_<theme>`), for every style once
+ * the module has a theme, so a page picks a theme by appending its name. The fonts of `fonts()` are an enum, `<name>_<font>`, in their order.
+ *
+ * @param {Record<string, unknown>} styles the exports of a built module of cssints/clay styles
+ * @returns {string} a C header that includes clay.h
+ */
+export declare const header: (styles: Record<string, unknown>) => string;
+//#endregion