@teacss/preset-standard 0.5.2 → 0.6.2

package/README.md

@@ -12,7 +12,7 @@ bun add @teacss/preset-standard
 ```
 
 ```css
-@preset "standard";
+@presets "standard";
 @source "./src/**/*.{ts,tsx}";
 @teacss;
 ```
@@ -35,14 +35,32 @@ separate. `multiplerKeywords` remains a deprecated alias for
 ## Application shortcuts
 
 ```css
-@shortcut hstack "d:flex flex-direction:row align-items:center";
-@shortcut truncate "overflow:hidden text-overflow:ellipsis white-space:nowrap";
+@shortcut stack-row "d:flex flex-direction:row align-items:center";
+@shortcut text-truncate "overflow:hidden text-overflow:ellipsis white-space:nowrap";
 ```
 
 Declarations may live in the CSS entry, imported CSS, or CSS matched by
 `@source`. Conditions remain valid on use, and the last declaration of a name
 wins. Programmatic shortcuts use Core's generic `UserConfig` types.
 
+## Paired sizing and logical dividers
+
+For text-flow sizing, `size:4x`, `min-size:4x`, and `max-size:4x` set both
+inline and block sizes. For fixed geometry, use `dimensions:4x`,
+`min-dimensions:4x`, and `max-dimensions:4x` for width and height. These are
+ordinary Standard declarations. Values must be accepted by both underlying
+single-axis rules. Variables, arbitrary values, and suffix conditions work as
+they do on those rules. `size:screen` emits `100vi` and `100vb`;
+`dimensions:screen` emits `100vw` and `100vh`.
+
+`divide-inline-width:` and `divide-block-width:` draw on logical inline-end
+and block-end edges. `divide-x-width:` and `divide-y-width:` keep physical
+right and bottom edges. `divide-color:` and `divide-style:` supply common
+settings. `divide-inline-color/style:` and `divide-block-color/style:` override
+only the named logical axis. Color and style alone do not draw a divider; each
+axis needs its own width. To change axes at a breakpoint, set the old width to
+`0` and the new width explicitly.
+
 ## Preflight and themes
 
 Preflight emits low-specificity reset rules and theme variables. Set
@@ -50,11 +68,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,67 +82,227 @@ 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.
+### Global role palettes and color scheme
 
-## Class merging
+Standard has seven 12-step roles: primary → gray, neutral → sage, focused →
+neutral, success → jade, warning → amber, failure → red, and general → blue.
+Use numbered roles directly, such as `bg-color:primary-200 text-color:primary-950`.
+Official adds structure without background/hover/foreground color aliases.
 
-```ts
-import { cn, pluginStandard } from "@teacss/preset-standard/merge";
+The CSS entry registers the selectable built-in physical palettes:
 
-cn("p:4 d:flex", "p:8"); // "d:flex p:8"
-cn("p:4", "p:invalid"); // "p:invalid"
+```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;
 ```
 
-The `/merge` entry also exports `createStandardMerger()`. Merge uses token
-shape and does not validate values. Combine preset plugins for a wider merger:
+Repeated/imported lists union and sort. They enable choices without changing
+defaults; removing every list for a role clears its choices. Only Standard's
+original built-in physical palette names are candidates. Overrides through
+`@custom` or `theme.colors` keep that identity; custom names remain available to
+ordinary color utilities but cannot become role candidates. Enabled palettes
+need all 12 effective steps and no direct/transitive role references, including
+mode overrides, `preflightBase`, and variable fallbacks. Candidate registration
+has no public Theme field; programmatic consumers load the CSS entry with
+`resolveEntryConfig()`.
+
+```html
+<html data-css-primary="blue" data-css-neutral="slate" data-css-scheme="dark">
+  <body><p class="text-color:primary-900">Global blue / slate / dark</p></body>
+</html>
+```
+
+Only html role attributes, `data-css-scheme` and configured mode aliases select
+colors. Descendants inherit; the same markers on descendants have no effect.
+Missing, empty, unknown or undeclared role values use configured defaults.
+Focused defaults to final global neutral while preserving explicit default
+step overrides. Valid root focused selection chooses an independent palette.
+Changing root attributes switches registered candidates without regenerating CSS.
+
+`@dark` / `@light` inspect html for every final target, including pseudo-elements.
+Without a valid explicit mode, neither condition activates, even when `defaultMode` is
+dark; `defaultMode` names the base table. OS conditions remain independent media
+queries. `modeSelectors: { dark: ".night", light: ".day" }` adds optional aliases
+on html. Canonical `data-css-scheme` wins even when empty/invalid; conflicting
+aliases select neither mode. Aliases are never implicit. Mode names preserve
+case, spaces and punctuation; empty names, NUL and unpaired surrogates are invalid.
+
+Theme output uses zero-specificity ordinary html selectors: base variables once,
+mode differences, then independent role mappings. Each role/candidate mapping is
+emitted once, without multiplying it by modes or other roles. `preflightRoot`
+adds explicit re-declaration targets that always use html selections; it does not
+enable local colors. On-demand preflight retains the consumed dependency closure
+through all registered candidates and effective modes. With preflight disabled,
+root mode conditions still work but the application supplies variables.
+
+Global `@custom` sets scales and colors; `@custom dark` changes colors only.
+Whole-theme variants and role scheme blocks are unsupported. Color selection
+never resets inherited spacing or changes radius/shadow geometry.
+
+### Spacing scaling
+
+The default chain is `--scaling → --spacing → default 1x…9x`:
+
+```css
+--spacing: calc(0.25rem * var(--scaling, 1));
+--spacing-1x: var(--spacing);
+--spacing-5x: calc(var(--spacing) * 6);
+```
+
+Set the existing variable utility on html, such as `$scaling:0.5@sm`, to halve
+numeric and default named spacing at the configured `sm` breakpoint (768px by
+default). Named multipliers remain `1,2,3,4,6,8,10,12,16`. Only the base formula
+reads scaling; no extra multiplier or default `--scaling` declaration is emitted.
+
+A root override of `--spacing` replaces the base formula and also changes default
+named steps. Explicit named overrides remain final values; reference `--spacing`
+to make a custom step follow the chain. Fixed lengths and unrelated scales are
+unchanged. Variables resolve where declared, so a descendant-only scaling change
+does not recompute inherited root spacing. Existing `preflightRoot` follows normal
+CSS re-declaration semantics. No density configuration or additional rule is needed.
+
+### 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>
+```
+
+`@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` and descendant color markers 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
 
 - Logical border width/style pairs accept two arbitrary components, such as
-  `border-a-width:[1px_2px]`; physical x/y and single-edge forms accept one.
+  `border-inline-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. `animation:spin` rotates
+  at `1s linear infinite`; `animation:spinner` fades a spinner leaf from opacity
+  `1` to `.25` at `800ms linear infinite`. Duration, timing, and iteration
+  utilities override these defaults. Gate decorative motion with `@motion-safe`
+  or stop it with `animation:none@motion-reduce`.
 - 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-inline-reverse:on space-block-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

@@ -74,7 +74,7 @@ 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;
   breakpoint?: Record<string, string>;
   container?: Record<string, string>;
@@ -100,8 +100,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-scheme` on html (or a
+   * configured `dark`/`light` alias). Only declare values that differ. OS
    * preference uses `@os-dark` / `@os-light`.
    */
   modes?: Record<string, {
@@ -110,38 +110,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 that re-declare the complete theme selected on html. */
   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 html selector aliases for `dark` / `light`; canonical `data-css-scheme` 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` html aliases, e.g. `{ dark: ".night" }`; no aliases are enabled by default. */
   modeSelectors?: ModeSelectors;
   /**
    * Container sizes for the `@container-*` conditions, merged over the default