@teacss/preset-standard 0.5.1 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ bun add @teacss/preset-standard
 ```
 
 ```css
-@preset "standard";
+@presets "standard";
 @source "./src/**/*.{ts,tsx}";
 @teacss;
 ```
@@ -50,11 +50,11 @@ Preflight emits low-specificity reset rules and theme variables. Set
 reset while limiting variables to referenced keys (including the reset's sans
 and monospace families).
 
-Selecting `@preset "standard"` also normalizes headings, links, lists, media,
+Selecting `@presets "standard"` also normalizes headings, links, lists, media,
 tables, horizontal rules, code typography, and form-control typography. Headings
 inherit size and weight; links inherit color and decoration; lists lose their
 markers; images and videos fit their container without losing aspect ratio.
-Use utilities or Shortcuts' `prose` family to author their visible presentation.
+Use utilities or Official's `prose` family to author their visible presentation.
 
 Small text, sub/sup, titled abbreviations, and progress have consistent baselines.
 Dialogs and popovers retain native auto-margin centering after the universal
@@ -64,43 +64,173 @@ appearance. Fieldsets use `min-inline-size: 0` so their boxes can shrink inside
 narrow containers; oversized descendants still need responsive sizing.
 Grouped options in `select[multiple]` and `select[size]` retain a 20px
 inline-start indent, following text direction and allowing utility overrides.
-Hidden elements remain hidden despite media/summary display resets, while
-`hidden="until-found"` (case-insensitive) retains native discovery behavior.
-Explicit display utilities can still override this low-specificity baseline.
+The reset enforces native hiding with two global rules:
+
+```css
+:where([hidden]:not([hidden="until-found" i])) { display: none !important; }
+:where([hidden="until-found" i]) { display: revert !important; }
+```
+
+Ordinary display utilities, component CSS and inline styles cannot reveal an
+element with `hidden`; remove the attribute to show it. Explicit `!important`
+declarations still follow the CSS cascade. `until-found` restores the tag's
+native display, with discovery depending on the tag and browser. Prefer `div`
+or `section` containers for discoverable content:
+
+```html
+<section hidden="until-found">Searchable content</section>
+```
+
+These rules run in both default and on-demand preflight. With preflight disabled,
+the application supplies its own hiding rules.
 
 Native control appearance, focus outlines, disabled state, and disclosure
 behavior remain intact. Marker-free semantic lists should use `role="list"`
 for Safari/VoiceOver. The reset adds no brand palette or global motion policy.
-Element-local `reset-*` shortcuts remain in the optional Shortcuts preset;
+Element-local `reset-*` shortcuts belong to the optional Official preset;
 Standard does not register those classes.
 
-CSS entries declare named variants with `@custom theme <name> {}`. Each emits
-zero-specificity variable overrides and a dynamic `theme-<name>` class.
-Preset-aware merging treats those classes as one opaque family.
+### Role palettes and mode regions
 
-## Class merging
+Primary creates emphasis. Neutral builds the interface. Semantic colors communicate state.
 
-```ts
-import { cn, pluginStandard } from "@teacss/preset-standard/merge";
+Standard provides seven 12-step roles: primary → gray, neutral → sage,
+focused → neutral, success → jade, warning → amber, failure → red, general → blue. Use
+`bg-color:primary-200 text-color:primary-950` directly. Neither Standard nor
+Official adds background/hover/foreground aliases; role steps already describe
+those uses. Keep palette selection in central configuration.
 
-cn("p:4 d:flex", "p:8"); // "d:flex p:8"
-cn("p:4", "p:invalid"); // "p:invalid"
+The role order is primary, neutral, then the states: focused, success, warning,
+failure, general. Focused follows the resolved neutral scale at each step when
+no focused selection applies, including when `@focused` is omitted. Declaring
+`@focused` only enables choices; it does not change this fallback. A configured
+`data-css-focused` selection overrides it. Empty, unknown or undeclared selections
+return to the region’s neutral palette; `theme.rolePalettes.focused: []` clears
+independent choices. Application `@custom` overrides still take precedence in
+the base mapping.
+
+Declare selectable physical palettes in the CSS entry:
+
+```css
+@presets "standard,official";
+@primary "gray,gold,red,blue";
+@neutral "sage,slate";
+@focused "gray,blue";
+@success "jade,green";
+@warning "amber,orange";
+@failure "red,ruby";
+@general "blue,cyan";
+@teacss;
+```
+
+Lists add available selections, not defaults. Repeated declarations/imports union
+and sort each role's names. Sources must be lowercase kebab-case physical palettes
+with all 12 base steps and no direct or transitive role references in any mode.
+Programmatic `theme.rolePalettes` has seven optional arrays; later arrays replace
+earlier arrays per role, and `[]` clears that role. It is global configuration,
+not a scale or a mode field. No DOM scanning is involved.
+
+```html
+<html data-css-primary="gray" data-css-neutral="sage" data-css-mode="dark">
+  <body>
+    <section data-css-primary="red" data-css-mode="light">
+      <p>Red / sage / light</p>
+      <article data-css-neutral="slate">Gray / slate / dark</article>
+    </section>
+  </body>
+</html>
+```
+
+Any of the seven `data-css-<role>` attributes, `data-css-mode`, or configured mode
+alias starts a region. Each of its eight dimensions uses the same selection order:
+**own attribute → root HTML attribute → configured default**. Intermediate
+regions are ignored. Plain descendants inherit until the next region. Empty,
+unknown, or undeclared values explicitly select the configured default and block
+root fallback. Removing the last marker rejoins the enclosing region. Runtime
+attribute changes need no regeneration. `data-css-theme` has no TeaCSS meaning.
+
+`@dark` / `@light` test the final styled target's region; pseudo-elements use their
+host. No explicit mode activates neither condition. `defaultMode` names the base
+palette; `@os-dark` / `@os-light` remain independent media queries.
+`modeSelectors: { dark: ".night", light: ".day" }` adds aliases; explicit mode
+attributes win, both aliases select neutral mode, and neither alias is implicit.
+Programmatic mode names preserve case, spaces and punctuation; empty names, NUL
+and unpaired surrogates are rejected.
+
+Global `@custom` sets scales and colors; `@custom dark` changes colors only.
+Whole-theme variants are unsupported. `@custom theme ...` and `theme.themes`
+are errors. Palette selection never changes spacing, radii or shadow templates.
+
+### Relationship markers
+
+`data-css-group` enables anonymous ancestor conditions such as `@group-hover`;
+`data-css-peer` enables preceding-sibling conditions such as `@peer-checked`.
+Named values are ASCII-whitespace-separated lists: `data-css-group="card panel"`
+also enables `@group-hover/card` and `@group-hover/panel`. Presence always
+matches anonymous conditions; an empty value enables only anonymous ones.
+Names are case-sensitive. Group remains descendant matching, peer uses `~`.
+
+## Root language conditions
+
+```html
+<html lang="zh">
+  <body><p lang="en" class="p:4 p:10@lang-zh">...</p></body>
+</html>
 ```
 
-The `/merge` entry also exports `createStandardMerger()`. Merge uses token
-shape and does not validate values. Combine preset plugins for a wider merger:
+`@lang-<tag>` compares the complete root `html:root[lang]` value, ignoring ASCII
+case without trimming. Here `@lang-zh` matches and `@lang-en` does not.
+`zh`, `zh-CN`, and `zh-Hans` are independent: `@lang-zh` does not match a root
+value of `zh-CN`. Local `lang`, theme, and mode regions do not override the root
+language.
+Root elements, descendants, targets, and pseudo-elements share this condition.
+
+Use BCP 47 tags: `zh`, `zh-CN`, `zh-Hans`, `zh-Hans-CN`, `es-419`,
+`de-1996`, and `en-u-ca-gregory`. Extlang, private-use (`x-project`), and
+grandfathered (`i-klingon`) forms are also supported. Validation checks structure,
+not registry membership; it does not canonicalize aliases or infer parent tags.
+Tag case is unrestricted: `@lang-zh-CN` and `@lang-zh-cn` match identically.
+Non-ASCII characters, malformed subtags, underscores, whitespace, wildcards,
+and escapes are unmatched. The lowercase `lang-` prefix is reserved: rename custom
+breakpoint keys using it, including invalid language forms. Existing `@max-<name>`
+syntax is unchanged.
+
+`@!lang-en` also matches missing/empty root language. Conditions compose with
+states, relations, queries, modes, targets, shortcuts, and `@apply` using AND.
+Conflicting languages never match; repetition follows ordinary suffix behavior.
+The language guard contributes `0,1,0` specificity before existing wrappers;
+`space-*` / `divide-*` keep their zero-specificity selectors.
+
+Changing root `lang` updates generated CSS without runtime listeners or
+regeneration, including with preflight disabled. Keep complete tokens in scanned
+sources or safelists; do not escape `@` in HTML/JSX class strings. Each HTML iframe
+uses its own root; propagation across Shadow DOM or independent XML documents
+is unsupported. Applications own translation, `dir`, and SSR's initial language.
+
+## Class merging
 
 ```ts
-import { createMerger } from "@teacss/classes";
-import { pluginIcon } from "@teacss/preset-icons/merge";
-import { pluginStandard } from "@teacss/preset-standard/merge";
+import { cn } from "@teacss/classes";
 
-const cn = createMerger({ plugins: [pluginStandard, pluginIcon] });
+cn("p:4 d:flex", "p:8"); // "d:flex p:8"
+cn("p:4", "p:invalid"); // "p:invalid"
+cn("p:2@lang-en", "p:4@lang-en"); // "p:4@lang-en"
+cn("p:2@lang-ZH", "p:4@lang-zh"); // "p:4@lang-zh"
 ```
 
+`cn` uses fixed Standard and Icons rules. Install and import `@teacss/classes`
+directly for runtime class composition.
+Merge uses prefix shape and ordered conditions, ignoring ASCII language-tag
+case while preserving each winning token's spelling. It does not validate values
+or condition support: malformed suffixes can merge but emit no CSS.
+Unknown declarations merge
+only by their own prefix; application shortcuts have no cross-prefix footprint.
+
 Native shorthands are emitted before their component overrides. For example,
 `cn("border:[1px_solid_red]", "border-t-width:4")` retains both classes and
 produces a 4px top border. Reversing those arguments leaves only the shorthand.
+The same ordering covers place/gap/columns, text families and corner shapes;
+explicit display and overflow can override `line-clamp`'s corresponding declarations.
 
 ## Value and composition boundaries
 
@@ -108,23 +238,34 @@ produces a 4px top border. Reversing those arguments leaves only the shorthand.
   `border-a-width:[1px_2px]`; physical x/y and single-edge forms accept one.
 - `[…]` keeps structurally valid arbitrary CSS, including
   `animation-name:[var(--name)]`. It does not guarantee browser support.
+- Custom-variable values and `font-palette` use the shared structural checks;
+  failed bracket/variable decoding cannot fall back to unchecked raw CSS.
+- A configured `DEFAULT` key references its unsuffixed variable: `p:DEFAULT`
+  reads `--spacing`, including through negative spacing. Applications supply
+  these scale variables when preflight is disabled.
+- Named shadows use global templates and support local color overrides.
+  `shadow:$shadow-card` reads a complete raw variable without recoloring;
+  `box-shadow:[…]` replaces the whole composed surface.
+- Named animations quote their decoded CSS names to avoid shorthand keyword
+  ambiguity. Numeric zero iteration counts remain zero.
 - Bare background/mask sizes cannot be negative.
 - Border-spacing axis variables do not inherit into nested tables.
 - Gradient properties are registered on demand, retaining shared fallbacks
   and neutral additive-mask layers without registering unrelated families.
 
-## Bare utilities
+## Explicit activators
 
-The closed built-in bare-token inventory is:
+Standard utilities all use `property:value`. The following activators accept
+exactly `on`, with ordinary importance and suffix conditions:
 
 ```txt
-mask-g-linear mask-g-radial mask-g-conic
-divide-x divide-y
-space-x-reverse space-y-reverse space-a-reverse space-c-reverse
+mask-g-linear:on mask-g-radial:on mask-g-conic:on
+space-x-reverse:on space-y-reverse:on space-a-reverse:on space-c-reverse:on
 ```
 
-All other Standard utilities use `property:value`. Values are prefix-specific
-and may support theme references, arbitrary values, CSS-wide keywords, `!`, and
-trailing conditions.
+Use `divide-x-width:1` / `divide-y-width:1` for 1px child dividers. The former
+nine bare spellings emit nothing; bare names are reserved for registered
+application or Official shortcuts. Removing an activator restores its default;
+`off`, `true`, variable, arbitrary, and CSS-wide values are unsupported.
 
 Pre-1.0. Keep tests and documentation aligned when changing vocabulary.

package/dist/index.d.ts

@@ -64,6 +64,7 @@ declare function transformerCompileClass(options?: CompileClassOptions): SourceC
 type ColorPalette = Record<string, Record<string, string>>;
 /** Semantic color roles emitted as `--color-<role>` variables. */
 type SemanticColors = Record<string, string | number>;
+type ColorRole = "primary" | "neutral" | "focused" | "success" | "warning" | "failure" | "general";
 interface ThemeAnimation {
   keyframes?: Record<string, string>;
   durations?: Record<string, string>;
@@ -74,8 +75,10 @@ interface ThemeAnimation {
 interface Theme {
   /** Named color palette; each color is a 12-step `100...950` scale. */
   colors?: ColorPalette;
-  /** Semantic color roles such as `background`, `foreground`, `border`, and `emphasis`. */
+  /** Application semantic colors. Presets supply an empty namespace. */
   semanticColors?: SemanticColors;
+  /** Physical palettes available through each data-css-<role> attribute. Lists replace per role. */
+  rolePalettes?: Partial<Record<ColorRole, readonly string[]>>;
   breakpoint?: Record<string, string>;
   container?: Record<string, string>;
   spacing?: Record<string, string>;
@@ -100,8 +103,8 @@ interface Theme {
   /**
    * Non-default mode color overrides. `theme.colors` and
    * `theme.semanticColors` are the default mode; each entry here (e.g. `dark`)
-   * overrides color variables under the mode's class ancestor (`.<mode>`, or the
-   * configured `dark`/`light` selector). Only declare values that differ. OS
+   * contributes to the complete mapping for its `data-css-mode` region (or a
+   * configured `dark`/`light` alias). Only declare values that differ. OS
    * preference uses `@os-dark` / `@os-light`.
    */
   modes?: Record<string, {
@@ -110,38 +113,19 @@ interface Theme {
   }>;
   /** The mode whose palette is `theme.colors` (need not appear in `modes`). @default "light" */
   defaultMode?: string;
-  /**
-   * Named theme variants (`@custom theme <name>`): subtree-scoped variable
-   * overrides emitted under `:where(.theme-<name>)` after the base and mode
-   * blocks. The bare `theme-<name>` class activates one. A variant may only
-   * override values the base theme declares — `@teacss/config` enforces that
-   * contract for entry-declared variants.
-   */
-  themes?: Record<string, ThemeVariant>;
-  /** Root selector(s) used when emitting preflight CSS custom properties */
+  /** Additional declaration points inside every mode/palette region; roots always receive the complete mapping. */
   preflightRoot?: Arrayable<string>;
   /** Additional CSS custom properties merged after the default theme-derived preflight variables */
   preflightBase?: Record<string, string | number>;
 }
-/**
- * One named theme variant: the scalar scales plus color-only mode overrides
- * (entry-authored variants carry only `dark`). Structural records, mode
- * bookkeeping, and preflight options stay top-level-theme-only.
- */
-interface ThemeVariant extends Omit<Theme, "animation" | "modes" | "defaultMode" | "themes" | "preflightRoot" | "preflightBase"> {
-  modes?: Record<string, {
-    colors?: ColorPalette;
-    semanticColors?: SemanticColors;
-  }>;
-}
 type CustomRule = Rule<Theme>;
-/** Ancestor selectors for the class-triggered `dark` / `light` modes. @default `.dark` / `.light` */
+/** Optional region-marker aliases for `dark` / `light`; canonical `data-css-mode` takes precedence. */
 interface ModeSelectors {
   dark?: string;
   light?: string;
 }
 interface PresetStandardOptions extends PresetOptions {
-  /** Override the `dark` / `light` ancestor selectors, e.g. `{ dark: "[data-theme=dark]" }`. */
+  /** Add `dark` / `light` region aliases, e.g. `{ dark: ".night" }`; no aliases are enabled by default. */
   modeSelectors?: ModeSelectors;
   /**
    * Container sizes for the `@container-*` conditions, merged over the default