@galaxy-io/dls 1.6.1 → 2.0.0

package/dist/json/JsonViewer.js

@@ -0,0 +1,483 @@
+import VisuallyHidden from "../a11y/VisuallyHidden.js";
+import { FontFamily } from "../theme/enums.js";
+import Text, { TextSize, TextVariant } from "../text/Text.js";
+import Icon, { IconVariant } from "../icons/Icon.js";
+import Rotate from "../transform/Rotate.js";
+import { ButtonSize, ButtonVariant } from "../buttons/Button.js";
+import CopyButton from "../buttons/CopyButton.js";
+import Span, { SpanVariant } from "../text/Span.js";
+import { InputSize, InputVariant } from "../inputs/Input.js";
+import SearchInput from "../inputs/SearchInput.js";
+import CollapseMotion from "../transform/internal/CollapseMotion.js";
+import { TREE_ROW_CSS, TREE_ROW_LABEL_CSS, TREE_ROW_LEVEL_VARIABLE, TREE_ROW_SIZE_TO_CARET_PX_MAP, TREE_ROW_SIZE_TO_CSS_MAP, TREE_ROW_SIZE_TO_TEXT_SIZE_MAP, TreeRowCaretSlot, TreeRowSize } from "../tree/treeRow.js";
+/* empty css                     */
+import { styled } from "@linaria/react";
+import { Fragment, forwardRef, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "@linaria/core";
+import { CaretRightIcon } from "@phosphor-icons/react";
+//#region src/json/JsonViewer.tsx
+/**
+* A JSON value as an explorable tree: one row per key or array item, objects and arrays expand
+* and collapse, primitive values are colored by type (strings green, numbers orange, booleans and
+* `null` purple, structure tertiary), an optional search field highlights matching keys and values
+* and opens their ancestors, and an optional footer shows the focused row's JSONPath with buttons
+* to copy the path or the value as JSON.
+*
+* Its rows are Tree's rows: one shared geometry module (`tree/treeRow.ts`: height, padding,
+* indent, caret slot and size, type step), the same roles and keys (flat `role="treeitem"` rows,
+* roving tab stop, arrows / Home / End / Enter / type-ahead), without composing Tree. It has no
+* selection: the footer follows focus. Read-only. Raw JSON to copy whole is `CodeBlock`; editing is `CodeEditor`.
+*/
+/** Row rung: the same two rungs, with the same row geometry, as `TreeSize`. */
+var JsonViewerSize = /* @__PURE__ */ function(JsonViewerSize) {
+	/** Tree's SMALL row: 24px, mono `body_sm`, 10px caret, 14px per level; `SMALL` search field, `X_SMALL` copy buttons. */
+	JsonViewerSize["SMALL"] = "SMALL";
+	/** Tree's MEDIUM row: 28px, mono `body_md`, 12px caret, 16px per level; `MEDIUM` search field, `SMALL` copy buttons. The default. */
+	JsonViewerSize["MEDIUM"] = "MEDIUM";
+	return JsonViewerSize;
+}({});
+/**
+* Tones per JSON type: CodeBlock's token hues for the same kinds (spec Decision 3). A typed css map
+* on an `INHERIT` `Span`, since Span's `variant` carries meaning only and has no palette members.
+*/
+var JSON_VALUE_KIND_TO_CSS_MAP = {
+	["OBJECT"]: "gx-JsonViewer-OBJECT-o12kbvy5",
+	["ARRAY"]: "gx-JsonViewer-ARRAY-auj7crq",
+	["STRING"]: "gx-JsonViewer-STRING-sd1e3sf",
+	["NUMBER"]: "gx-JsonViewer-NUMBER-nyuj9qk",
+	["BOOLEAN"]: "gx-JsonViewer-BOOLEAN-b977xl5",
+	["NULL"]: "gx-JsonViewer-NULL-nv25tp1"
+};
+/** Identity: the viewer's rungs are Tree's row rungs (`tree/treeRow.ts`), so the rows match exactly. */
+var JSON_VIEWER_SIZE_TO_ROW_SIZE_MAP = {
+	["SMALL"]: TreeRowSize.SMALL,
+	["MEDIUM"]: TreeRowSize.MEDIUM
+};
+var JSON_VIEWER_SIZE_TO_INPUT_SIZE_MAP = {
+	["SMALL"]: InputSize.SMALL,
+	["MEDIUM"]: InputSize.MEDIUM
+};
+var JSON_VIEWER_SIZE_TO_BUTTON_SIZE_MAP = {
+	["SMALL"]: ButtonSize.X_SMALL,
+	["MEDIUM"]: ButtonSize.SMALL
+};
+/** Printable keys typed within this window build one type-ahead query (logic, not motion). */
+var TYPEAHEAD_TIMEOUT_MS = 500;
+/** Keys that need no bracket notation in a JSONPath. */
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** The viewer: search field, rows, footer, stacked. No surface of its own (spec Decision 7). */
+var Root = /*#__PURE__*/ styled("div")({
+	name: "Root",
+	class: "gx-JsonViewer-rv7ru98",
+	propsAsIs: false
+});
+/** The `role="tree"` column of rows. */
+var TREE_CSS = "gx-JsonViewer-TREE_CSS-texbj7a";
+/** Hover and press fills on top of Tree's shared row (`TREE_ROW_CSS`); the viewer has no selection. */
+var ROW_INTERACTIVE_CSS = "gx-JsonViewer-ROW_INTERACTIVE_CSS-rrsy1zk";
+/** A search match: a categorical highlight, not selection (so not `background.selected`). */
+var MARK_CSS = "gx-JsonViewer-MARK_CSS-me67haa";
+/** The footer: the focused path and the two copy buttons, under a hairline rule. */
+var FOOTER_CSS = "gx-JsonViewer-FOOTER_CSS-f1rapjox";
+/** The footer's path takes the free width and truncates. */
+var FOOTER_PATH_CSS = "gx-JsonViewer-FOOTER_PATH_CSS-f3yxl0";
+var kindOf = (value) => {
+	if (value === null) return "NULL";
+	if (Array.isArray(value)) return "ARRAY";
+	switch (typeof value) {
+		case "string": return "STRING";
+		case "number": return "NUMBER";
+		case "boolean": return "BOOLEAN";
+		default: return "OBJECT";
+	}
+};
+/** The entries of a container as `[key, value]` pairs, in order. */
+var entriesOf = (value) => {
+	if (Array.isArray(value)) return value.map((item, index) => [index, item]);
+	if (value !== null && typeof value === "object") return Object.entries(value);
+	return [];
+};
+var childPath = (parent, key) => typeof key === "number" ? `${parent}[${key}]` : IDENTIFIER.test(key) ? `${parent}.${key}` : `${parent}[${JSON.stringify(key)}]`;
+var plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+/** What a value shows on its row: a primitive as JSON, a container as a summary. */
+var displayOf = (value, kind) => {
+	switch (kind) {
+		case "OBJECT": {
+			const count = entriesOf(value).length;
+			return count === 0 ? "{}" : `{${plural(count, "key", "keys")}}`;
+		}
+		case "ARRAY": {
+			const count = entriesOf(value).length;
+			return count === 0 ? "[]" : `[${plural(count, "item", "items")}]`;
+		}
+		case "STRING": return JSON.stringify(value);
+		default: return String(value);
+	}
+};
+/** The rows of `data` under its root: the root's entries, or one row for a primitive / empty root. */
+function getRootNodes(data) {
+	const kind = kindOf(data);
+	const entries = entriesOf(data);
+	if (entries.length === 0) return [{
+		path: "$",
+		key: null,
+		value: data,
+		kind,
+		isContainer: false,
+		level: 1,
+		parentPath: null
+	}];
+	return entries.map(([key, value]) => toNode(key, value, "$", 1, null));
+}
+function toNode(key, value, parent, level, parentPath) {
+	const kind = kindOf(value);
+	return {
+		path: childPath(parent, key),
+		key,
+		value,
+		kind,
+		isContainer: entriesOf(value).length > 0,
+		level,
+		parentPath
+	};
+}
+var childrenOf = (node) => entriesOf(node.value).map(([key, value]) => toNode(key, value, node.path, node.level + 1, node.path));
+/** Every node, depth first (for paths, values, search and the initial expansion). */
+function getAllNodes(data) {
+	const nodes = [];
+	const walk = (list) => {
+		for (const node of list) {
+			nodes.push(node);
+			if (node.isContainer) walk(childrenOf(node));
+		}
+	};
+	walk(getRootNodes(data));
+	return nodes;
+}
+/** The searchable text of a node's value: a primitive's display without quotes; containers none. */
+var searchTextOf = (node) => {
+	if (node.kind === "OBJECT" || node.kind === "ARRAY") return null;
+	const display = displayOf(node.value, node.kind);
+	return node.kind === "STRING" ? display.slice(1, -1) : display;
+};
+/** Whether a node's key (not an index) or primitive value contains the lower-cased term. */
+var isMatch = (node, term) => typeof node.key === "string" && node.key.toLowerCase().includes(term) || (searchTextOf(node)?.toLowerCase().includes(term) ?? false);
+/** Splits `text` around case-insensitive occurrences of `term`, marking each. */
+function highlight(text, term) {
+	if (term === "") return text;
+	const lower = text.toLowerCase();
+	const parts = [];
+	let from = 0;
+	let at = lower.indexOf(term, from);
+	if (at === -1) return text;
+	while (at !== -1) {
+		if (at > from) parts.push(text.slice(from, at));
+		parts.push(/* @__PURE__ */ jsx("mark", {
+			className: MARK_CSS,
+			children: text.slice(at, at + term.length)
+		}, `m${at}`));
+		from = at + term.length;
+		at = lower.indexOf(term, from);
+	}
+	if (from < text.length) parts.push(text.slice(from));
+	return parts;
+}
+var matchLabelOf = (count) => count === 0 ? "No matches" : plural(count, "match", "matches");
+/** A row's depth as the `--gx-json-viewer-level` custom property (0 at the top level). */
+var levelStyle = (level) => ({ [TREE_ROW_LEVEL_VARIABLE]: String(level - 1) });
+/** Collapsible, type-colored JSON with search and path copy. */
+var JsonViewer = forwardRef(function JsonViewer(props, ref) {
+	const { data, defaultExpandedDepth = 1, canSearch = false, canCopy = false, size = "MEDIUM", ariaLabel, "aria-label": ariaLabelAttribute, "aria-labelledby": labelledBy, id, className, style, ...rest } = props;
+	const rowSize = JSON_VIEWER_SIZE_TO_ROW_SIZE_MAP[size];
+	const textSize = TREE_ROW_SIZE_TO_TEXT_SIZE_MAP[rowSize];
+	const caretPx = TREE_ROW_SIZE_TO_CARET_PX_MAP[rowSize];
+	const treeName = ariaLabel ?? ariaLabelAttribute;
+	const allNodes = useMemo(() => getAllNodes(data), [data]);
+	const nodeByPath = useMemo(() => new Map(allNodes.map((node) => [node.path, node])), [allNodes]);
+	const [expanded, setExpanded] = useState(() => new Set(allNodes.filter((node) => node.isContainer && node.level <= defaultExpandedDepth).map((node) => node.path)));
+	const [term, setTerm] = useState("");
+	const preSearchExpanded = useRef(null);
+	const lowerTerm = term.toLowerCase();
+	const matchCount = useMemo(() => lowerTerm === "" ? 0 : allNodes.filter((node) => isMatch(node, lowerTerm)).length, [allNodes, lowerTerm]);
+	/** Search drives expansion: the ancestors of every match open; clearing restores the set. */
+	const handleSearch = (next) => {
+		const lower = next.toLowerCase();
+		if (lower === "") {
+			if (preSearchExpanded.current !== null) setExpanded(preSearchExpanded.current);
+			preSearchExpanded.current = null;
+			setTerm("");
+			return;
+		}
+		if (preSearchExpanded.current === null) preSearchExpanded.current = expanded;
+		const ancestors = /* @__PURE__ */ new Set();
+		for (const node of allNodes) {
+			if (!isMatch(node, lower)) continue;
+			let parent = node.parentPath;
+			while (parent !== null && !ancestors.has(parent)) {
+				ancestors.add(parent);
+				parent = nodeByPath.get(parent)?.parentPath ?? null;
+			}
+		}
+		setExpanded(ancestors);
+		setTerm(next);
+	};
+	const visible = useMemo(() => {
+		const rows = [];
+		const walk = (list) => {
+			for (const node of list) {
+				rows.push(node);
+				if (node.isContainer && expanded.has(node.path)) walk(childrenOf(node));
+			}
+		};
+		walk(getRootNodes(data));
+		return rows;
+	}, [data, expanded]);
+	const visibleIndex = useMemo(() => new Map(visible.map((node, index) => [node.path, index])), [visible]);
+	const [focusedPath, setFocusedPath] = useState(null);
+	/** The roving tab stop: the last focused row, its nearest visible ancestor, else the first row. */
+	const tabStopPath = useMemo(() => {
+		let path = focusedPath;
+		while (path !== null) {
+			if (visibleIndex.has(path)) return path;
+			path = nodeByPath.get(path)?.parentPath ?? null;
+		}
+		return visible[0]?.path ?? null;
+	}, [
+		focusedPath,
+		visible,
+		visibleIndex,
+		nodeByPath
+	]);
+	const rowElements = useRef(/* @__PURE__ */ new Map());
+	const rowRefCallbacks = useRef(/* @__PURE__ */ new Map());
+	const shouldRestoreFocus = useRef(false);
+	const setRowElement = (path) => {
+		let callback = rowRefCallbacks.current.get(path);
+		if (callback === void 0) {
+			callback = (element) => {
+				if (element) {
+					rowElements.current.set(path, element);
+					return;
+				}
+				const previous = rowElements.current.get(path);
+				if (previous !== void 0 && previous === previous.ownerDocument.activeElement) shouldRestoreFocus.current = true;
+				rowElements.current.delete(path);
+				rowRefCallbacks.current.delete(path);
+			};
+			rowRefCallbacks.current.set(path, callback);
+		}
+		return callback;
+	};
+	useEffect(() => {
+		if (!shouldRestoreFocus.current) return;
+		shouldRestoreFocus.current = false;
+		if (tabStopPath !== null) rowElements.current.get(tabStopPath)?.focus();
+	});
+	const typeahead = useRef({
+		query: "",
+		timer: void 0
+	});
+	useEffect(() => {
+		const state = typeahead.current;
+		return () => clearTimeout(state.timer);
+	}, []);
+	const focusRow = useCallback((path) => {
+		if (path === null || path === void 0) return;
+		rowElements.current.get(path)?.focus();
+	}, []);
+	const toggle = (path) => {
+		const next = new Set(expanded);
+		if (next.has(path)) next.delete(path);
+		else next.add(path);
+		setExpanded(next);
+	};
+	/** Moves focus to the next visible row whose key text starts with the typed query. */
+	const handleTypeahead = (fromIndex, character) => {
+		const state = typeahead.current;
+		clearTimeout(state.timer);
+		state.query += character.toLowerCase();
+		state.timer = setTimeout(() => {
+			state.query = "";
+		}, TYPEAHEAD_TIMEOUT_MS);
+		const isRepeat = [...state.query].every((entry) => entry === state.query[0]);
+		const query = isRepeat ? state.query.charAt(0) : state.query;
+		const start = isRepeat ? fromIndex + 1 : fromIndex;
+		for (let offset = 0; offset < visible.length; offset += 1) {
+			const node = visible[(start + offset) % visible.length];
+			if (node !== void 0 && node.key !== null && String(node.key).toLowerCase().startsWith(query)) {
+				focusRow(node.path);
+				return;
+			}
+		}
+	};
+	const handleKeyDown = (event, node) => {
+		if (event.target !== event.currentTarget) return;
+		const index = visibleIndex.get(node.path) ?? 0;
+		const isExpanded = node.isContainer && expanded.has(node.path);
+		let isHandled = true;
+		switch (event.key) {
+			case "ArrowDown":
+				focusRow(visible[index + 1]?.path);
+				break;
+			case "ArrowUp":
+				focusRow(visible[index - 1]?.path);
+				break;
+			case "Home":
+				focusRow(visible[0]?.path);
+				break;
+			case "End":
+				focusRow(visible[visible.length - 1]?.path);
+				break;
+			case "ArrowRight":
+				if (node.isContainer) if (!isExpanded) toggle(node.path);
+				else focusRow(visible[index + 1]?.path);
+				break;
+			case "ArrowLeft":
+				if (isExpanded) toggle(node.path);
+				else focusRow(node.parentPath);
+				break;
+			case "Enter":
+				if (node.isContainer) toggle(node.path);
+				break;
+			case " ": break;
+			default: if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) handleTypeahead(index, event.key);
+			else isHandled = false;
+		}
+		if (isHandled) event.preventDefault();
+	};
+	/** One level of rows, each container followed by its animated group. */
+	const renderNodes = (list) => list.map((node, position) => {
+		const isExpanded = node.isContainer && expanded.has(node.path);
+		const display = displayOf(node.value, node.kind);
+		const isContainerKind = node.kind === "OBJECT" || node.kind === "ARRAY";
+		const valueText = node.kind === "STRING" ? /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			"\"",
+			highlight(display.slice(1, -1), lowerTerm),
+			"\""
+		] }) : isContainerKind ? display : highlight(display, lowerTerm);
+		const handleCaretClick = (event) => {
+			event.stopPropagation();
+			rowElements.current.get(node.path)?.focus();
+			toggle(node.path);
+		};
+		return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("div", {
+			ref: setRowElement(node.path),
+			role: "treeitem",
+			"aria-level": node.level,
+			"aria-setsize": list.length,
+			"aria-posinset": position + 1,
+			"aria-expanded": node.isContainer ? isExpanded : void 0,
+			tabIndex: tabStopPath === node.path ? 0 : -1,
+			className: cx(TREE_ROW_CSS, TREE_ROW_SIZE_TO_CSS_MAP[rowSize], ROW_INTERACTIVE_CSS),
+			style: levelStyle(node.level),
+			onFocus: () => setFocusedPath(node.path),
+			onClick: () => {
+				if (node.isContainer) toggle(node.path);
+			},
+			onKeyDown: (event) => handleKeyDown(event, node),
+			children: [/* @__PURE__ */ jsx(TreeRowCaretSlot, {
+				"aria-hidden": true,
+				onClick: node.isContainer ? handleCaretClick : void 0,
+				children: node.isContainer && /* @__PURE__ */ jsx(Rotate, {
+					isRotated: isExpanded,
+					deg: 90,
+					children: /* @__PURE__ */ jsx(Icon, {
+						component: CaretRightIcon,
+						size: caretPx,
+						variant: IconVariant.TERTIARY
+					})
+				})
+			}), /* @__PURE__ */ jsxs(Text, {
+				as: "span",
+				family: FontFamily.MONO,
+				size: textSize,
+				lineClamp: 1,
+				shouldTooltipOnOverflow: true,
+				className: TREE_ROW_LABEL_CSS,
+				children: [node.key !== null && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Span, {
+					variant: typeof node.key === "number" ? SpanVariant.TERTIARY : SpanVariant.PRIMARY,
+					children: typeof node.key === "number" ? String(node.key) : highlight(node.key, lowerTerm)
+				}), /* @__PURE__ */ jsx(Span, {
+					variant: SpanVariant.SECONDARY,
+					children: ": "
+				})] }), /* @__PURE__ */ jsx(Span, {
+					variant: SpanVariant.INHERIT,
+					className: JSON_VALUE_KIND_TO_CSS_MAP[node.kind],
+					children: valueText
+				})]
+			})]
+		}), node.isContainer && /* @__PURE__ */ jsx(CollapseMotion, {
+			isOpen: isExpanded,
+			children: isExpanded && renderNodes(childrenOf(node))
+		})] }, node.path);
+	});
+	const footerNode = nodeByPath.get(focusedPath ?? "$");
+	const footerPath = focusedPath ?? "$";
+	const footerValue = JSON.stringify(footerNode?.value ?? data, null, 2);
+	const matchLabel = matchLabelOf(matchCount);
+	const buttonSize = JSON_VIEWER_SIZE_TO_BUTTON_SIZE_MAP[size];
+	return /* @__PURE__ */ jsxs(Root, {
+		...rest,
+		ref,
+		id,
+		className,
+		style,
+		children: [
+			canSearch && /* @__PURE__ */ jsx(SearchInput, {
+				size: JSON_VIEWER_SIZE_TO_INPUT_SIZE_MAP[size],
+				variant: InputVariant.PRIMARY,
+				fillWidth: true,
+				ariaLabel: `Search ${treeName ?? "JSON"}`,
+				onSearch: handleSearch,
+				trailing: term !== "" && /* @__PURE__ */ jsx(Text, {
+					as: "span",
+					size: TextSize.BODY_SM,
+					variant: TextVariant.TERTIARY,
+					children: matchLabel
+				})
+			}),
+			/* @__PURE__ */ jsx("div", {
+				role: "tree",
+				"aria-label": treeName,
+				"aria-labelledby": labelledBy,
+				className: TREE_CSS,
+				children: renderNodes(getRootNodes(data))
+			}),
+			canCopy && /* @__PURE__ */ jsxs("div", {
+				className: FOOTER_CSS,
+				children: [
+					/* @__PURE__ */ jsx(Text, {
+						as: "span",
+						family: FontFamily.MONO,
+						size: textSize,
+						variant: TextVariant.SECONDARY,
+						lineClamp: 1,
+						shouldTooltipOnOverflow: true,
+						className: FOOTER_PATH_CSS,
+						children: footerPath
+					}),
+					/* @__PURE__ */ jsx(CopyButton, {
+						value: footerPath,
+						label: "Copy path",
+						size: buttonSize,
+						variant: ButtonVariant.TERTIARY
+					}),
+					/* @__PURE__ */ jsx(CopyButton, {
+						value: footerValue,
+						label: "Copy value",
+						size: buttonSize,
+						variant: ButtonVariant.TERTIARY
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx(VisuallyHidden, {
+				"aria-live": "polite",
+				children: term === "" ? "" : matchLabel
+			})
+		]
+	});
+});
+JsonViewer.displayName = "JsonViewer";
+//#endregion
+export { JsonViewerSize, JsonViewer as default };

package/dist/layout/Box.d.ts

@@ -0,0 +1,87 @@
+import { type AriaAttributes, type CSSProperties, type ElementType, type ReactNode } from "react";
+import { Radius, type SpaceShorthand } from "../theme/enums.js";
+/** Surface step the box fills with (surface set, Constitution V-A). Leave `variant` unset for no fill. */
+export declare enum BoxVariant {
+    /** The canvas, `background.base`. */
+    BASE = "BASE",
+    /** A panel, `background.primary`. */
+    PRIMARY = "PRIMARY",
+    /** A raised surface, `background.secondary`. */
+    SECONDARY = "SECONDARY",
+    /** The most elevated surface, `background.tertiary`. */
+    TERTIARY = "TERTIARY"
+}
+/** Offsets for a positioned box. A number is px; a string is any CSS length. */
+export type BoxInset = {
+    /** CSS `top`. */
+    top?: number | string;
+    /** CSS `right`. */
+    right?: number | string;
+    /** CSS `bottom`. */
+    bottom?: number | string;
+    /** CSS `left`. */
+    left?: number | string;
+};
+export interface BoxProps extends AriaAttributes {
+    /** Content of the box. */
+    children?: ReactNode;
+    /**
+     * Surface step the box fills with. Unset draws no fill: the parent shows through.
+     * @default undefined (no fill)
+     */
+    variant?: BoxVariant;
+    /**
+     * Draw the `0.5px` hairline border (`border.primary`).
+     * @default false
+     */
+    hasBorder?: boolean;
+    /** Corner radius from the scale. Square corners when omitted. */
+    radius?: Radius;
+    /** Padding from the space scale: one value, or 2–4 in CSS shorthand order (`[12, 16]`). */
+    padding?: SpaceShorthand;
+    /** CSS `width`. A number is px. `fillWidth` wins over it. */
+    width?: number | string;
+    /** CSS `height`. A number is px. Use `"100%"` to fill the parent (1.x `fillHeight`). */
+    height?: number | string;
+    /** CSS `min-width`. A number is px. */
+    minWidth?: number | string;
+    /** CSS `max-width`. A number is px. (1.x `Wrapper maxWidth` set `width`; use `width` for that.) */
+    maxWidth?: number | string;
+    /** CSS `min-height`. A number is px. */
+    minHeight?: number | string;
+    /** CSS `max-height`. A number is px. */
+    maxHeight?: number | string;
+    /**
+     * Stretch to the parent's full width (`width: 100%`). Wins over `width`.
+     * @default false
+     */
+    fillWidth?: boolean;
+    /**
+     * CSS `overflow`.
+     * @default "visible"
+     */
+    overflow?: CSSProperties["overflow"];
+    /**
+     * CSS `position`.
+     * @default static
+     */
+    position?: CSSProperties["position"];
+    /** `top` / `right` / `bottom` / `left` offsets; they apply once `position` is not `static`. */
+    inset?: BoxInset;
+    /**
+     * Element or component to render (`"section"`, `"aside"`, a router link).
+     * @default "div"
+     */
+    as?: ElementType;
+    /** DOM id on the root element. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root element. */
+    className?: string;
+    /** Inline style on the root element; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** A block container with a surface, an optional hairline border, a radius and padding. */
+declare const Box: import("react").ForwardRefExoticComponent<BoxProps & import("react").RefAttributes<HTMLElement>>;
+export default Box;

package/dist/layout/Box.js

@@ -0,0 +1,109 @@
+import { Radius } from "../theme/enums.js";
+import { getCssSizeValue, spaceToCss } from "../utils/css.js";
+/* empty css              */
+import { styled } from "@linaria/react";
+import { forwardRef } from "react";
+import { jsx } from "react/jsx-runtime";
+import { cx } from "@linaria/core";
+//#region src/layout/Box.tsx
+/**
+* The generic block container: a surface step, an optional hairline border, a radius, padding,
+* and the sizing / positioning props a layout component may carry (Constitution V). Replaces 1.x
+* `Wrapper` (the positioning box) and `Spacing` (margins are gone; use the parent's `gap` or
+* `padding`).
+*
+* Continuous values (`padding`, sizes, `overflow`, `position`, `inset`) are set as `--gx-box-*`
+* custom properties on the root, and a block that reads each one is switched on only when its prop
+* is set. So a nested `Box` never inherits its parent's values, and nothing extra reaches a custom
+* `as` component (Linaria forwards `$`-props to one).
+*/
+/** Surface step the box fills with (surface set, Constitution V-A). Leave `variant` unset for no fill. */
+var BoxVariant = /* @__PURE__ */ function(BoxVariant) {
+	/** The canvas, `background.base`. */
+	BoxVariant["BASE"] = "BASE";
+	/** A panel, `background.primary`. */
+	BoxVariant["PRIMARY"] = "PRIMARY";
+	/** A raised surface, `background.secondary`. */
+	BoxVariant["SECONDARY"] = "SECONDARY";
+	/** The most elevated surface, `background.tertiary`. */
+	BoxVariant["TERTIARY"] = "TERTIARY";
+	return BoxVariant;
+}({});
+var Root = /*#__PURE__*/ styled("div")({
+	name: "Root",
+	class: "gx-Box-rcu11uw",
+	propsAsIs: false
+});
+var BOX_VARIANT_TO_CSS_MAP = {
+	["BASE"]: "gx-Box-BASE-bn7d3r",
+	["PRIMARY"]: "gx-Box-PRIMARY-p1tb0t1s",
+	["SECONDARY"]: "gx-Box-SECONDARY-sngj0ew",
+	["TERTIARY"]: "gx-Box-TERTIARY-t1vd7izj"
+};
+var RADIUS_TO_CSS_MAP = {
+	[Radius.SM]: "gx-Box-Radius_SM-r1duzr06",
+	[Radius.MD]: "gx-Box-Radius_MD-r501792",
+	[Radius.LG]: "gx-Box-Radius_LG-rxydgx9",
+	[Radius.PILL]: "gx-Box-Radius_PILL-rrn38q3"
+};
+var BORDER_CSS = "gx-Box-BORDER_CSS-b1aq7688";
+var FILL_WIDTH_CSS = "gx-Box-FILL_WIDTH_CSS-f1nw7r38";
+/** Each block reads the `--gx-box-<property>` custom property the component sets beside it. */
+var BOX_CSS_PROPERTY_TO_CSS_MAP = {
+	padding: "gx-Box-padding-poq987s",
+	width: "gx-Box-width-w1dvt2z3",
+	height: "gx-Box-height-hpkzdg3",
+	"min-width": "gx-Box-min-width-m1w4kn1o",
+	"max-width": "gx-Box-max-width-morpz05",
+	"min-height": "gx-Box-min-height-mwtkiw3",
+	"max-height": "gx-Box-max-height-mz7b6w6",
+	overflow: "gx-Box-overflow-o1d5jyby",
+	position: "gx-Box-position-p1cr9tw3",
+	top: "gx-Box-top-t176ib3h",
+	right: "gx-Box-right-rjk68mc",
+	bottom: "gx-Box-bottom-bqrxdfn",
+	left: "gx-Box-left-l1xu1nwn"
+};
+/** A length prop as CSS (number → px), or `undefined` when unset. */
+var toLength = (value) => value === void 0 ? void 0 : getCssSizeValue(value);
+/** A block container with a surface, an optional hairline border, a radius and padding. */
+var Box = forwardRef(function Box({ children, variant, hasBorder = false, radius, padding, width, height, minWidth, maxWidth, minHeight, maxHeight, fillWidth = false, overflow, position, inset, as = "div", id, className, style, ...rest }, ref) {
+	const values = {
+		padding: padding === void 0 ? void 0 : spaceToCss(padding),
+		width: fillWidth ? void 0 : toLength(width),
+		height: toLength(height),
+		"min-width": toLength(minWidth),
+		"max-width": toLength(maxWidth),
+		"min-height": toLength(minHeight),
+		"max-height": toLength(maxHeight),
+		overflow,
+		position,
+		top: toLength(inset?.top),
+		right: toLength(inset?.right),
+		bottom: toLength(inset?.bottom),
+		left: toLength(inset?.left)
+	};
+	const classNames = [];
+	const variables = {};
+	for (const property of Object.keys(values)) {
+		const value = values[property];
+		if (value === void 0) continue;
+		classNames.push(BOX_CSS_PROPERTY_TO_CSS_MAP[property]);
+		variables[`--gx-box-${property}`] = value;
+	}
+	return /* @__PURE__ */ jsx(Root, {
+		...rest,
+		as,
+		ref,
+		id,
+		className: cx(variant !== void 0 && BOX_VARIANT_TO_CSS_MAP[variant], hasBorder && BORDER_CSS, radius !== void 0 && RADIUS_TO_CSS_MAP[radius], fillWidth && FILL_WIDTH_CSS, ...classNames, className),
+		style: {
+			...variables,
+			...style
+		},
+		children
+	});
+});
+Box.displayName = "Box";
+//#endregion
+export { BoxVariant, Box as default };