teacss 0.2.0-alpha.8 → 0.3.1

package/LICENSE

@@ -1,6 +1,7 @@
-MIT License
+# MIT License
 
-Copyright (c) 2022 Billgo
+Copyright (c) 2021-PRESENT Anthony Fu <https://github.com/antfu>
+Copyright (c) 2026-PRESENT Billgo <hi@billgo.me>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,3 +1,363 @@
-# Teacss
+# TeaCSS
 
-An unocss preset
+**An LLM-friendly atomic CSS toolkit.**
+
+Readable utilities for humans. Predictable syntax for AI agents.
+
+## Purpose
+
+`teacss` is the application-facing package. Its root entry provides the
+official `cn` and `recipe` runtime helpers plus Standard preset constant
+tables, while its subpaths expose the engine and official presets.
+
+Use it for normal TeaCSS applications. Preset authors, custom integration
+authors, and tooling authors should import the narrower `@teacss/*` packages
+that own those extension APIs; the root entry intentionally does not expose
+low-level factories such as `createDefiner`.
+
+The base installation contains the runtime class helpers, engine core, and
+official presets. Build integrations are separate packages, so install and
+import the one owned by the selected build boundary directly:
+
+| Build boundary | Additional installation | Import |
+| --- | --- | --- |
+| Vite | `bun add -d @teacss/vite vite` | `@teacss/vite` |
+| Astro | `bun add -d @teacss/astro astro vite` | `@teacss/astro` |
+| Rsbuild | `bun add -d @teacss/rsbuild @rsbuild/core` | `@teacss/rsbuild` |
+| PostCSS | `bun add -d @teacss/postcss postcss` | `@teacss/postcss` |
+| Bun Build | `bun add -d @teacss/bun` | `@teacss/bun` |
+
+The standalone CLI is intentionally separate because `teacss` has no CLI
+subpath or executable:
+
+```sh
+bun add -d @teacss/cli
+```
+
+TeaCSS is an atomic CSS toolkit designed around a simple idea: utility classes should read like CSS declarations. Its primary audience is large language models, so every language and design tradeoff is judged first by whether a model can reliably predict the output. Instead of compressing meaning into short aliases, TeaCSS uses an explicit `property:value` syntax that remains easy for developers to read and easy for AI agents to generate, validate, and reason about. Predictability takes precedence over brevity.
+
+## Philosophy
+
+TeaCSS keeps three principles in view:
+
+* **Predictability over brevity.** A model should be able to infer the emitted CSS from the source token.
+* **Clarity over cleverness.** Classes should be readable first, compact only when that does not hide intent.
+* **One model over exceptions.** State, responsive behavior, relations, and arbitrary selectors all use the same trailing `@` condition axis. Write `p:4@hover`, never `hover:p:4`.
+
+## Usage
+
+Install or update the optional TeaCSS skill:
+
+```sh
+skills add teacss/skills --skill teacss
+skills update teacss
+```
+
+Restart Codex after installing the skill.
+
+Install the application package and the integration used by the project. For
+Vite:
+
+```sh
+bun add teacss
+bun add -d @teacss/vite vite
+```
+
+Use the Vite integration:
+
+```ts
+import { pluginTeacss } from "@teacss/vite";
+
+export default {
+  plugins: [pluginTeacss()],
+};
+```
+
+Create a TeaCSS entry at `index.css` or `src/index.css`:
+
+```css
+@preset "standard";
+@source "./src/**/*.{ts,tsx}";
+@teacss;
+```
+
+Add `@preset "icons";` when the app uses the official icon vocabulary.
+Add `@preset "articles";` for the fixed semantic-descendant utility
+`article:base`:
+
+```html
+<article
+  class="article:base max-inline-size:65ch m-a:auto font-size:3x text-color:$color-foreground"
+>
+  <h1>Title</h1>
+  <p>Readable long-form content.</p>
+</article>
+```
+
+The utility defaults to TeaCSS's shared `shortcuts` layer
+(`LAYER_SHORTCUTS`). Under the default layer order, ordinary utilities in the
+`utilities` layer emit later. The preset does not create an article-specific
+layer.
+
+The articles factory is available only from its explicit subpath:
+
+```ts
+import presetArticles, { presetArticles as namedPresetArticles } from "teacss/preset-articles";
+```
+
+The root `teacss` entry does not re-export it.
+
+Import the generated stylesheet once from your app entry:
+
+```ts
+import "virtual:teacss.css";
+```
+
+Then write TeaCSS utilities in your markup:
+
+```html
+<button class="p:4 bg-color:red-500 text-color:white bg-color:red-600@hover">
+  Submit
+</button>
+```
+
+The root entry also re-exports the Standard preset's constant tables for
+programmatic use:
+
+```ts
+import { breakpointKeywords, primaryColors } from "teacss";
+```
+
+These are the same exports as `@teacss/preset-standard/constants`; there is no
+separate `teacss/constants` subpath.
+
+Grouped utilities can share the same condition:
+
+```html
+<button class="{p:4;text-color:white;bg-color:red-500}@hover">
+  Submit
+</button>
+```
+
+## Runtime Recipes
+
+The application entry exports `recipe`, bound once to its exact official
+`cn`:
+
+```ts
+import { recipe, type ClassProp, type VariantProps } from "teacss";
+
+const badge = recipe({
+  className: "d:inline-flex align-items:center rd:full p-x:2",
+  variants: {
+    tone: {
+      neutral: "bg-color:gray-100 text-color:gray-900",
+      accent: "bg-color:blue-500 text-color:white",
+    },
+  },
+  compoundVariants: [
+    {
+      tone: "accent",
+      className: "font-weight:700",
+    },
+  ],
+});
+
+badge({
+  tone: "accent",
+  className: "p-x:3",
+}); // string
+
+type BadgeProps = VariantProps<typeof badge> & ClassProp;
+
+function badgeClassName({ className, ...variants }: BadgeProps) {
+  return badge({ ...variants, className });
+}
+```
+
+A primitive string top-level `className` value selects the single-element form.
+Its variant choices and compound outputs are strings; the recipe call accepts
+variants plus caller `className` and returns the merged string directly.
+
+Use a non-empty object top-level `className` value for multiple elements:
+
+```ts
+const button = recipe({
+  className: {
+    container: "d:inline-flex align-items:center p:2 p:4@md",
+    icon: "inline-size:4x",
+  },
+  variants: {
+    size: {
+      small: {
+        container: "p:2",
+        icon: "inline-size:3x",
+      },
+      large: {
+        container: "p:4",
+        icon: "inline-size:5x",
+      },
+    },
+    disabled: {
+      true: {
+        container: "opacity:50 pointer-events:none",
+      },
+    },
+  },
+  defaultVariants: {
+    size: "small",
+    disabled: false,
+  },
+  compoundVariants: [
+    {
+      size: "large",
+      disabled: true,
+      className: {
+        container: "font-weight:700",
+        icon: "inline-size:6x",
+      },
+    },
+    {
+      disabled: true,
+      classKeys: ["container", "icon"],
+      className: "opacity:80",
+    },
+  ],
+});
+
+const classes = button({
+  size: "large",
+});
+
+classes.container({
+  disabled: true,
+  className: "p:6",
+});
+classes.icon();
+
+type ButtonProps = VariantProps<typeof button> & ClassProp;
+
+function buttonClassName({ className, ...variants }: ButtonProps) {
+  return button(variants).container({ className });
+}
+```
+
+There is no distinguished or required `root` key in an object-form top-level
+`className`; every declared key is an ordinary named class. Variant choices are
+always target maps. A compound either supplies a non-empty `className` target
+map, or pairs a primitive-string `className` with a non-empty `classKeys` array
+to broadcast that class to several effective named classes. `classKeys` may
+name declared or inherited classes and must be dense, unique, and free of
+unknown names. The two compound forms are mutually exclusive, and matching
+entries contribute in declaration order. A recipe call returns a readonly
+resolver for every name.
+Recipe-level selections are captured once. A resolver selection is local to
+that invocation, compounds are re-evaluated for it, and `className` appends only
+to that resolver. The one-sided `"true"` choice makes `disabled`
+boolean-capable: boolean `false` is a branchless state that contributes no
+fragment but can still drive defaults and compounds. Responsive behavior
+remains suffix-only inside static values, such as `p:4@md`; recipe props do not
+accept breakpoint objects.
+
+Every definition without `extend` requires its own `className` field. An
+extending child may omit `className` to inherit the parent's string or object
+mode, base fragments, and existing named classes. If a child declares
+`className`, it must keep that mode; an object child may add new names:
+
+```ts
+const primaryButton = recipe({
+  extend: button,
+  variants: {
+    emphasis: {
+      strong: {
+        container: "font-weight:700",
+      },
+    },
+  },
+});
+
+const strongBadge = recipe({
+  extend: badge,
+  className: "font-weight:700",
+});
+```
+
+`classKeys` is reserved as a variant name, while `parts`, `styles`, and
+`styleKeys` are available as ordinary variant names. Nested
+`compoundVariants[].classKeys` is supported; the retired top-level definition
+field `styles` and former nested `parts` selector are not compatibility aliases.
+
+The repeated `className` spelling is separated by boundary:
+`definition.className` supplies base classes and selects string or object mode,
+`compoundVariants[].className` supplies a compound output, and caller
+`className` is accepted by a single-element recipe call or one named resolver.
+A multi-element recipe call itself accepts shared selections only.
+
+`@teacss/classes` exports the factory rather than a pre-bound definer. This
+integration creates its own `recipe` from the official `cn`; custom
+integrations follow the same boundary with their own merger:
+
+```ts
+import { createDefiner, createMerger } from "@teacss/classes";
+
+const merge = createMerger({ conflicts, plugins });
+export const recipe = createDefiner({ merge });
+```
+
+`createDefiner` and its type-only `RecipeDefiner` return type are intentionally
+available only from `@teacss/classes`; the named return type keeps declarations
+for exported integration-owned definers compact. Normal recipe libraries
+peer-depend on and externalize `teacss`. A custom integration peer-depends on
+`@teacss/classes` and exports the exact definer used for extendable parents.
+Consumers deduplicate the owning integration. Recreating a definer, loading
+another runtime copy or version, or resolving the parent and definer from
+different provider-package instances breaks extension identity even if the
+declarations and merger are compatible. Deduplicating only `@teacss/classes`
+is insufficient for a duplicated custom-definer provider. `VariantProps`
+extraction does not need runtime identity; `extend` does.
+
+## Runtime Class Merging
+
+Use the application runtime merger for component class names. It understands the
+standard vocabulary and canonical `icon:<collection>-<icon-name>` utilities:
+
+```ts
+import { cn } from "teacss";
+
+cn("p:4 d:flex", "p:8"); // "d:flex p:8"
+cn("p:4", "p:invalid"); // "p:invalid"
+cn("reset:li", "reset:ul"); // "reset:ul"
+cn("d:block", "reset:li"); // "d:block reset:li"
+```
+
+The default `cn` is one direct merger composed from `pluginStandard` and
+`pluginIcon`; it does not chain preset-local mergers. Resolution is based
+on parsed shape, conditions, importance, and declared footprints. It does not
+validate values, so an unsupported winner may emit no CSS. The supported
+`reset:*` profiles apply to the current element: headings (`reset:h1` through
+`reset:h6`), links and controls
+(`reset:a|button|select|input-text|textarea`), and lists
+(`reset:li|ol|ul|menu`). `reset:input-text` is only for text-like inputs; there
+is no generic `reset:input`. Profiles replace one another as a single opaque
+family and never delete an unrelated utility. Document-root and shadow-host
+defaults come from the standard preset's automatic preflight.
+
+Generic class merging is a separate package for custom conflict metadata:
+
+```sh
+bun add @teacss/classes
+```
+
+```ts
+import { createMerger } from "@teacss/classes";
+```
+
+## Status
+
+TeaCSS is currently pre-1.0 and under active development.
+
+Syntax, configuration, package boundaries, and public APIs may change before the first stable release.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+import { Preset, Rule, UserConfig, Variant, createGenerator } from "@teacss/core";
+export { type Preset, type Rule, type UserConfig, type Variant, createGenerator };

package/dist/core.js

@@ -0,0 +1 @@
+import{createGenerator as e}from"@teacss/core";export{e as createGenerator};

package/dist/index.d.ts

@@ -1,39 +1,7 @@
-export { default as cn } from 'classnames';
-import * as CLSX from 'clsx';
-import { clsx } from 'clsx';
-
-type ClassValue = CLSX.ClassValue;
-type ClassProp = {
-    class: ClassValue;
-    className?: never;
-} | {
-    class?: never;
-    className: ClassValue;
-} | {
-    class?: never;
-    className?: never;
-};
-type OmitUndefined<T> = T extends undefined ? never : T;
-type StringToBoolean<T> = T extends "true" | "false" ? boolean : T;
-
-declare function cxm(...inputs: ClassValue[]): string;
-type VariantProps<Component extends (...args: any) => any> = Omit<OmitUndefined<Parameters<Component>[0]>, "class" | "className">;
-type CxOptions = Parameters<typeof clsx>;
-type CxReturn = ReturnType<typeof clsx>;
-declare const cx: typeof clsx;
-type ConfigSchema = Record<string, Record<string, ClassValue>>;
-type ConfigVariants<T extends ConfigSchema> = {
-    [Variant in keyof T]?: StringToBoolean<keyof T[Variant]> | null | undefined;
-};
-type ConfigVariantsMulti<T extends ConfigSchema> = {
-    [Variant in keyof T]?: StringToBoolean<keyof T[Variant]> | StringToBoolean<keyof T[Variant]>[] | undefined;
-};
-type Config<T> = T extends ConfigSchema ? {
-    variants?: T;
-    defaultVariants?: ConfigVariants<T>;
-    compoundVariants?: (T extends ConfigSchema ? (ConfigVariants<T> | ConfigVariantsMulti<T>) & ClassProp : ClassProp)[];
-} : never;
-type Props<T> = T extends ConfigSchema ? ConfigVariants<T> & ClassProp : ClassProp;
-declare const cva: <T>(base?: ClassValue, config?: Config<T>) => (props?: Props<T>) => string;
-
-export { type CxOptions, type CxReturn, type VariantProps, cva, cx, cxm };
+import { ClassProp, Merger, RecipeDefiner, VariantProps } from "@teacss/classes";
+export * from "@teacss/preset-standard/constants";
+//#region src/index.d.ts
+declare const cn: Merger;
+declare const recipe: RecipeDefiner;
+//#endregion
+export { type ClassProp, type VariantProps, cn, recipe };