shelving 1.282.2 → 1.284.0

package/ui/util/ClassProps.md

@@ -0,0 +1,56 @@
+# ClassProps
+
+The shared `className` prop most components accept — an app class merged *after* the classes the component computes for itself.
+
+**Things to know:**
+
+- CSS-module class names are hashed, so an app stylesheet can't target a component instance on its own. `className` is the sanctioned way to attach an app class to a specific instance.
+- It's merged **last**, and an app's global stylesheet is unlayered, so its rules beat the library's `@layer components` rules without a specificity fight.
+- It accepts any `Classes` value — a string, a nested array, or a dictionary whose `true` keys become class names — because it goes through `getClass()` like every other class the component composes.
+- It lands on the component's **own root element**. A component that renders more than one element (`<Card>`'s stretched overlay link, `<Field>`'s inner input) keeps the class on the outer one. `<Popover>` is the one deliberate exception: its class goes on the floating panel, not the wrapper that anchors it.
+- **Not every component takes one.** Formatting-only components (`<When>`, `<Prose>`, `<Scroll>`) exist to format what's already there, the `*Layout` components are structural (write a new layout rather than bending an existing one), and `<Dialog>` is nearly always rendered from the dialogs state object. Style the content inside them instead.
+- Tokens and per-property hooks (`--card-background`, `--button-radius`, …) remain the primary theming surface. Reach for `className` for a composed one-off treatment those can't express — a keyframe animation, a bespoke gradient, a transform on press — not to restyle a component everywhere.
+
+## Usage
+
+### Attaching an app class
+
+```tsx
+import { Button } from "shelving/ui";
+
+// `.spongy-press` lives in the app's own global stylesheet.
+<Button className="spongy-press" strong onClick={claim}>
+	Claim
+</Button>;
+```
+
+```css
+/* style.css — unlayered, so it beats the library's `@layer components` rules. */
+.spongy-press:active {
+	transform: scale(0.96);
+}
+```
+
+### Conditional classes
+
+```tsx
+import { Card } from "shelving/ui";
+
+// Arrays and `true`-flag dictionaries work too — anything `Classes` allows.
+<Card className={["claim-card", { sparkle: isNew }]} href={path}>
+	{content}
+</Card>;
+```
+
+### Adding it to your own component
+
+```tsx
+import { type ClassProps, getClass } from "shelving/ui";
+
+export interface AddressProps extends BlockVariants, ChildProps, ClassProps {}
+
+export function Address({ children, className, ...props }: AddressProps): ReactElement {
+	// Merge `className` last so a caller's class wins.
+	return <address className={getClass(ADDRESS_CLASS, getBlockClass(props), className)}>{children}</address>;
+}
+```

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. */

package/ui/util/props.d.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import type { Classes } from "./css.js";
 /**
  * Props for a component that requires `children`.
  *
@@ -15,3 +16,14 @@ export interface ChildProps {
 export interface OptionalChildProps {
     readonly children?: ReactNode | undefined;
 }
+/**
+ * Props for a component that accepts an additional `className`, merged _after_ the classes the component computes for itself.
+ * - Accepts anything `Classes` allows — a string, a nested array of strings, or a `Variants` dictionary of `true` flags.
+ * - Merged last so an app's own (unlayered) stylesheet reliably beats the library's `@layer components` rules.
+ * - Component hooks (`--card-background` etc.) and the tint ladder remain the primary theming surface; `className` is the escape hatch for one-off treatments they can't express.
+ *
+ * @see https://shelving.cc/ui/ClassProps
+ */
+export interface ClassProps {
+    readonly className?: Classes | undefined;
+}

package/ui/util/props.test.tsx

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import type { ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+	Button,
+	Card,
+	Cell,
+	createMeta,
+	Field,
+	Loading,
+	MetaContext,
+	Paragraph,
+	Popover,
+	PopoverButtonInput,
+	Span,
+	Tag,
+	TextInput,
+} from "shelving/ui";
+
+/** Render `children` inside the meta context that link-rendering components need. */
+function render(children: ReactNode): string {
+	return renderToStaticMarkup(<MetaContext value={createMeta({ root: "http://x.com/", url: "./" })}>{children}</MetaContext>);
+}
+
+describe("ClassProps", () => {
+	test("component renders a `className` string on its root element", () => {
+		expect(render(<Paragraph className="spongy">Hi</Paragraph>)).toContain('<p class="spongy">');
+		expect(render(<Span className="spongy">Hi</Span>)).toContain('<span class="spongy">');
+		expect(render(<Cell className="spongy">Hi</Cell>)).toContain('<td class="spongy">');
+	});
+
+	test("component accepts every `Classes` form, not just a string", () => {
+		expect(render(<Paragraph className={["spongy", "sparkle"]}>Hi</Paragraph>)).toContain('<p class="spongy sparkle">');
+		expect(render(<Paragraph className={{ spongy: true, sparkle: false }}>Hi</Paragraph>)).toContain('<p class="spongy">');
+	});
+
+	test("clickable component renders its `className` on the rendered element", () => {
+		// `Button` renders through `Clickable`, which picks `<button>` for `onClick` and `<a>` for `href`.
+		expect(render(<Button className="spongy" onClick={() => undefined} />)).toContain('<button type="button" class="spongy"');
+		expect(render(<Button className="spongy" href="/about" />)).toContain('class="spongy"');
+		expect(render(<Tag className="spongy">New</Tag>)).toContain('class="spongy"');
+	});
+
+	test("clickable wrapper renders a working `<button>` when only `onClick` is set", () => {
+		// `Card` spreads `href={href}` into `Clickable` even when unset — dispatch must pick `<button>` from the defined `onClick`, not a dead `<a>`.
+		const html = render(<Card onClick={() => undefined}>Hi</Card>);
+		expect(html).toContain("<button");
+		expect(html).not.toContain("<a ");
+	});
+
+	test("`className` lands on the component's own root, not on its inner elements", () => {
+		// `Card` renders the class on its `<article>`, not on the stretched overlay `<a>` it also renders.
+		const html = render(
+			<Card className="spongy" href="/about">
+				Hi
+			</Card>,
+		);
+		expect(html).toContain('<article class="spongy">');
+		expect(html).not.toContain('<a class="spongy"');
+	});
+
+	test("`Popover` styles its floating panel rather than its wrapper", () => {
+		const html = render(
+			<Popover className="spongy">
+				<button type="button">Open</button>
+				<div>Panel</div>
+			</Popover>,
+		);
+		expect(html).toContain('<section class="spongy"');
+	});
+
+	test("input component renders its `className` on the input element", () => {
+		expect(render(<TextInput className="spongy" name="name" onValue={() => undefined} />)).toContain('class="spongy"');
+	});
+
+	test("popover wrapper components render their `className` on the trigger, not the floating panel", () => {
+		// `PopoverButtonInput` (and `PopoverButton`/`QueryInput`) style their always-visible trigger — only a bare `<Popover>` styles the panel.
+		const html = render(
+			<PopoverButtonInput name="pick" className="spongy">
+				{["Pick", "Panel"]}
+			</PopoverButtonInput>,
+		);
+		expect(html).toContain('class="spongy"');
+		expect(html).toContain("<button");
+	});
+
+	test("omitted `className` renders the same markup as `className={undefined}`", () => {
+		expect(render(<Field title="Name">Hi</Field>)).toBe(
+			render(
+				<Field title="Name" className={undefined}>
+					Hi
+				</Field>,
+			),
+		);
+		expect(render(<Paragraph>Hi</Paragraph>)).not.toContain("spongy");
+		// A component with no class of its own renders no `class` attribute at all, rather than an empty one.
+		expect(render(<Loading />)).not.toContain("class=");
+		expect(render(<Loading className="spongy" />)).toContain('class="spongy"');
+	});
+});

package/ui/util/props.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import type { Classes } from "./css.js";
 
 /**
  * Props for a component that requires `children`.
@@ -17,3 +18,15 @@ export interface ChildProps {
 export interface OptionalChildProps {
 	readonly children?: ReactNode | undefined;
 }
+
+/**
+ * Props for a component that accepts an additional `className`, merged _after_ the classes the component computes for itself.
+ * - Accepts anything `Classes` allows — a string, a nested array of strings, or a `Variants` dictionary of `true` flags.
+ * - Merged last so an app's own (unlayered) stylesheet reliably beats the library's `@layer components` rules.
+ * - Component hooks (`--card-background` etc.) and the tint ladder remain the primary theming surface; `className` is the escape hatch for one-off treatments they can't express.
+ *
+ * @see https://shelving.cc/ui/ClassProps
+ */
+export interface ClassProps {
+	readonly className?: Classes | undefined;
+}

package/ui/input/ButtonInputPopover.d.ts

@@ -1,25 +0,0 @@
-/** biome-ignore-all lint/a11y/noStaticElementInteractions: This is fine we're only using this to listen for clicks on child buttons. */
-/** biome-ignore-all lint/a11y/useKeyWithClickEvents: This is fine we're only using this to listen for clicks on child buttons. */
-import { type ReactElement } from "react";
-import type { InputProps } from "./Input.js";
-import { type PopoverChildren } from "./Popover.js";
-/**
- * Props for `ButtonInputPopover`, an input button that toggles an adjacent popover.
- *
- * @see https://shelving.cc/ui/ButtonInputPopoverProps
- */
-export interface ButtonInputPopoverProps extends InputProps {
-    children: PopoverChildren;
-}
-/**
- * An input button that, when clicked, shows a popover next to it when clicked or focused.
- * - The first element passed to `children` is used as the content for the button, the rest is the content of the popover.
- *
- * DH: Would love to use new HTML `popover="auto"` functionality for this but the anchor positioning it needs is not supported everywhere yet.
- *
- * @returns A `Popover` wrapping a `ButtonInput` that toggles it open and closed.
- * @example <ButtonInputPopover name="filter">{label}{panel}</ButtonInputPopover>
- * @see https://shelving.cc/ui/ButtonInputPopover
- */
-export declare function ButtonInputPopover({ children: [buttonChildren, ...popoverChildren], //
-...props }: ButtonInputPopoverProps): ReactElement;

package/ui/input/ButtonInputPopover.tsx

@@ -1,41 +0,0 @@
-/** biome-ignore-all lint/a11y/noStaticElementInteractions: This is fine we're only using this to listen for clicks on child buttons. */
-/** biome-ignore-all lint/a11y/useKeyWithClickEvents: This is fine we're only using this to listen for clicks on child buttons. */
-
-import { type ReactElement, useState } from "react";
-import { ButtonInput } from "./ButtonInput.js";
-import type { InputProps } from "./Input.js";
-import { Popover, type PopoverChildren } from "./Popover.js";
-
-/**
- * Props for `ButtonInputPopover`, an input button that toggles an adjacent popover.
- *
- * @see https://shelving.cc/ui/ButtonInputPopoverProps
- */
-export interface ButtonInputPopoverProps extends InputProps {
-	children: PopoverChildren;
-}
-
-/**
- * An input button that, when clicked, shows a popover next to it when clicked or focused.
- * - The first element passed to `children` is used as the content for the button, the rest is the content of the popover.
- *
- * DH: Would love to use new HTML `popover="auto"` functionality for this but the anchor positioning it needs is not supported everywhere yet.
- *
- * @returns A `Popover` wrapping a `ButtonInput` that toggles it open and closed.
- * @example <ButtonInputPopover name="filter">{label}{panel}</ButtonInputPopover>
- * @see https://shelving.cc/ui/ButtonInputPopover
- */
-export function ButtonInputPopover({
-	children: [buttonChildren, ...popoverChildren], //
-	...props
-}: ButtonInputPopoverProps): ReactElement {
-	const [open, setOpen] = useState(false);
-	return (
-		<Popover open={open} onClose={() => setOpen(false)}>
-			<ButtonInput onClick={() => setOpen(!open)} {...props}>
-				{buttonChildren}
-			</ButtonInput>
-			{popoverChildren}
-		</Popover>
-	);
-}

package/ui/input/ButtonPopover.d.ts

@@ -1,25 +0,0 @@
-/** biome-ignore-all lint/a11y/noStaticElementInteractions: This is fine we're only using this to listen for clicks on child buttons. */
-/** biome-ignore-all lint/a11y/useKeyWithClickEvents: This is fine we're only using this to listen for clicks on child buttons. */
-import { type ReactElement } from "react";
-import { type ButtonVariants } from "../button/Button.js";
-import { type PopoverChildren } from "./Popover.js";
-/**
- * Props for `ButtonPopover`, a button that toggles an adjacent popover.
- *
- * @see https://shelving.cc/ui/ButtonPopoverProps
- */
-export interface ButtonPopoverProps extends ButtonVariants {
-    children: PopoverChildren;
-}
-/**
- * A button that, when clicked, shows a popover next to it when clicked or focused.
- * - The first element passed to `children` is used as the content for the button, the rest is the content of the popover.
- *
- * DH: Would love to use new HTML `popover="auto"` functionality for this but the anchor positioning it needs is not supported everywhere yet.
- *
- * @returns A `Popover` wrapping a `Button` that toggles it open and closed.
- * @example <ButtonPopover>{label}{panel}</ButtonPopover>
- * @see https://shelving.cc/ui/ButtonPopover
- */
-export declare function ButtonPopover({ children: [buttonChildren, ...popoverChildren], //
-...props }: ButtonPopoverProps): ReactElement;

package/ui/input/ButtonPopover.tsx

@@ -1,40 +0,0 @@
-/** biome-ignore-all lint/a11y/noStaticElementInteractions: This is fine we're only using this to listen for clicks on child buttons. */
-/** biome-ignore-all lint/a11y/useKeyWithClickEvents: This is fine we're only using this to listen for clicks on child buttons. */
-
-import { type ReactElement, useState } from "react";
-import { Button, type ButtonVariants } from "../button/Button.js";
-import { Popover, type PopoverChildren } from "./Popover.js";
-
-/**
- * Props for `ButtonPopover`, a button that toggles an adjacent popover.
- *
- * @see https://shelving.cc/ui/ButtonPopoverProps
- */
-export interface ButtonPopoverProps extends ButtonVariants {
-	children: PopoverChildren;
-}
-
-/**
- * A button that, when clicked, shows a popover next to it when clicked or focused.
- * - The first element passed to `children` is used as the content for the button, the rest is the content of the popover.
- *
- * DH: Would love to use new HTML `popover="auto"` functionality for this but the anchor positioning it needs is not supported everywhere yet.
- *
- * @returns A `Popover` wrapping a `Button` that toggles it open and closed.
- * @example <ButtonPopover>{label}{panel}</ButtonPopover>
- * @see https://shelving.cc/ui/ButtonPopover
- */
-export function ButtonPopover({
-	children: [buttonChildren, ...popoverChildren], //
-	...props
-}: ButtonPopoverProps): ReactElement {
-	const [open, setOpen] = useState(false);
-	return (
-		<Popover open={open} onClose={() => setOpen(false)}>
-			<Button onClick={() => setOpen(!open)} {...props}>
-				{buttonChildren}
-			</Button>
-			{popoverChildren}
-		</Popover>
-	);
-}