@greese/ui 1.0.0 → 1.2.0

package/src/styles/_utilities.scss

@@ -0,0 +1,104 @@
+// `pkg:@greese/ui/scss/utilities`: the utility classes (ADR 0019), written by
+// Sass from the same table as `utilities.css`, the Vite plugin and the CLI
+// (src/utilities.ts, as dist/_utilities-table.scss). Built here, they take the
+// breakpoints the stylesheet is built with, so `md-…` agrees with the
+// components' `md` without passing the breakpoints twice:
+//   @use 'pkg:@greese/ui/scss/config' with ($breakpoints: (…));
+//   @use 'pkg:@greese/ui/scss/utilities';
+//   @include utilities.classes($groups: (spacing, layout), $prefix: g);
+// Sass can't read your source to keep only the classes it uses: name them in
+// `$only`, or use the Vite plugin or `greese-utilities --content`, which can.
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use 'config';
+@use '../../dist/maps' as defaults;
+@use '../../dist/utilities-table' as table;
+
+/// The groups, in the order they're written.
+$groups: table.$groups;
+
+@function _name($parts...) {
+  $out: '';
+
+  @each $part in $parts {
+    @if $part and $part != '' {
+      @if $out == '' {
+        $out: '#{$part}';
+      } @else {
+        $out: '#{$out}-#{$part}';
+      }
+    }
+  }
+
+  @return $out;
+}
+
+@mixin _variant($variant, $groups, $only, $prefix) {
+  @each $d in table.$definitions {
+    $group: map.get($d, group);
+    $wanted: not $groups or list.index($groups, $group);
+
+    @if $variant == hover {
+      $wanted: $wanted and map.get($d, hover);
+    } @else if $variant {
+      $wanted: $wanted and map.get($d, responsive);
+    }
+
+    @if $wanted {
+      @each $value, $declarations in map.get($d, values) {
+        $name: _name($prefix, $variant, map.get($d, stem), $value);
+
+        @if not $only or list.index($only, $name) {
+          $selector: '.#{$name}';
+
+          @if $variant == hover {
+            $selector: '#{$selector}:hover';
+          }
+
+          #{$selector} {
+            @each $property, $v in $declarations {
+              #{$property}: string.unquote($v);
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+/// The utility classes, in `@layer greese.utilities`: plain, then `hover-…`
+/// where hover exists, then each breakpoint's (`md-…`), smallest first, so a
+/// larger screen's class wins (mobile first).
+///
+///   $groups   only these groups (`spacing`, `sizing`, `layout`, `flex`,
+///             `grid`, `typography`, `border`, `color`, `effects`); all by default
+///   $only     only these class names, prefix included: your purge list
+///   $prefix   a prefix for every class (`g` gives `g-p-4`)
+@mixin classes($groups: null, $only: null, $prefix: '') {
+  @each $group in $groups or () {
+    @if not list.index(table.$groups, $group) {
+      @error 'greese ui utilities: no group `#{$group}`. Groups: #{meta.inspect(table.$groups)}.';
+    }
+  }
+
+  // stylelint-disable-next-line layer-name-pattern -- the whole list, interpolated
+  @layer #{defaults.$layer-order};
+
+  @layer greese.utilities {
+    @include _variant(null, $groups, $only, $prefix);
+
+    @media (hover: hover) {
+      @include _variant(hover, $groups, $only, $prefix);
+    }
+
+    @each $key, $min in config.$breakpoints {
+      @if $min > 0 {
+        @media (width >= #{$min}) {
+          @include _variant($key, $groups, $only, $prefix);
+        }
+      }
+    }
+  }
+}

package/src/styles/breakpoints.test.ts

@@ -8,7 +8,10 @@ const build = (breakpoints: string): string =>
 
 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]])
+  [...css.matchAll(/--greese-breakpoint-(?!keys)([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', () => {
@@ -20,12 +23,29 @@ describe('breakpoints, fixed when the stylesheet is built', () => {
       ['lg', '1200px'],
       ['xl', '1536px'],
     ])
+    // And their keys, in order, for configureBreakpoints() to read.
+    expect(tokens).toContain('--greese-breakpoint-keys: xs sm md lg xl;')
   })
 
   it('does not repeat them when built with the defaults', () => {
     expect(vars(build(`(${DEFAULTS})`)).length).toBe(5)
   })
 
+  it('declares only the configured ones in a build of its own, keys included', () => {
+    const css = build(
+      '(xs: 0px, sm: 600px, tablet: 700px, md: 777px, lg: 1200px, xl: 1536px)'
+    )
+    expect(vars(css)).toEqual([
+      ['xs', '0px'],
+      ['sm', '600px'],
+      ['tablet', '700px'],
+      ['md', '777px'],
+      ['lg', '1200px'],
+      ['xl', '1536px'],
+    ])
+    expect(css).toContain('--greese-breakpoint-keys: xs sm tablet md lg xl;')
+  })
+
   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)'

package/src/styles/entryPoints.test.ts

@@ -5,7 +5,15 @@ import { compileAsProject, rules } from '../test/sass.ts'
 
 const compile = compileAsProject
 
-const AUTHORING = ['mixins', 'tones', 'floating', 'controls'] as const
+const AUTHORING = [
+  'mixins',
+  'breakpoints',
+  'tones',
+  'floating',
+  'controls',
+  'slides',
+  'utilities',
+] as const
 
 describe('the SCSS entry points for theme authors (ADR 0021)', () => {
   it('are exported, and each compiles alone without writing CSS', () => {
@@ -14,7 +22,7 @@ describe('the SCSS entry points for theme authors (ADR 0021)', () => {
       expect(exported, name).toContain(`./scss/${name}`)
       expect(compile(`@use 'pkg:@greese/ui/scss/${name}';`), name).toBe('')
     }
-  })
+  }, 30_000)
 
   it('give a component’s own members, under the name its source uses', () => {
     const css = compile(`
@@ -66,3 +74,18 @@ describe('the SCSS entry points for theme authors (ADR 0021)', () => {
     ).toThrow(/Undefined mixin/)
   })
 })
+
+describe('a build that picks its components (ADR 0034)', () => {
+  it('compiles core and chosen components from their sources, with its own breakpoints', () => {
+    const css = compile(`
+@use 'pkg:@greese/ui/scss/config' with ($breakpoints: (xs: 0px, sm: 480px, md: 700px, lg: 1024px, xl: 1440px));
+@use 'pkg:@greese/ui/scss/core';
+@use 'pkg:@greese/ui/scss/components/Stack';
+@use 'pkg:@greese/ui/scss/components/Button';`)
+    expect(css).toContain('--greese-color-primary:')
+    expect(rules(css, '.greese-Button').length).toBeGreaterThan(0)
+    expect(css).toContain('@media (width >= 700px)')
+    expect(css).not.toContain('greese-Dialog')
+    expect(css.match(/@layer greese\.reset, /g)).toHaveLength(1)
+  })
+})

package/src/styles/index.scss

@@ -5,7 +5,6 @@
 // lets `@use … with ($breakpoints: …)` reconfigure every component.
 @forward 'config';
 @use 'core';
-@use 'breakpoint-vars';
 @use '../components/ThemeProvider/ThemeProvider';
 @use '../components/VisuallyHidden/VisuallyHidden';
 @use '../components/Box/Box';
@@ -69,13 +68,16 @@
 @use '../components/SegmentedControl/SegmentedControl';
 @use '../components/DateField/DateField';
 @use '../components/NumberField/NumberField';
+@use '../components/NumberStepper/NumberStepper';
 @use '../components/Table/Table';
 @use '../components/Combobox/Combobox';
+@use '../components/ScrollCarousel/ScrollCarousel';
 @use '../components/Carousel/Carousel';
 @use '../components/ChatBubble/ChatBubble';
 @use '../components/Countdown/Countdown';
 @use '../components/Diff/Diff';
 @use '../components/Dock/Dock';
+@use '../components/EditableField/EditableField';
 @use '../components/Fieldset/Fieldset';
 @use '../components/Indicator/Indicator';
 @use '../components/Key/Key';

package/src/styles/kit.test.ts

@@ -13,8 +13,15 @@ import {
 } from '../index.ts'
 import { blocks, compileScss, rules } from '../test/sass.ts'
 
-const compile = (scss: string, use = `@use 'kit' as greese;`): string =>
+/** The guard theme rules carry for `layer` (see reset-guard() in the kit). */
+const guard = (layer: string) =>
+  `:where(:not(.greese-reset-${layer}, .greese-reset-${layer} *, .greese-reset, .greese-reset *))`
+
+/** Compiled kit output with or without the reset guards, which most tests aren't about. */
+const compileGuarded = (scss: string, use = `@use 'kit' as greese;`): string =>
   compileScss(`${use}\n${scss}`)
+const compile = (scss: string, use?: string): string =>
+  compileGuarded(scss, use).replace(/:where\(:not\(\.greese-reset-[^)]*\)\)/g, '')
 
 /** The custom properties the first rule for `selector` declares, in order. */
 const declared = (css: string, selector: string): Array<[string, string]> => {
@@ -231,6 +238,23 @@ describe('SCSS kit: motion()', () => {
     ])
   })
 
+  it('assigns the carousel roles, forward and back', () => {
+    const css = compile(`@include greese.motion-defaults((
+      carousel: fade-in,
+      carousel-back: pocket-right,
+      carousel-exit: fade-out,
+      carousel-back-exit: pocket-out-right,
+      carousel-duration: slow,
+    ));`)
+    expect(Object.fromEntries(declared(css, ':root'))).toMatchObject({
+      '--greese-motion-carousel': 'greese-fade-in',
+      '--greese-motion-carousel-back': 'greese-pocket-right',
+      '--greese-motion-carousel-exit-opacity': '0',
+      '--greese-motion-carousel-back-exit-translate': '100% 0px',
+      '--greese-motion-carousel-duration': 'var(--greese-duration-slow)',
+    })
+  })
+
   it('assigns motion roles with motion-defaults(), pointing at effects and tokens', () => {
     const css = compile(`@include greese.motion-defaults((
       content: wipe-open-x,
@@ -611,6 +635,55 @@ describe('SCSS kit: tokens() and theme()', () => {
     ])
   })
 
+  /** What each selector ends up declaring, by where it sits: later blocks win. */
+  const effective = (css: string) => {
+    const out = new Map<string, Map<string, string>>()
+    for (const b of blocks(css)) {
+      const key = [...b.within, b.prelude].join(' > ')
+      const seen = out.get(key) ?? new Map<string, string>()
+      for (const [p, v] of b.declarations) seen.set(p, v)
+      if (b.declarations.length) out.set(key, seen)
+    }
+    return out
+  }
+
+  it.each([
+    ['in a named theme', (body: string) => `@include greese.theme(brand) { ${body} }`],
+    ['on the page', (body: string) => body],
+  ])('adds up repeated calls %s, as one merged call', (_, wrap) => {
+    const color = `@include greese.tokens((color: (primary: (light: #0f766e, dark: #5eead4), accentContent: #000)));`
+    const shape = `@include greese.tokens((radius: (md: 2px), color: (accent: "#fde047")), $extend: (space: (9: 5rem)));`
+    const merged = `@include greese.tokens((color: (primary: (light: #0f766e, dark: #5eead4), accentContent: #000, accent: "#fde047"), radius: (md: 2px)), $extend: (space: (9: 5rem)));`
+    const split = compile(wrap(`${color}\n${shape}`))
+    expect(effective(split)).toEqual(effective(compile(wrap(merged))))
+    // The second call writes only what it changes, not the theme again.
+    expect(split.match(/--greese-space-4:/g)?.length ?? 0).toBeLessThanOrEqual(1)
+  })
+
+  it('keeps an earlier call’s explicit value over what a later one derives', () => {
+    const css = compile(`@include greese.theme(brand) {
+      @include greese.tokens((color: (primaryContent: #123456)));
+      @include greese.tokens((color: (primary: "#fde047")));
+    }`)
+    const values = effective(css).get('@layer greese.theme > [data-greese-theme=brand]')
+    expect(values?.get('--greese-color-primary-content')).toBe('#123456')
+    expect(values?.get('--greese-color-primary')).toBe('#fde047')
+  })
+
+  it('scopes to a theme with scope(name), and to the page with null, false or empty', () => {
+    const card = `@include greese.component(Card) { padding: 0; }`
+    expect(
+      rules(
+        compile(`@include greese.scope(brand) { ${card} }`),
+        '[data-greese-theme=brand] .greese-Card'
+      )
+    ).toHaveLength(1)
+    for (const none of ['null', 'false', "''"])
+      expect(
+        rules(compile(`@include greese.scope(${none}) { ${card} }`), '.greese-Card')
+      ).toHaveLength(1)
+  })
+
   it('rejects unknown token groups and keys', () => {
     expect(() => compile('@include greese.tokens((colr: (accent: red)));')).toThrow(
       /no token group `colr`/
@@ -752,3 +825,100 @@ describe('SCSS kit: keyframes()', () => {
     ).toThrow(/built-in effect keeps its keyframes/)
   })
 })
+
+describe('SCSS kit: resets', () => {
+  it('guards each theme rule for its layer: component() as shape, motion() as motion', () => {
+    const css = compileGuarded(`@include greese.component(Dialog) {
+      padding: 0;
+      @include greese.part(body) { margin: 0; }
+      @include greese.motion((enter: fade-up));
+    }
+    @include greese.component(Card, $layer: color) { color: red; }`)
+    expect(rules(css, `.greese-Dialog${guard('shape')}`)[0]?.declarations).toEqual([
+      ['padding', '0'],
+    ])
+    expect(
+      rules(css, `.greese-Dialog${guard('shape')} .greese-Dialog-body`)
+    ).toHaveLength(1)
+    expect(
+      ruleIn(css, `.greese-Dialog${guard('motion')}`, '@layer greese.overrides', motionOk)
+    ).toContainEqual(expect.arrayContaining(['animation']))
+    expect(rules(css, `.greese-Card${guard('color')}`)).toHaveLength(1)
+  })
+
+  it('writes reset-guard() for rules of your own', () => {
+    const css = compileGuarded(`.x#{greese.reset-guard(motion)} { a: b; }`)
+    expect(rules(css, `.x${guard('motion')}`)).toHaveLength(1)
+    expect(() => compileGuarded(`.x#{greese.reset-guard(sound)} { a: b; }`)).toThrow(
+      /no theme layer `sound`. Layers: color, shape, motion/
+    )
+  })
+
+  it('declares each layer’s defaults in the reset classes, and all three in .greese-reset', () => {
+    const css = compileGuarded('@include greese.reset-classes;')
+    const color = declared(css, '.greese-reset-color')
+    expect(color).toContainEqual([
+      '--greese-color-primary',
+      'light-dark(#2771e0, #81b2ff)',
+    ])
+    expect(declared(css, '.greese-reset-shape')).toContainEqual([
+      '--greese-corner-control',
+      expect.any(String),
+    ])
+    expect(declared(css, '.greese-reset-motion')).toEqual(
+      expect.arrayContaining([
+        ['--greese-motion-overlay', 'initial'],
+        ['--greese-motion-dialog-exit-opacity', 'initial'],
+      ])
+    )
+    for (const layer of ['color', 'shape', 'motion'])
+      expect(rules(css, '.greese-reset').map((r) => r.declarations)).toContainEqual(
+        declared(css, `.greese-reset-${layer}`)
+      )
+  })
+
+  it('declares the defaults in any rule with reset()', () => {
+    const css = compileGuarded('.notice { @include greese.reset(color); }')
+    expect(declared(css, '.notice')).toContainEqual([
+      '--greese-color-primary',
+      'light-dark(#2771e0, #81b2ff)',
+    ])
+    expect(declared(css, '.notice').some(([p]) => p.startsWith('--greese-corner'))).toBe(
+      false
+    )
+  })
+
+  it('leaves a component out of the layers reset() takes from it, for the rest of the build', () => {
+    const css = compileGuarded(`
+      @include greese.component(Card) { @include greese.reset(shape); }
+      @include greese.component(Card) { border-radius: 0; @include greese.motion((enter: fade-up)); }
+      @include greese.component(Card, $layer: color) { color: red; }
+      .a { clip-path: none; }
+      #{greese.themed('.greese-Card', Card)}, #{greese.themed('.greese-Tile', Tile)} { clip-path: inset(0); }`)
+    // The reset layer's rule matches nothing; motion() inside it still plays.
+    expect(
+      rules(css, `.greese-Card${guard('shape')}:not(*)`).map((r) => r.declarations)
+    ).toContainEqual([['border-radius', '0']])
+    expect(
+      ruleIn(css, `.greese-Card${guard('motion')}`, '@layer greese.overrides', motionOk)
+    ).toHaveLength(1)
+    expect(css).toContain('color: red')
+    expect(
+      rules(css, `.greese-Card${guard('shape')}:not(*)`).map((r) => r.declarations)
+    ).toContainEqual([['clip-path', 'inset(0)']])
+    expect(rules(css, `.greese-Tile${guard('shape')}`)).toHaveLength(1)
+  })
+
+  it('warns when reset() comes after the rules it would take back', () => {
+    const warnings: string[] = []
+    compileScss(
+      `@use 'kit' as greese;
+      @include greese.component(Card) { border-radius: 0; }
+      @include greese.component(Card) { @include greese.reset(shape); }`,
+      warnings
+    )
+    expect(warnings.join('\n')).toMatch(
+      /reset\(shape\) for Card comes after Card's shape rules/
+    )
+  })
+})

package/src/styles/public/_breakpoints.scss

@@ -0,0 +1,43 @@
+// `pkg:@greese/ui/scss/breakpoints`: more breakpoints for the layout
+// components, measured against a container instead of the viewport. A library
+// whose components live in boxes of their own size (@greese/authoring's
+// panels) names its container and its keys, and gets Stack's, Grid's and
+// AutoLayout's responsive classes for them:
+//   @use 'pkg:@greese/ui/scss/breakpoints';
+//   @layer greese.components {
+//     @include breakpoints.container-set((panelmd: 360px), greese-panel);
+//   }
+// Keys follow `$breakpoints`' rules (one word, no dashes, increasing), and
+// mustn't be one of its own. JavaScript learns them through
+// `addContainerBreakpoints()` from @greese/react, so `resolveResponsive()`
+// writes their classes. Writes no CSS until included.
+@use 'sass:map';
+@use 'sass:string';
+@use '../config';
+@use '../layout-props';
+
+/// Stack's, Grid's and AutoLayout's responsive props for `$set`, each key
+/// applying where the nearest `$container` is at least that wide.
+@mixin container-set($set, $container) {
+  $previous: -1px;
+
+  @each $key, $min in $set {
+    @if map.has-key(config.$breakpoints, $key) {
+      @error 'container-set: `#{$key}` is already a viewport breakpoint; give the container\'s its own name.';
+    }
+
+    @if string.index('#{$key}', '-') {
+      @error 'container-set: key `#{$key}` must be one word, without dashes.';
+    }
+
+    @if $min <= $previous {
+      @error 'container-set: breakpoints must increase, but `#{$key}` (#{$min}) does not exceed the one before it.';
+    }
+
+    $previous: $min;
+  }
+
+  @include layout-props.stack($set, $container);
+  @include layout-props.grid($set, $container);
+  @include layout-props.autolayout($set, $container);
+}

package/src/styles/public/_slides.scss

@@ -0,0 +1,3 @@
+// `pkg:@greese/ui/scss/slides`: the previous/next buttons and dots that
+// ScrollCarousel and Carousel share, for theme authors (ADR 0021).
+@forward '../slides';

package/src/styles/public/_utilities.scss

@@ -0,0 +1,3 @@
+// `pkg:@greese/ui/scss/utilities`: the utility classes, built with this
+// build's breakpoints (ADR 0034). The library's own module, as the others.
+@forward '../utilities';

package/src/styles/resets.scss

@@ -0,0 +1,7 @@
+// Compiled to dist/css/resets.css: the classes that take a theme's layers back
+// from part of a page (`.greese-reset-color`, `-shape`, `-motion`, and
+// `.greese-reset` for all three) with their default tokens. Opt-in, since most
+// pages never reset. Theme rules stop at the classes either way; this file
+// adds the defaults the tokens return to.
+@use 'kit';
+@include kit.reset-classes;

package/src/styles/utilities.test.ts

@@ -0,0 +1,39 @@
+// @vitest-environment node
+import { describe, expect, it } from 'vitest'
+import { generateUtilities } from '../utilities.ts'
+import { blocks, compileScss } from '../test/sass.ts'
+
+describe('utilities in Sass (pkg:@greese/ui/scss/utilities)', () => {
+  /** Each block's place, selector and declarations: the CSS, formatting aside. */
+  const shape = (css: string) =>
+    blocks(css)
+      .filter((b) => b.declarations.length)
+      .map((b) => [...b.within, b.prelude, ...b.declarations.flat()].join(' | '))
+
+  const sass = (call: string, use = '') =>
+    compileScss(`${use}\n@use 'utilities';\n@include utilities.classes${call};`)
+
+  it('writes what generateUtilities() writes', () => {
+    expect(shape(sass(''))).toEqual(shape(generateUtilities()))
+  })
+
+  it('takes the build’s breakpoints, groups, a prefix and a purge list', () => {
+    const breakpoints = { xs: 0, sm: 480, tablet: 700, md: 768, lg: 1024, xl: 1440 }
+    const custom = `@use 'config' with ($breakpoints: (${Object.entries(breakpoints)
+      .map(([k, v]) => `${k}: ${v}px`)
+      .join(', ')}));`
+    expect(shape(sass('($groups: (spacing, layout), $prefix: g)', custom))).toEqual(
+      shape(
+        generateUtilities({ groups: ['spacing', 'layout'], prefix: 'g', breakpoints })
+      )
+    )
+    const used = new Set(['p-4', 'md-display-flex', 'hover-opacity-75'])
+    expect(shape(sass(`($only: (${[...used].join(', ')}))`))).toEqual(
+      shape(generateUtilities({ used }))
+    )
+  })
+
+  it('stops the build on an unknown group', () => {
+    expect(() => sass('($groups: (spaces))')).toThrow(/no group `spaces`/)
+  })
+})