@greese/ui 0.0.0-stage → 1.0.0

package/src/styles/_mixins.scss

@@ -0,0 +1,261 @@
+// greese ui's build-time SCSS toolkit. Nothing here reaches the browser except
+// the CSS these mixins compile to.
+@use 'sass:map';
+@use 'sass:string';
+@use 'config';
+
+$breakpoints: config.$breakpoints;
+
+/// Mobile-first media query: styles apply from `$bp` upward. `xs` needs none.
+@mixin up($bp) {
+  $min: map.get($breakpoints, $bp);
+
+  @if not $min {
+    @error 'Unknown breakpoint `#{$bp}`. Expected one of #{map.keys($breakpoints)}.';
+  }
+
+  @if $min <= 0 {
+    @content;
+  } @else {
+    @media (width >= $min) {
+      @content;
+    }
+  }
+}
+
+/// Styles apply below `$bp` only: the complement of `up($bp)`.
+@mixin down($bp) {
+  $min: map.get($breakpoints, $bp);
+
+  @if not $min or $min <= 0 {
+    @error 'down() needs a breakpoint above xs, got `#{$bp}`.';
+  }
+
+  @media (width < $min) {
+    @content;
+  }
+}
+
+/// The custom property holding one breakpoint's value of a responsive prop.
+/// Must match `responsiveVar()` in src/utils/responsive.ts.
+@function responsive-var($block, $prop, $bp) {
+  @return --#{string.to-lower-case($block)}-#{$prop}-#{$bp};
+}
+
+/// `$template` with its `VALUE` placeholder replaced, or `$value` alone.
+@function _fill($template, $value) {
+  @if not $template {
+    @return $value;
+  }
+
+  $at: string.index($template, 'VALUE');
+
+  @return string.unquote(
+    string.slice($template, 1, $at - 1) + '#{$value}' + string.slice($template, $at + 5)
+  );
+}
+
+/// One breakpoint's rules: the value class, then a class per token.
+@mixin _breakpoint-rules($block, $prop, $bp, $properties, $tokens, $template, $scope) {
+  $prefix: '';
+
+  @if $scope {
+    $prefix: '#{$scope} ';
+  }
+
+  #{$prefix}.#{$block}--#{$bp}-#{$prop} {
+    @each $property in $properties {
+      #{$property}: _fill($template, var(#{responsive-var($block, $prop, $bp)}));
+    }
+  }
+
+  @each $key, $value in $tokens {
+    #{$prefix}.#{$block}--#{$bp}-#{$prop}-#{$key} {
+      @each $property in $properties {
+        #{$property}: _fill($template, $value);
+      }
+    }
+  }
+}
+
+/// A responsive prop: a class per breakpoint and value that sets the
+/// property directly (docs/adr/0001-styling-model.md).
+///
+/// For each breakpoint, smallest first, inside that breakpoint's media query:
+///   - a value class, `.#{$block}--#{bp}-#{$prop}`, reading the breakpoint's
+///     variable (`--greese-stack-gap-md`), for open-ended values that
+///     `resolveResponsive()` sets inline;
+///   - for each `$tokens` entry, `.#{$block}--#{bp}-#{$prop}-#{key}`.
+///
+/// Every class has the same specificity, so source order is the
+/// mobile-first fallback: a larger breakpoint's class comes later and wins
+/// where it applies, and below it the smaller one's still does. A breakpoint
+/// with no class leaves the property to the component's own styles, so an
+/// unset prop costs nothing and never overrides a default. There is no
+/// `var()` chain and nothing to register: each variable is read only by the
+/// element that sets it, which was the fastest form in measurement (ADR
+/// 0001, 2026-10-19 addendum).
+///
+/// With `$container-scope`, the same rules are emitted again under
+/// `@container`, prefixed with the scope so they win inside it.
+///
+/// @param $block           component root class, without the dot: 'greese-Stack'
+/// @param $prop            prop segment in class and variable names: 'gap'
+/// @param $properties      CSS property, or list of them, to set
+/// @param $tokens          map of token key to CSS value, one class each
+/// @param $template        wraps each value: 'repeat(auto-fill, minmax(VALUE, 1fr))'
+/// @param $container-scope selector prefix whose container-query variant
+///                         applies: '.greese-Grid--container >'
+///
+/// Use it at the top level of a layer block, not nested in a selector.
+@mixin responsive-prop(
+  $block,
+  $prop,
+  $properties,
+  $tokens: (),
+  $template: null,
+  $container-scope: null
+) {
+  @each $bp, $min in $breakpoints {
+    @include up($bp) {
+      @include _breakpoint-rules(
+        $block,
+        $prop,
+        $bp,
+        $properties,
+        $tokens,
+        $template,
+        null
+      );
+    }
+  }
+
+  @if $container-scope {
+    @each $bp, $min in $breakpoints {
+      @if $min <= 0 {
+        @include _breakpoint-rules(
+          $block,
+          $prop,
+          $bp,
+          $properties,
+          $tokens,
+          $template,
+          $container-scope
+        );
+      } @else {
+        @container (width >= #{$min}) {
+          @include _breakpoint-rules(
+            $block,
+            $prop,
+            $bp,
+            $properties,
+            $tokens,
+            $template,
+            $container-scope
+          );
+        }
+      }
+    }
+  }
+}
+
+/// The spacing scale as a `$tokens` map for `responsive-prop()`.
+@function space-tokens() {
+  $map: ();
+
+  @each $key in config.$space-keys {
+    $map: map.set($map, $key, var(--greese-space-#{$key}));
+  }
+
+  @return $map;
+}
+
+/// Hover styles only where hover exists, so taps never leave sticky hovers.
+@mixin hover {
+  @media (hover: hover) {
+    &:hover {
+      @content;
+    }
+  }
+}
+
+/// The standard keyboard focus indicator.
+@mixin focus-ring($offset: 2px) {
+  &:focus-visible {
+    outline: 2px solid var(--greese-color-focus-ring);
+    outline-offset: $offset;
+  }
+}
+
+/// Grows the hit area to at least `$size` on touch screens without changing
+/// the visual size. The element must be positioned (relative, absolute, …).
+@mixin touch-target($size: 44px) {
+  @media (pointer: coarse) {
+    &::after {
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      inline-size: max(100%, #{$size});
+      block-size: max(100%, #{$size});
+      content: '';
+      translate: -50% -50%;
+    }
+  }
+}
+
+/// Content that switches in (a tab's panel, an accordion's content): the
+/// container stays put and its children enter, a stagger apart. Not when the
+/// container has a `greese` entrance of its own (`.greese-Motion`), which then
+/// plays instead. A theme changes the entrance with `animation-name` on the
+/// same selector (ADR 0025).
+@mixin content-entrance {
+  &:not(.greese-Motion) > * {
+    @include motion-safe {
+      @include role-entrance(content, greese-content-in, normal);
+    }
+
+    @for $i from 2 through 6 {
+      &:nth-child(#{$i}) {
+        animation-delay: calc(var(--greese-motion-stagger, 0.04s) * #{$i - 1});
+      }
+    }
+  }
+}
+
+/// An entrance a theme assigns by role (ADR 0025): `--greese-motion-<role>`
+/// names the effect, `--greese-motion-<role>-duration` its duration, and
+/// `--greese-motion-enter-ease` the curve every role arrives on. Each falls
+/// back to the base theme's. A theme points a role at an effect or a token;
+/// the effect and the token keep their own values.
+@mixin role-entrance($role, $name, $duration, $ease: var(--greese-easing-enter)) {
+  animation-name: var(--greese-motion-#{$role}, #{$name});
+  animation-duration: var(
+    --greese-motion-#{$role}-duration,
+    var(--greese-duration-#{$duration})
+  );
+  animation-timing-function: var(--greese-motion-enter-ease, #{$ease});
+  animation-fill-mode: backwards;
+}
+
+/// The entrance `content-entrance` plays unless a theme picks another.
+@mixin content-entrance-keyframes {
+  @keyframes greese-content-in {
+    from {
+      opacity: 0;
+      translate: 0 0.25rem;
+    }
+  }
+}
+
+/// Motion beyond duration tokens (which already collapse under reduced
+/// motion), e.g. keyframe animations or transforms.
+@mixin motion-safe {
+  @media (prefers-reduced-motion: no-preference) {
+    @content;
+  }
+}
+
+/// Baseline for every component root.
+@mixin component-root {
+  box-sizing: border-box;
+}

package/src/styles/_tones.scss

@@ -0,0 +1,63 @@
+@use 'sass:list';
+
+// Color roles shared by every component with a `tone` prop.
+// A tone sets two variables on the component: the color and the color of
+// content drawn on top of it.
+
+$tones: (
+  neutral: (
+    var(--greese-color-fg),
+    var(--greese-color-canvas),
+  ),
+  muted: (
+    var(--greese-color-fg-muted),
+    var(--greese-color-canvas),
+  ),
+  primary: (
+    var(--greese-color-primary),
+    var(--greese-color-primary-content),
+  ),
+  secondary: (
+    var(--greese-color-secondary),
+    var(--greese-color-secondary-content),
+  ),
+  tertiary: (
+    var(--greese-color-tertiary),
+    var(--greese-color-tertiary-content),
+  ),
+  accent: (
+    var(--greese-color-accent),
+    var(--greese-color-accent-content),
+  ),
+  positive: (
+    var(--greese-color-positive),
+    var(--greese-color-canvas),
+  ),
+  negative: (
+    var(--greese-color-negative),
+    var(--greese-color-negative-content),
+  ),
+  warning: (
+    var(--greese-color-warning),
+    var(--greese-color-canvas),
+  ),
+  info: (
+    var(--greese-color-info),
+    var(--greese-color-canvas),
+  ),
+);
+
+// The brand roles, in order, as a list for components that style them by hand.
+$brand: (primary, secondary, tertiary, accent);
+
+/// Emits `.#{$block}--#{tone}` classes setting `--#{$var}` and `--#{$var}-on`.
+@mixin classes($block, $var, $only: null) {
+  @each $tone, $pair in $tones {
+    @if not $only or list.index($only, $tone) {
+      .#{$block}--#{$tone} {
+        --#{$var}: #{list.nth($pair, 1)};
+        --#{$var}-on: #{list.nth($pair, 2)};
+      }
+    }
+  }
+}

package/src/styles/_type-emit.scss

@@ -0,0 +1,76 @@
+// Writes the type system's custom properties from a typography map, in the
+// build's breakpoints: the smallest screen's values at the selector, then one
+// media query per breakpoint that changes any, smallest first.
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use 'config';
+@use 'mixins';
+
+@function value($value) {
+  @if meta.type-of($value) == string {
+    @return string.unquote($value);
+  }
+
+  @if meta.type-of($value) == list {
+    @return string.unquote(meta.inspect($value));
+  }
+
+  @return $value;
+}
+
+/// One point's values as a map of `--greese-type-<variant>-<prop>: value`.
+/// `base` also takes `xs`, which is the same point.
+@function _point($typography, $point) {
+  $out: ();
+
+  @each $variant, $spec in $typography {
+    $style: map.get($spec, $point) or ();
+
+    @if $point == base {
+      $style: map.merge($style, map.get($spec, xs) or ());
+    }
+
+    @each $prop, $v in $style {
+      $out: map.set($out, '--greese-type-#{$variant}-#{$prop}', $v);
+    }
+  }
+
+  @return $out;
+}
+
+@mixin _declare($declarations, $selector) {
+  @if list.length($declarations) > 0 {
+    #{$selector} {
+      @each $property, $v in $declarations {
+        #{$property}: #{value($v)};
+      }
+    }
+  }
+}
+
+/// The smallest screen's values, for a rule that already declares tokens.
+@function base($typography) {
+  @return _point($typography, base);
+}
+
+@mixin emit($typography, $selector: ':root') {
+  @include _declare(base($typography), $selector);
+  @include emit-media($typography, $selector);
+}
+
+/// The changes at each breakpoint above the smallest.
+@mixin emit-media($typography, $selector: ':root') {
+  @each $bp, $min in config.$breakpoints {
+    @if $bp != xs {
+      $declarations: _point($typography, $bp);
+
+      @if list.length($declarations) > 0 {
+        @include mixins.up($bp) {
+          @include _declare($declarations, $selector);
+        }
+      }
+    }
+  }
+}

package/src/styles/_typography-vars.scss

@@ -0,0 +1,8 @@
+// The type system's custom properties, from this build's typography and
+// breakpoints (the defaults unless you configured them), in the token layer.
+@use 'config';
+@use 'type-emit';
+
+@layer greese.tokens {
+  @include type-emit.emit(config.$typography);
+}

package/src/styles/base.scss

@@ -0,0 +1,80 @@
+// Opt-in global styles, compiled to dist/base.css: a light reset plus page
+// defaults wired to the tokens. Import it only if greese ui owns the page.
+// Usage:
+//   import '@greese/react/base.css'
+//   import '@greese/react/styles.css'
+@use '../../dist/layers';
+
+@layer greese.reset {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  html {
+    text-size-adjust: 100%;
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  body {
+    min-block-size: 100dvh;
+    margin: 0;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  p,
+  figure,
+  blockquote,
+  dl,
+  dd {
+    margin: 0;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  p {
+    overflow-wrap: break-word;
+  }
+
+  img,
+  picture,
+  video,
+  canvas,
+  svg {
+    display: block;
+    max-inline-size: 100%;
+  }
+
+  input,
+  button,
+  textarea,
+  select {
+    font: inherit;
+  }
+}
+
+@layer greese.base {
+  body {
+    font-family: var(--greese-font-body);
+    font-size: var(--greese-type-p2-font-size);
+    line-height: var(--greese-line-height-normal);
+    color: var(--greese-color-fg);
+    background-color: var(--greese-color-canvas);
+    -webkit-font-smoothing: antialiased;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--greese-color-focus-ring);
+    outline-offset: 2px;
+  }
+}

package/src/styles/breakpoints.test.ts

@@ -0,0 +1,73 @@
+// @vitest-environment node
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { compileScss, STYLES } from '../test/sass.ts'
+
+const build = (breakpoints: string): string =>
+  compileScss(`@use 'index' with ($breakpoints: ${breakpoints});`)
+
+const DEFAULTS = 'xs: 0px, sm: 600px, md: 900px, lg: 1200px, xl: 1536px'
+const vars = (css: string) =>
+  [...css.matchAll(/--greese-breakpoint-([a-z0-9]+): ([^;]+);/g)].map((m) => [m[1], m[2]])
+
+describe('breakpoints, fixed when the stylesheet is built', () => {
+  it('declares the defaults as custom properties, in the tokens', () => {
+    const tokens = readFileSync(`${STYLES}../../dist/tokens.css`, 'utf8')
+    expect(vars(tokens)).toEqual([
+      ['xs', '0px'],
+      ['sm', '600px'],
+      ['md', '900px'],
+      ['lg', '1200px'],
+      ['xl', '1536px'],
+    ])
+  })
+
+  it('does not repeat them when built with the defaults', () => {
+    expect(vars(build(`(${DEFAULTS})`)).length).toBe(5)
+  })
+
+  it('adds a key: classes, media queries and a custom property', () => {
+    const css = build(
+      '(xs: 0px, sm: 600px, tablet: 700px, md: 900px, lg: 1200px, xl: 1536px)'
+    )
+    expect(css).toContain('--greese-breakpoint-tablet: 700px;')
+    expect(css).toContain('@media (width >= 700px)')
+    expect(css).toContain('.greese-Stack--tablet-gap-3')
+    expect(css).toContain('.greese-Stack--tablet-gap {')
+    // The configured values replace the defaults in the one stylesheet.
+    const last = css.lastIndexOf('--greese-breakpoint-sm')
+    expect(css.slice(last)).toContain('--greese-breakpoint-sm: 600px')
+  })
+
+  it('changes values, and the custom properties follow', () => {
+    const css = build('(xs: 0px, sm: 480px, md: 768px, lg: 1024px, xl: 1440px)')
+    expect(css).toContain('@media (width >= 768px)')
+    expect(css).not.toContain('@media (width >= 900px)')
+    // The type system follows the build's breakpoints.
+    expect(css).toMatch(
+      /@media \(width >= 768px\)[^@]*--greese-type-h1-font-size: 2\.75rem/
+    )
+    expect(css).toContain('--greese-breakpoint-md: 768px;')
+  })
+
+  it('takes a key that starts with a digit when quoted', () => {
+    const css = build(`(${DEFAULTS}, '2xl': 1800px)`)
+    expect(css).toContain('--greese-breakpoint-2xl: 1800px;')
+    expect(css).toContain('.greese-Stack--2xl-gap-3')
+  })
+
+  it('keeps the keys components use, and the order', () => {
+    expect(() => build('(xs: 0px, sm: 600px, md: 900px)')).toThrow(
+      /must keep the key `lg`/
+    )
+    expect(() =>
+      build('(xs: 100px, sm: 600px, md: 900px, lg: 1200px, xl: 1536px)')
+    ).toThrow(/`xs` must be 0/)
+    expect(() =>
+      build('(xs: 0px, sm: 900px, md: 600px, lg: 1200px, xl: 1536px)')
+    ).toThrow(/must increase/)
+    expect(() =>
+      build('(xs: 0px, sm: 600px, big-one: 700px, md: 900px, lg: 1200px, xl: 1536px)')
+    ).toThrow(/one word, without dashes/)
+  })
+})

package/src/styles/entryPoints.test.ts

@@ -0,0 +1,68 @@
+// @vitest-environment node
+import { describe, expect, it } from 'vitest'
+import manifest from '../../package.json' with { type: 'json' }
+import { compileAsProject, rules } from '../test/sass.ts'
+
+const compile = compileAsProject
+
+const AUTHORING = ['mixins', 'tones', 'floating', 'controls'] as const
+
+describe('the SCSS entry points for theme authors (ADR 0021)', () => {
+  it('are exported, and each compiles alone without writing CSS', () => {
+    const exported = Object.keys(manifest.exports)
+    for (const name of AUTHORING) {
+      expect(exported, name).toContain(`./scss/${name}`)
+      expect(compile(`@use 'pkg:@greese/ui/scss/${name}';`), name).toBe('')
+    }
+  })
+
+  it('give a component’s own members, under the name its source uses', () => {
+    const css = compile(`
+@use 'pkg:@greese/ui/scss/mixins';
+@use 'pkg:@greese/ui/scss/floating';
+@use 'pkg:@greese/ui/scss/controls';
+@use 'pkg:@greese/ui/scss/tones';
+@use 'sass:list';
+@use 'sass:map';
+.a {
+  @include mixins.focus-ring;
+  @include mixins.up(md) { gap: 1px; }
+  @include floating.surface;
+  @include controls.frame;
+  color: list.nth(map.get(tones.$tones, primary), 1);
+}`)
+    expect(css).toContain('@media (width >= 900px)')
+    expect(rules(css, '.a:focus-visible')[0]?.declarations).toContainEqual([
+      'outline',
+      expect.stringMatching(/^2px solid /),
+    ])
+    expect(css).toContain('var(--greese-color-primary)')
+  })
+
+  it('are the modules the kit loads: a configured breakpoint reaches them', () => {
+    const css = compile(`
+@use 'pkg:@greese/ui/scss/config' with ($breakpoints: (xs: 0px, sm: 500px, md: 700px, lg: 1000px, xl: 1400px));
+@use 'pkg:@greese/ui/scss/kit' as greese;
+@use 'pkg:@greese/ui/scss/mixins';
+.a { @include mixins.up(md) { gap: 1px; } }
+.b { @include greese.up(md) { gap: 1px; } }`)
+    expect(css.match(/@media \(width >= 700px\)/g)).toHaveLength(2)
+    expect(css).not.toContain('900px')
+  })
+
+  it('hide what only the library’s own sheets can use', () => {
+    expect(() =>
+      compile(
+        `@use 'pkg:@greese/ui/scss/mixins'; .a { @include mixins.responsive-prop('greese-A', p, padding); }`
+      )
+    ).toThrow(/Undefined mixin/)
+    expect(() =>
+      compile(`@use 'pkg:@greese/ui/scss/mixins'; .a { b: mixins.space-tokens(); }`)
+    ).toThrow()
+    expect(() =>
+      compile(
+        `@use 'pkg:@greese/ui/scss/tones'; .a { @include tones.classes('greese-A', tone); }`
+      )
+    ).toThrow(/Undefined mixin/)
+  })
+})