shelving 1.286.0 → 1.286.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.286.0",
+	"version": "1.286.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,12 +9,12 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.14",
+		"@biomejs/biome": "^2.5.15",
 		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.4.2",
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
-		"stylelint": "^17.15.0",
+		"stylelint": "^17.16.0",
 		"stylelint-config-standard": "^40.0.0",
 		"typescript": "^7.0.2"
 	},

package/ui/block/Details.d.ts

@@ -1,22 +1,27 @@
 import type { ReactElement, ReactNode } from "react";
 import { type BlockVariants } from "../style/Block.js";
 import type { ClassProps } from "../util/props.js";
-/** Props for `DetailsItem` — a single collapsible disclosure. */
+/**
+ * Props for `<Details>` — the summary title, the revealed content, and the open state.
+ *
+ * @see https://shelving.cc/ui/DetailsProps
+ */
 export interface DetailsProps extends BlockVariants, ClassProps {
     /** Content of the always-visible summary (e.g. a question). */
     title: ReactNode;
-    /** Whether the item starts expanded. */
+    /** Whether the panel starts expanded. */
     open?: boolean | undefined;
-    /** Shared group name — items with the same `name` open exclusively (only one at a time). */
+    /** Shared group name — panels with the same `name` open exclusively (only one at a time). */
     name?: string | undefined;
-    /** Content revealed when the item is expanded. */
+    /** Content revealed when the panel is expanded. */
     children: ReactNode;
 }
 /**
- * A single collapsible panel within an `Details`, built on native `<details>` and `<summary>`
- * - Panel animates to its true height (where `interpolate-size` + `::details-content` are supported),
- * - Give sibling items a shared `name` to make them open exclusively.
+ * A collapsible panel with a title that is always visible, built on native `<details>` and `<summary>`.
+ * - The panel animates to its true height (where `interpolate-size` and `::details-content` are supported).
+ * - Give sibling panels a shared `name` to make them open exclusively.
  *
  * @kind component
+ * @see https://shelving.cc/ui/Details
  */
 export declare function Details({ title, open, name, children, className, ...props }: DetailsProps): ReactElement;

package/ui/block/Details.js

@@ -1,16 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ChevronUpIcon } from "@heroicons/react/24/outline";
+import { ChevronUpIcon } from "@heroicons/react/24/solid";
 import { getBlockClass } from "../style/Block.js";
-import { getClass } from "../util/css.js";
+import { getFlexClass } from "../style/Flex.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import DETAILS_CSS from "./Details.module.css";
-const DETAILS_CLASS = DETAILS_CSS.details;
-const DETAILS_SUMMARY_CLASS = DETAILS_CSS.summary;
+const DETAILS_CLASS = getModuleClass(DETAILS_CSS, "details");
+const DETAILS_SUMMARY_CLASS = getClass(getModuleClass(DETAILS_CSS, "summary"), getFlexClass({ between: true, gap: "normal" }));
 /**
- * A single collapsible panel within an `Details`, built on native `<details>` and `<summary>`
- * - Panel animates to its true height (where `interpolate-size` + `::details-content` are supported),
- * - Give sibling items a shared `name` to make them open exclusively.
+ * A collapsible panel with a title that is always visible, built on native `<details>` and `<summary>`.
+ * - The panel animates to its true height (where `interpolate-size` and `::details-content` are supported).
+ * - Give sibling panels a shared `name` to make them open exclusively.
  *
  * @kind component
+ * @see https://shelving.cc/ui/Details
  */
 export function Details({ title, open = false, name, children, className, ...props }) {
     return (_jsxs("details", { className: getClass(DETAILS_CLASS, getBlockClass(props), className), open: open, name: name, children: [_jsxs("summary", { className: DETAILS_SUMMARY_CLASS, children: [_jsx("span", { children: title }), _jsx(ChevronUpIcon, {})] }), children] }));

package/ui/block/Details.md

@@ -0,0 +1,63 @@
+# Details
+
+A collapsible panel. The title is always visible. The content shows when the user opens the panel. Built on the native `<details>` and `<summary>` elements, so it works with the keyboard and without JavaScript.
+
+**Things to know:**
+
+- A chevron on the right of the title points down when the panel is closed and up when it is open.
+- The panel animates to its true height where the browser supports `interpolate-size` and `::details-content`. Other browsers open it at once.
+- Give sibling panels the same `name` to make them open exclusively: when one opens, the others close.
+- Two or more panels next to each other get a divider line between them.
+- A raw `<details>` inside `.prose` gets the same spacing and divider, but it keeps the browser's own marker in place of the chevron.
+
+## Usage
+
+### Single panel
+
+```tsx
+import { Details, Paragraph } from "shelving/ui";
+
+<Details title="What is shelving?">
+  <Paragraph>A TypeScript data toolkit.</Paragraph>
+</Details>
+```
+
+### Open by default
+
+```tsx
+import { Details, Paragraph } from "shelving/ui";
+
+<Details title="Release notes" open>
+  <Paragraph>Bug fixes and small improvements.</Paragraph>
+</Details>
+```
+
+### Exclusive group (FAQ)
+
+```tsx
+import { Details, Paragraph } from "shelving/ui";
+
+// Only one answer is open at a time.
+<Details name="faq" title="Is it free?">
+  <Paragraph>Yes.</Paragraph>
+</Details>
+<Details name="faq" title="Does it work with React?">
+  <Paragraph>Yes, through `shelving/ui`.</Paragraph>
+</Details>
+```
+
+## Styling
+
+`Details` paints from the [tint ladder](/ui/TINT_CLASS). Override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` to an ancestor scope to recolour the chevron and divider together.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--details-space` | Outer block margin, and the padding above a divider | `var(--space-paragraph)` (16px) |
+| `--details-border` | Divider between panels next to each other | `var(--stroke-normal) solid var(--tint-90)` |
+| `--details-marker-color` | Colour of the browser's marker on a raw `<details>` in `.prose` | `var(--tint-80)` |
+| `--details-radius` | Corner radius of the title's focus ring | `var(--radius-xsmall)` (8px) |
+| `--details-icon-color` | Chevron colour | `var(--tint-50)` |
+| `--details-transition` | Open/close animation and chevron turn | `all var(--duration-fast)` (150ms) |
+| `--details-gap` | Space between the title and the content | `var(--space-paragraph)` (16px) |
+
+**Global tokens it reads:** the tint ladder `--tint-50` / `--tint-80` / `--tint-90`, plus `--space-paragraph`, `--space-normal`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--duration-fast` and `--size-icon` (chevron size, from `getFlexClass`).

package/ui/block/Details.module.css

@@ -48,26 +48,11 @@
 			}
 		}
 
-		/* Title (with chevron icon) */
-		.summary {
-			/* Box */
-			display: flex;
-
-			/* Contents */
-			align-items: center;
-			justify-content: space-between;
-			gap: var(--space-normal);
-
-			/* Children */
-			[data-slot="icon"] {
-				width: var(--size-icon);
-				height: var(--size-icon);
-				color: var(--color-gray);
-				transform: rotate(180deg);
-				transition: var(--details-transition, all var(--duration-fast));
-				border-radius: var(--radius-xxsmall);
-				flex: none;
-			}
+		/* Title chevron (the summary's flex class sets its size). Points down while closed. */
+		.summary [data-slot="icon"] {
+			color: var(--details-icon-color, var(--tint-50));
+			transform: rotate(180deg);
+			transition: var(--details-transition, all var(--duration-fast));
 		}
 
 		/* Content */
@@ -96,10 +81,8 @@
 
 		/* States */
 		&[open] {
-			.summary {
-				[data-slot="icon"] {
-					transform: rotate(0deg);
-				}
+			.summary [data-slot="icon"] {
+				transform: rotate(0deg);
 			}
 
 			&::details-content {

package/ui/block/Details.tsx

@@ -1,31 +1,37 @@
-import { ChevronUpIcon } from "@heroicons/react/24/outline";
+import { ChevronUpIcon } from "@heroicons/react/24/solid";
 import type { ReactElement, ReactNode } from "react";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
-import { getClass } from "../util/css.js";
+import { getFlexClass } from "../style/Flex.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import type { ClassProps } from "../util/props.js";
 import DETAILS_CSS from "./Details.module.css";
 
-const DETAILS_CLASS = DETAILS_CSS.details;
-const DETAILS_SUMMARY_CLASS = DETAILS_CSS.summary;
+const DETAILS_CLASS = getModuleClass(DETAILS_CSS, "details");
+const DETAILS_SUMMARY_CLASS = getClass(getModuleClass(DETAILS_CSS, "summary"), getFlexClass({ between: true, gap: "normal" }));
 
-/** Props for `DetailsItem` — a single collapsible disclosure. */
+/**
+ * Props for `<Details>` — the summary title, the revealed content, and the open state.
+ *
+ * @see https://shelving.cc/ui/DetailsProps
+ */
 export interface DetailsProps extends BlockVariants, ClassProps {
 	/** Content of the always-visible summary (e.g. a question). */
 	title: ReactNode;
-	/** Whether the item starts expanded. */
+	/** Whether the panel starts expanded. */
 	open?: boolean | undefined;
-	/** Shared group name — items with the same `name` open exclusively (only one at a time). */
+	/** Shared group name — panels with the same `name` open exclusively (only one at a time). */
 	name?: string | undefined;
-	/** Content revealed when the item is expanded. */
+	/** Content revealed when the panel is expanded. */
 	children: ReactNode;
 }
 
 /**
- * A single collapsible panel within an `Details`, built on native `<details>` and `<summary>`
- * - Panel animates to its true height (where `interpolate-size` + `::details-content` are supported),
- * - Give sibling items a shared `name` to make them open exclusively.
+ * A collapsible panel with a title that is always visible, built on native `<details>` and `<summary>`.
+ * - The panel animates to its true height (where `interpolate-size` and `::details-content` are supported).
+ * - Give sibling panels a shared `name` to make them open exclusively.
  *
  * @kind component
+ * @see https://shelving.cc/ui/Details
  */
 export function Details({ title, open = false, name, children, className, ...props }: DetailsProps): ReactElement {
 	return (

package/ui/button/FullscreenButton.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/16/solid";
+import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/24/solid";
 import { useEffect, useState } from "react";
 import { Button } from "./Button.js";
 /**

package/ui/button/FullscreenButton.tsx

@@ -1,4 +1,4 @@
-import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/16/solid";
+import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/24/solid";
 import { type ReactElement, useEffect, useState } from "react";
 import type { ClassProps } from "../util/props.js";
 import { Button, type ButtonVariants } from "./Button.js";

package/ui/button/RetryButton.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ArrowPathIcon } from "@heroicons/react/16/solid";
+import { ArrowPathIcon } from "@heroicons/react/24/solid";
 import { createContext, use } from "react";
 import { Button } from "./Button.js";
 /**

package/ui/button/RetryButton.tsx

@@ -1,4 +1,4 @@
-import { ArrowPathIcon } from "@heroicons/react/16/solid";
+import { ArrowPathIcon } from "@heroicons/react/24/solid";
 import { createContext, type ReactElement, use } from "react";
 import type { Callback } from "../../util/function.js";
 import type { ClassProps, OptionalChildProps } from "../util/index.js";