@teacss/core 0.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+# MIT License
+
+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
+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

@@ -0,0 +1,124 @@
+# @teacss/core
+
+**The framework-neutral TeaCSS engine.**
+
+## Purpose
+
+`@teacss/core` parses colon-syntax tokens, resolves the shared `@` condition
+axis, matches rules, and emits layered CSS. It owns mechanism only; presets own
+the vocabulary.
+
+Preset, integration, and tooling authors use this package directly. It does
+not discover filesystem configuration, manage build-tool module lifecycles, or
+provide runtime class composition; higher-level packages own those boundaries.
+A negated condition stays unmatched when its owning resolver cannot express a
+negative form; it is never silently emitted as the positive condition.
+
+## Usage
+
+```sh
+bun add @teacss/core @teacss/preset-standard
+```
+
+```ts
+import { createGenerator } from "@teacss/core";
+import { presetStandard } from "@teacss/preset-standard";
+
+const generator = await createGenerator({
+  presets: [presetStandard()],
+});
+
+const { css } = await generator.generate("p:4 bg-color:red-500@hover");
+```
+
+Large direct-input builds can cap concurrent token parsing to reduce peak memory:
+
+```ts
+const { css } = await generator.generate(tokens, {
+  tokenConcurrency: 256,
+});
+```
+
+The limit must be a positive integer. It is opt-in because custom asynchronous
+rules may intentionally coordinate work across tokens; omitting it preserves the
+existing unbounded scheduling behavior. Matched tokens and emitted CSS remain in
+the same deterministic order as default scheduling; matched-token iteration
+continues to follow input order. CSS string tie-breakers use
+locale-independent UTF-16 code-unit order.
+
+Most apps should install `teacss`. Use `@teacss/core` directly when building
+presets, generators, or tooling.
+
+Class-list integrations can use `splitClassTokens()` to split whitespace while
+preserving spaces inside attached `[]` literal regions. It intentionally keeps
+quotes, semicolons, and group syntax as ordinary token content; source
+extraction remains a separate, broader boundary. The default source extractor
+also recognizes valid unquoted HTML class values such as `class=p:4` and
+distributes grouped conditions in HTML values such as
+`class={p:4;m:2}@hover`. Braced attributes in JSX/TSX remain host expression
+containers rather than HTML class groups. Known JavaScript, TypeScript, JSX,
+TSX, and MDX file IDs stay on that host-source path, so invalid unquoted JSX
+attributes are not reinterpreted as HTML. File-aware grouping treats
+`.ts`/`.mts`/`.cts` as non-JSX host source and `.jsx`/`.tsx`/`.mdx` with JSX
+raw-text semantics, avoiding ambiguous angle assertions and text delimiters.
+Only `.tsx` applies TSX generic-arrow disambiguation; JSX, MDX, and mixed
+documents retain their own or conservative auto-detection semantics.
+
+Use `expandGroups()` when scanning host source, where valid TeaCSS groups may
+sit inside JavaScript strings or arrays. Use `expandClassGroups()` only after a
+class list has been isolated; it expands top-level groups while preserving
+group-like braces inside attached `[]` values and `()` CSS functions.
+
+Generic runtime class merging is intentionally separate from the generator:
+
+```sh
+bun add @teacss/classes
+```
+
+```ts
+import { createMerger } from "@teacss/classes";
+```
+
+## Theme merging
+
+Plain theme objects from presets and user configuration are deep-merged. A
+non-plain theme, such as a class instance, is treated as one atomic value so its
+prototype and private state remain valid: a later non-plain theme replaces an
+earlier one, and an empty plain overlay leaves it unchanged. To replace it with
+a plain theme, use a top-level `{ $reset: true, ... }` value. To combine
+class-backed state with another theme, use `extendTheme` and perform the
+class-aware merge there. A non-empty plain overlay on a non-plain theme is
+rejected instead of manufacturing an invalid class instance.
+
+## Transactional configuration
+
+Runtime integrations that reload configuration can stage work without mutating
+the live generator:
+
+```ts
+const prepared = await generator.prepareConfig(nextConfig);
+const candidates = await prepared.generator.applyExtractors(source, id);
+
+if (validationPassed) generator.commitConfig(prepared);
+```
+
+`prepared.generator` is isolated but shares the candidate resolved config that
+will be committed. `commitConfig()` returns `false` when a newer preparation has
+superseded the candidate or the candidate generator was reconfigured. The
+prepared snapshot is frozen, while its resolved config remains mutable for
+staged transformer work. A successful commit keeps the live generator identity
+and notifies every `config` observer; preparation and failed validation emit
+nothing. Observer failures are reported as diagnostics after the commit and do
+not roll the active configuration back.
+
+## Preflight context
+
+Preset preflights receive the generator and theme through their `getCSS(context)`
+callback. `context.generated` additionally exposes the utilities produced by the
+current `generate()` call after postprocessing, including cache hits and excluding
+preflights. Demand-driven preflights can inspect this read-only list without
+sharing mutable state across generation calls.
+
+## Status
+
+Pre-1.0. Public engine APIs may change before the stable release.