shelving 1.283.0 → 1.284.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.283.0",
+	"version": "1.284.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/button/Button.md

@@ -60,11 +60,14 @@ import { getButtonClass } from "shelving/ui";
 
 `--button-padding` and `--button-small-padding` set the `padding` shorthand, so a single value pads both axes equally and a two-value override pads block and inline separately (e.g. `var(--space-small) var(--space-normal)`).
 
+`--button-shadow`, `--button-hover-transform` and the `--button-active-*` pressed-state hooks are static and apply to every button, with one exception: `plain` and `outline` never paint a box shadow in any state — they have no fill until hover, so a raised edge under them reads broken. The hover and pressed transforms still apply to them, so all buttons move together. `--button-transition` already covers animating the press and release.
+
 | Variable | Styles | Default |
 |---|---|---|
 | `--button-background` | Surface fill | `var(--tint-90)` |
 | `--button-hover-background` | Surface fill on hover / focus | `var(--tint-95)` |
 | `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid var(--tint-90)` |
+| `--button-hover-transform` | Transform on hover / focus | `none` |
 | `--button-text` | Label colour | `var(--tint-50)` |
 | `--button-border` | Border shorthand | `var(--button-stroke) solid var(--tint-80)` |
 | `--button-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
@@ -78,6 +81,11 @@ import { getButtonClass } from "shelving/ui";
 | `--button-weight` | Font weight | `var(--weight-strong)` (700) |
 | `--button-size` | Font size | `var(--size-normal)` |
 | `--button-leading` | Line height | `var(--leading)` |
+| `--button-shadow` | Box shadow (never on `plain` / `outline`) | `none` |
+| `--button-active-background` | Surface fill while pressed | `var(--button-hover-background)` |
+| `--button-active-border` | Border while pressed | `var(--button-hover-border)` |
+| `--button-active-shadow` | Box shadow while pressed | `var(--button-shadow)` |
+| `--button-active-transform` | Transform while pressed | `var(--button-hover-transform)` |
 | `--button-transition` | Transition | `all var(--duration-fast)` (150ms) |
 | `--button-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
 | `--button-disabled-opacity` | Opacity when disabled | `0.5` |
@@ -94,3 +102,13 @@ import { getButtonClass } from "shelving/ui";
   --button-padding: var(--space-small) var(--space-normal);
 }
 ```
+
+```css
+/* Theme: buttons are raised and press down flat — `plain` and `outline` press down too but never cast a shadow. */
+:root {
+  --button-shadow: 0 0.25rem 0 var(--tint-80);
+  --button-active-transform: translateY(0.2rem);
+  --button-active-shadow: 0 0.05rem 0 var(--tint-80);
+  --button-transition: all var(--duration-fast) cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+```

package/ui/button/Button.module.css

@@ -31,6 +31,7 @@
 		/* Style. */
 		background: var(--button-background, var(--tint-90));
 		color: var(--button-text, var(--tint-50));
+		box-shadow: var(--button-shadow, none);
 		transition: var(--button-transition, all var(--duration-fast));
 		cursor: pointer;
 		outline: var(--button-focus-border, var(--stroke-focus) solid var(--color-focus));
@@ -55,6 +56,15 @@
 		&:focus:not(:focus-visible) {
 			border: var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid var(--tint-90));
 			background: var(--button-hover-background, var(--tint-95));
+			transform: var(--button-hover-transform, none);
+		}
+
+		&:enabled:active,
+		&:any-link:active {
+			border: var(--button-active-border, var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid var(--tint-90)));
+			background: var(--button-active-background, var(--button-hover-background, var(--tint-95)));
+			transform: var(--button-active-transform, var(--button-hover-transform, none));
+			box-shadow: var(--button-active-shadow, var(--button-shadow, none));
 		}
 
 		/* Variants */
@@ -101,13 +111,21 @@
 			border-color: transparent;
 		}
 
-		&.plain:not(:enabled:hover, :any-link:hover, :focus) {
-			border-color: transparent;
-			background: transparent;
+		&.plain {
+			box-shadow: none;
+
+			&:not(:enabled:hover, :any-link:hover, :focus) {
+				border-color: transparent;
+				background: transparent;
+			}
 		}
 
-		&.outline:not(:enabled:hover, :any-link:hover, :focus) {
-			background: transparent;
+		&.outline {
+			box-shadow: none;
+
+			&:not(:enabled:hover, :any-link:hover, :focus) {
+				background: transparent;
+			}
 		}
 	}
 }

package/ui/util/css.d.ts

@@ -47,7 +47,7 @@ export declare function getClass(...classes: unknown[]): string;
  * - This allows this situation to be handled gracefully and classes will be silently ignored in this environment.
  *
  * @param classes Class keys/values to merge.
- * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module).
+ * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module) or no classes match.
  * @see https://shelving.cc/ui/getModuleClass
  */
 export declare function getModuleClass(module: CSSModule | string, ...classes: unknown[]): string | undefined;

package/ui/util/css.js

@@ -42,12 +42,12 @@ function* getClasses(classes) {
  * - This allows this situation to be handled gracefully and classes will be silently ignored in this environment.
  *
  * @param classes Class keys/values to merge.
- * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module).
+ * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module) or no classes match.
  * @see https://shelving.cc/ui/getModuleClass
  */
 export function getModuleClass(module, ...classes) {
     if (isDictionary(module))
-        return Array.from(getModuleClasses(module, classes)).join(" ");
+        return Array.from(getModuleClasses(module, classes)).join(" ") || undefined;
 }
 /** Yield the items in a list of possible `className` strings that match a `CSSModule` dictionary. */
 function* getModuleClasses(module, classes) {

package/ui/util/css.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { getClass, getModuleClass } from "shelving/ui";
+
+describe("getClass", () => {
+	test("joins strings, arrays, and true-valued variant keys", () => {
+		expect(getClass("a", ["b", "c"], { d: true, e: false })).toBe("a b c d");
+	});
+
+	test("ignores `null` and `undefined`", () => {
+		expect(getClass("a", null, undefined, "b")).toBe("a b");
+	});
+});
+
+describe("getModuleClass", () => {
+	test("maps class keys through the module dictionary", () => {
+		expect(getModuleClass({ track: "abc123" }, "track")).toBe("abc123");
+		expect(getModuleClass({ track: "abc123", spin: "def456" }, "track", "spin")).toBe("abc123 def456");
+	});
+
+	test("returns `undefined` when the module is a string (unprocessed CSS module)", () => {
+		expect(getModuleClass("./Loading.module.css", "track")).toBeUndefined();
+	});
+
+	test('returns `undefined` when no classes match, so no empty `class=""` attribute renders', () => {
+		// Some environments (e.g. `bun test` v1.4+) import a `.module.css` as an empty object.
+		expect(getModuleClass({}, "track")).toBeUndefined();
+		expect(getModuleClass({ track: "abc123" }, "missing")).toBeUndefined();
+	});
+});

package/ui/util/css.ts

@@ -77,11 +77,11 @@ function* getClasses(classes: unknown): Iterable<string> {
  * - This allows this situation to be handled gracefully and classes will be silently ignored in this environment.
  *
  * @param classes Class keys/values to merge.
- * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module).
+ * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module) or no classes match.
  * @see https://shelving.cc/ui/getModuleClass
  */
 export function getModuleClass(module: CSSModule | string, ...classes: unknown[]): string | undefined {
-	if (isDictionary(module)) return Array.from(getModuleClasses(module, classes)).join(" ");
+	if (isDictionary(module)) return Array.from(getModuleClasses(module, classes)).join(" ") || undefined;
 }
 
 /** Yield the items in a list of possible `className` strings that match a `CSSModule` dictionary. */