@mastors/core 1.1.0 → 2.0.0

package/README.md

@@ -20,7 +20,6 @@
   - [Feature flags](#feature-flags)
   - [Dark mode strategy](#dark-mode-strategy)
   - [Class prefix](#class-prefix)
-  - [Config via public API](#config-via-public-api)
 - [Design Tokens](#design-tokens)
   - [Color](#color)
   - [Spacing](#spacing)
@@ -31,7 +30,6 @@
   - [Opacity](#opacity)
   - [Transitions](#transitions)
 - [Functions](#functions)
-  - [vars()](#vars)
 - [Mixins](#mixins)
   - [Breakpoints](#breakpoints)
   - [Theme](#theme)
@@ -61,7 +59,7 @@
 `@mastors/core` is the only required package in the Mastors ecosystem. It provides:
 
 - **Design tokens** — color, spacing, typography, radius, shadows, z-index, opacity, and transitions as SCSS maps
-- **Functions** — `rem()`, `em()`, `color()`, `spacing()`, `tint()`, `shade()`, `alpha()`, `contrast()`, `fluid()`, `map-deep-get()`, `map-collect()`, `str-replace()`, `vars()`
+- **Functions** — `rem()`, `em()`, `color()`, `spacing()`, `tint()`, `shade()`, `alpha()`, `contrast()`, `fluid()`, `map-deep-get()`, `map-collect()`, `str-replace()`
 - **Mixins** — `bp()`, `dark-mode()`, `light-mode()`, `theme()`, `elevation()`, `transition()`, `container()`, `pseudo()`
 - **Generator engine** — `generate-utilities()`, `emit-custom-properties()`, and responsive-generator mixins used by all utility packages
 - **Reset** — modern CSS reset and document defaults
@@ -69,8 +67,7 @@
 - **Responsive engine** — breakpoint-aware utility variant generation (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`)
 - **Container queries** — `.cq-inline`, `.cq-size`, `cq()` mixin for `@container` rules
 - **Fluid typography** — `fluid-type()` mixin and function using `clamp()`
-- **Utility classes** — display, position, overflow, spacing, sizing, colors, borders (full directional radius scale), shadows, opacity, cursor, z-index, transforms, typography, animation, interaction, layout (aspect-ratio, object-fit/position, blend modes)
-- **Accessibility** — focus ring, reduced-motion, screen-reader utilities, print layer
+- **Utility classes** — display, position, overflow, spacing, sizing, colors, borders (full directional radius scale), shadows, opacity, cursor, z-index, transforms
 - **TypeScript types and runtime token mirror**
 
 All other `@mastors/*` packages consume `@mastors/core/api` for shared tokens, functions, and mixins.
@@ -101,7 +98,7 @@ Import the complete compiled stylesheet — reset, tokens, themes, utilities, he
 
 ### Public API (zero output)
 
-Import only the public API surface. No CSS is emitted — you get access to all tokens, functions, mixins, and config:
+Import only the public API surface. No CSS is emitted — you get access to all tokens, functions, and mixins for use in your own components:
 
 ```scss
 @use "@mastors/core/api" as m;
@@ -110,8 +107,7 @@ Import only the public API surface. No CSS is emitted — you get access to all
   padding:          m.spacing(6);
   background-color: m.color("neutral", 50);
   border-radius:    m.radius("xl");
-  box-shadow:       m.vars(shadow-md);
-  transition:       box-shadow m.vars(duration-200) m.vars(ease-out);
+  box-shadow:       m.shadow("md");
 
   @include m.bp("lg") {
     padding: m.spacing(10);
@@ -209,22 +205,6 @@ $mastors-config: ("prefix": "m-") !default;
 // .m-flex, .m-block, .m-grid-cols-3, ...
 ```
 
-### Config via public API
-
-As of v1.2, both the `$mastors-config` map / `config()` accessor and all `$enable-*` flags are forwarded through the public API surface. Downstream consumers no longer need a direct partial import to read them:
-
-```scss
-@use "@mastors/core/api" as m;
-
-// Read a config value
-$prefix: m.config("prefix");
-
-// Read feature flags
-@if m.$enable-responsive {
-  // emit responsive variants
-}
-```
-
 ---
 
 ## Design Tokens
@@ -378,49 +358,8 @@ m.easing("bounce")  // cubic-bezier(0.34, 1.56, 0.64, 1)
 | `map-deep-get($map, $keys...)` | Deep nested map access | `map-deep-get($tokens, "primary", "600")` |
 | `map-collect($maps...)` | Shallow-merge multiple maps | `map-collect($a, $b)` |
 | `str-replace($str, $search)` | Replace substring | `str-replace("a-b", "-", "_")` |
-| `vars($token, $fallback?)` | CSS custom property reference | `vars(shadow-md)` -> `var(--mastors-shadow-md)` |
-
-(1) `contrast()` uses a simplified linear luminance approximation without sRGB gamma expansion. The threshold is set to `0.35` (not the WCAG `0.179`) to compensate for the missing gamma step — this gives correct results across the neutral scale. Suitable for UI decisions; implement full sRGB linearisation for strict WCAG 2.1 contrast-ratio auditing.
-
-### vars()
-
-`vars()` lets you reference any emitted design token as a CSS custom property by name, without hard-coding the `--mastors-` prefix. If the token name ever changes or the prefix is reconfigured, only the function implementation needs to update — all call sites stay the same.
-
-```scss
-@use "@mastors/core/api" as m;
-
-.button {
-  // Basic token reference
-  color:       m.vars(accent);
-  box-shadow:  m.vars(shadow-sm);
-
-  // With CSS fallback (passed through verbatim)
-  background:  m.vars(surface-raised, #f9fafb);
-  transition:  opacity m.vars(duration-150) m.vars(ease-out);
-
-  &:hover {
-    box-shadow: m.vars(shadow-md);
-    transform:  translateY(-1px);
-  }
-}
-
-// Composes cleanly with other values in shorthand properties
-.chip {
-  border: 1px solid m.vars(border);
-  padding: m.rem(4px) m.rem(10px);
-}
-```
 
-Token names follow the same `--mastors-{name}` convention used in `:root`. Common examples:
-
-| Call | Emits |
-|---|---|
-| `m.vars(accent)` | `var(--mastors-accent)` |
-| `m.vars(surface)` | `var(--mastors-surface)` |
-| `m.vars(shadow-lg)` | `var(--mastors-shadow-lg)` |
-| `m.vars(duration-200)` | `var(--mastors-duration-200)` |
-| `m.vars(ease-in-out)` | `var(--mastors-ease-in-out)` |
-| `m.vars(border, #e5e7eb)` | `var(--mastors-border, #e5e7eb)` |
+(1) `contrast()` uses a simplified linear luminance approximation, not the full WCAG 2.1 gamma-expanded formula. Suitable for UI decisions, not for strict accessibility audits.
 
 ---
 
@@ -508,9 +447,7 @@ Mobile-first, min-width media queries using the named breakpoint map.
 
 ## Responsive Engine
 
-The engine in `responsive/_engine.scss` wraps utility maps in breakpoint media queries. Sub-packages can call `@include engine.run($utilities)` directly for standalone use.
-
-For the standard workflow, responsive variant generation is built into `generate-utilities()` — any utility entry that declares `responsive: true` automatically emits both base classes and breakpoint-prefixed variants in a single call. No separate invocation is required.
+The engine in `responsive/_engine.scss` wraps utility maps in breakpoint media queries. Sub-packages call `@include engine.run($utilities)` in their responsive layer.
 
 Generated class pattern: `.{breakpoint}\:{class}`
 
@@ -526,7 +463,8 @@ Generated class pattern: `.{breakpoint}\:{class}`
 ```
 
 Utilities with responsive support at v1.0: `display`, `position`.
-Additional responsive utilities added in v1.2: `text-align`, `float`, `flex-direction` (via flexer), `grid-template-columns` (via gridder).
+
+> Spacing, sizing, and color utilities use direct `@each` loops in v1.0 and do not generate responsive variants by default. Responsive variants for those groups are planned for a future minor release.
 
 ---
 
@@ -639,16 +577,6 @@ Use semantic custom properties directly in your CSS for automatic theme switchin
 }
 ```
 
-Or use `vars()` in SCSS for the same result without the prefix noise:
-
-```scss
-.card {
-  background-color: m.vars(surface);
-  color:            m.vars(text);
-  border-color:     m.vars(border);
-}
-```
-
 Custom themes can be applied with any `data-theme` attribute:
 
 ```scss
@@ -703,12 +631,8 @@ When importing the full stylesheet, core emits these utility classes:
 | Pointer events | `.pointer-events-none` `.pointer-events-auto` |
 | Z-index | `.z-base` `.z-dropdown` `.z-modal` `.z-tooltip` etc. |
 | Transforms | `.translate-x-*` `.translate-y-*` `.rotate-*` `.scale-*` `.origin-*` `.transform-gpu` `.transform-none` |
-| Typography | `.text-{left\|center\|right\|justify\|start\|end}` (responsive) · `.text-{xs…9xl}` · `.font-{thin…black}` · `.font-{sans\|mono\|display}` · `.italic` `.not-italic` · `.leading-*` · `.tracking-*` · `.underline` `.overline` `.line-through` `.no-underline` · `.decoration-{solid\|dashed\|dotted\|double\|wavy}` · `.decoration-{1\|2\|4\|8}` · `.uppercase` `.lowercase` `.capitalize` `.normal-case` · `.text-ellipsis` `.text-clip` · `.whitespace-*` · `.break-normal` `.break-words` `.break-all` `.break-keep` · `.align-{baseline\|top\|middle\|bottom}` · `.list-none` `.list-disc` `.list-decimal` · `.antialiased` `.subpixel-antialiased` |
-| Animation | `.transition` `.transition-{colors\|opacity\|shadow\|transform\|none\|all}` · `.duration-*` · `.ease-*` · `.delay-*` · `.animate-{spin\|ping\|pulse\|bounce\|fade-in\|fade-out\|slide-up\|slide-down\|scale-in\|none}` · `.fill-{none\|forwards\|backwards\|both}` · `.animation-{running\|paused}` · `.animate-repeat-{0\|1\|infinite}` |
-| Interaction | `.select-{none\|text\|all\|auto}` · `.resize-{none\|x\|y}` `.resize` · `.scroll-{auto\|smooth}` · `.snap-{none\|x\|y\|both\|mandatory\|proximity}` · `.snap-{start\|end\|center}` · `.snap-stop-{always\|normal}` · `.scroll-m-*` `.scroll-p-*` · `.touch-{auto\|none\|pan-x\|pan-y\|manipulation}` · `hover:opacity-*` `hover:bg-accent` `hover:underline` `hover:shadow-lg` `hover:scale-{105\|110}` `hover:-translate-y-1` · `focus:ring` `focus:ring-2` `focus:ring-offset-2` `focus:ring-none` · `disabled:opacity-50` `disabled:cursor-not-allowed` `disabled:pointer-events-none` |
-| Layout | `.aspect-{auto\|square\|video\|4-3\|3-2\|21-9\|9-16\|golden}` · `.object-{contain\|cover\|fill\|none\|scale-down}` · `.object-{center\|top\|bottom\|left\|right\|…}` · `.float-{left\|right\|none\|start\|end}` (responsive) · `.clear-*` · `.isolate` `.isolation-auto` · `.mix-blend-*` · `.bg-blend-*` · `.box-decoration-{clone\|slice}` · `.appearance-{none\|auto}` · `.will-change-{auto\|scroll\|contents\|transform}` |
 
-Display and position utilities support responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`). Text-align and float also support responsive prefixes.
+Display and position utilities support responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`).
 
 ---
 
@@ -744,16 +668,6 @@ Display and position utilities support responsive prefixes (`sm:`, `md:`, `lg:`,
 | `:focus-visible` | 2px primary-500 ring, 2px offset — keyboard only |
 | `:focus:not(:focus-visible)` | Removes ring for mouse/pointer users |
 | `prefers-reduced-motion: reduce` | Collapses all animation/transition durations to 0.01ms |
-| `.print\:hidden` | `display: none` inside `@media print` |
-| `.screen\:hidden` | `display: none` outside `@media print` (print-only element) |
-| `.print\:break-inside-avoid` | Prevents page breaks inside the element when printing |
-| `.print\:break-before` | Forces a page break before the element |
-| `.print\:break-after` | Forces a page break after the element |
-| `.print\:text-black` | Forces `color: #000` for print output |
-| `.print\:bg-white` | Forces `background: #fff` for print output |
-| `.print\:border-none` | Removes borders for print output |
-| `.print\:shadow-none` | Removes box-shadow for print output |
-| `a[href]::after` *(print)* | Appends `(url)` after links so destinations are visible on paper |
 
 ---
 
@@ -765,10 +679,6 @@ The three generator mixins are the engine behind all utility class output in the
 
 Generates utility classes from a configuration map. Used by `@mastors/flexer`, `@mastors/gridder`, and all core utility partials.
 
-The mixin runs in two passes:
-- **Pass 1** — emits base (unprefixed) classes for every entry.
-- **Pass 2** — for every entry with `responsive: true`, iterates all breakpoints (skipping `xs`/0px) and emits breakpoint-prefixed variants inside `@media` blocks. Respects the `$enable-responsive` flag and the global prefix/`!important` config.
-
 ```scss
 @use "@mastors/core/scss/generators/class-generator" as gen;
 
@@ -784,8 +694,6 @@ The mixin runs in two passes:
     ),
   ),
 ));
-// Emits: .text-left, .text-center, .text-right
-// And:   .sm\:text-left, .md\:text-left, … for all breakpoints
 ```
 
 ### `emit-custom-properties($map, $prefix)`
@@ -870,17 +778,14 @@ These stubs are documented in each file's header comment.
 /* Full stylesheet — reset + tokens + themes + utilities */
 @use "@mastors/core/scss";
 
-/* Public API — zero CSS output, all tokens/mixins/functions/config */
+/* Public API — zero CSS output, all tokens/mixins/functions */
 @use "@mastors/core/api" as m;
 
 /* Individual partials */
 @use "@mastors/core/scss/tokens/color" as ct;
 @use "@mastors/core/scss/mixins/breakpoint" as bp;
 @use "@mastors/core/scss/functions/rem" as r;
-@use "@mastors/core/scss/functions/vars";       /* vars() standalone */
 @use "@mastors/core/scss/responsive/fluid-type" as ft;
-@use "@mastors/core/scss/config/settings";      /* $mastors-config, config() */
-@use "@mastors/core/scss/config/flags";         /* $enable-* flags */
 ```
 
 ```ts
@@ -903,31 +808,17 @@ import type { MastorsConfig, Breakpoint, ThemeMode, Tokens } from '@mastors/core
 
 ## Changelog
 
-### v1.2.0
-
-- **Added:** `vars($token, $fallback?)` function in `functions/_vars.scss` — wraps the `--mastors-` namespace so downstream consumers reference tokens as `var(--mastors-{name})` without hard-coding the prefix. Namespace stored in `$-namespace: "mastors" !default`. Forwarded through `functions/_index.scss` and exposed via `@use "@mastors/core/api"`.
-- **Added:** `config/_index.scss` shim — `@forward`s both `_settings.scss` and `_flags.scss`. `api/_index.scss` now includes `@forward "../config/index"`, exposing `config()` accessor and all `$enable-*` flags through the public API surface without a direct partial import.
-- **Added:** `utilities/_typography.scss` — full typography utility surface covering text-align (responsive), font-size (token-driven `@each`), font-weight (token-driven), font-family (token-driven), font-style (`.italic` / `.not-italic`), line-height / leading (token-driven), letter-spacing / tracking (token-driven), text-decoration (line + style + thickness), text-transform, text-overflow, white-space, word-break, text-indent, vertical-align, list-style, font-smoothing.
-- **Added:** `utilities/_animation.scss` — transition-property presets (`.transition`, `.transition-colors`, `.transition-opacity`, `.transition-shadow`, `.transition-transform`, `.transition-none`, `.transition-all`), token-driven `.duration-*` and `.delay-*`, token-driven `.ease-*`, named animation presets (`.animate-spin/ping/pulse/bounce/fade-in/fade-out/slide-up/slide-down/scale-in/none`), full `@keyframes` definitions prefixed `mastors-*`, animation fill-mode / play-state / iteration utilities.
-- **Added:** `utilities/_interaction.scss` — user-select, resize, scroll-behavior (`.scroll-auto` / `.scroll-smooth`), scroll-snap (type + align + stop + scroll-margin/padding), touch-action, and state-variant pseudo-class utilities: `hover:opacity-*`, `hover:bg-accent`, `hover:text-accent`, `hover:underline`, `hover:no-underline`, `hover:shadow-lg`, `hover:scale-105`, `hover:scale-110`, `hover:-translate-y-1`, `focus:ring`, `focus:ring-2`, `focus:ring-offset-2`, `focus:ring-none`, `disabled:opacity-50`, `disabled:cursor-not-allowed`, `disabled:pointer-events-none`.
-- **Added:** `utilities/_layout.scss` — aspect-ratio block (`.aspect-auto`, `.aspect-square`, `.aspect-video`, `.aspect-4-3`, `.aspect-3-2`, `.aspect-21-9`, `.aspect-9-16`, `.aspect-golden`; the `$-aspect-ratios` map is `!default`-overridable). Documented alongside object-fit and object-position which were already present.
-- **Added:** `accessibility/_print.scss` — `print:hidden`, `screen:hidden`, `print:break-inside-avoid`, `print:break-before`, `print:break-after`, `print:text-black`, `print:bg-white`, `print:border-none`, `print:shadow-none`, automatic `a[href]::after` link expansion, suppression for `#` and `javascript:` links.
-
 ### v1.0.0
 
 - Initial public release
 - Full token system: color, spacing, typography, radii, shadows, z-index, opacity, transitions, sizing
 - Complete functions layer: `rem`, `em`, `color`, `spacing`, `radius`, `shadow`, `z`, `opacity`, `duration`, `easing`, `tint`, `shade`, `alpha`, `contrast`, `fluid`, `map-deep-get`, `map-collect`, `str-replace`
 - Complete mixins layer: `bp`, `respond-to`, `breakpoint-up`, `breakpoint-down`, `dark-mode`, `light-mode`, `theme`, `elevation`, `transition`, `container`, `pseudo`
-- **Fixed:** `generate-utilities()` now runs a two-pass emit — Pass 1 outputs base classes, Pass 2 automatically emits breakpoint-prefixed responsive variants for all entries with `responsive: true`. Previously responsive variants were silently not emitted.
-- **Fixed:** `generators/_responsive-generator.scss` replaced the `@content`-based no-op stub with a thin wrapper that correctly delegates to `engine.run()` for backward compatibility.
-- **Fixed:** `contrast()` luminance threshold corrected from `0.179` (WCAG linearised) to `0.35` (calibrated for the simplified non-gamma-expanded approximation in use). Prevents wrong light/dark decisions on mid-grey backgrounds.
-- **Added:** `stylelint` linting with `stylelint-config-standard-scss` — `pnpm lint` now runs real SCSS style checks. `postcss-scss`, `stylelint`, and `stylelint-config-standard-scss` added to `devDependencies`; `.stylelintrc.json` added to `packages/core`.
-- Generator engine: `generate-utilities` (with integrated responsive Pass 2), `emit-custom-properties`, `emit-nested-custom-properties`
+- Generator engine: `generate-utilities`, `emit-custom-properties`, `emit-nested-custom-properties`
 - Responsive engine with correct numeric breakpoint escaping (`2xl:` prefix)
 - Container queries: `.cq-inline`, `.cq-size`, `.cq-normal`, `[data-container]`, `cq()` mixin
 - Fluid typography: `fluid-type()` mixin + function + `fluid-scale()` preset
-- Full directional border-radius utility scale — all four sides x all token steps
+- Full directional border-radius utility scale — all four sides x all token steps (fixed from partial `lg`-only coverage)
 - Light and dark themes via CSS custom property semantic contract (15 semantic props)
 - Modern CSS reset — no duplicate `box-sizing` declarations
 - Accessibility layer: `:focus-visible` ring, `prefers-reduced-motion` override, `.sr-only`, `.visually-hidden`