@galaxy-io/dls 1.4.9 → 1.4.11

package/dist/charts/useChartInteraction.js

@@ -1,11 +1,65 @@
 import { ChartMarkState } from "./types.js";
-import { useCallback, useMemo, useState } from "react";
+import { DashboardContext } from "./DashboardProvider.js";
+import { useCallback, useContext, useEffect, useId, useMemo, useState } from "react";
 //#region src/charts/useChartInteraction.ts
-function useChartInteraction({ categoryCount, seriesKeys, disabled = false, isLoading = false }) {
+function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, disabled = false, isLoading = false }) {
 	const [hoveredIndex, setHoveredIndex] = useState(null);
 	const [hoveredSeriesKey, setHoveredSeriesKey] = useState(null);
+	const sync = useContext(DashboardContext);
+	const syncId = useId();
+	const canSync = sync !== null && categoryKeys !== void 0;
+	const setActive = sync?.setActive;
+	const clearActive = sync?.clearActive;
 	const safeHovered = hoveredIndex !== null && hoveredIndex < categoryCount ? hoveredIndex : null;
 	const safeHoveredSeries = hoveredSeriesKey !== null && (seriesKeys === void 0 || seriesKeys.includes(hoveredSeriesKey)) ? hoveredSeriesKey : null;
+	/**
+	* Publish this chart's hover to the sync group.
+	*
+	* An effect over the derived label rather than calls inside the pointer
+	* handlers, so three edge cases collapse into one place: data shrinking
+	* under a resting pointer (the `safeHovered` guard nulls the key → clears),
+	* the label at the resting index changing (republishes what is now under
+	* the pointer), and unmount while source (the cleanup effect below).
+	* Source-only writes still hold — `localKey` derives from `safeHovered`,
+	* which only this chart's own pointer sets.
+	*/
+	const localKey = canSync && safeHovered !== null ? categoryKeys[safeHovered] ?? null : null;
+	useEffect(() => {
+		if (!setActive || !clearActive) return;
+		if (localKey !== null) setActive({
+			sourceId: syncId,
+			categoryKey: localKey
+		});
+		else clearActive(syncId);
+	}, [
+		setActive,
+		clearActive,
+		syncId,
+		localKey
+	]);
+	useEffect(() => () => clearActive?.(syncId), [clearActive, syncId]);
+	/**
+	* The category a sibling is hovering, resolved to this chart's own index.
+	*
+	* `isLoading` blocks following — the marks are force-muted anyway, but
+	* without the guard LineChart would still draw its cursor and dots through
+	* a loading plot. An unmatched label resolves to no crosshair at all, which
+	* is how charts with partially overlapping categories degrade.
+	*/
+	const followedIndex = useMemo(() => {
+		if (!canSync || isLoading) return null;
+		const entry = sync.activeEntry;
+		if (entry === null || entry.sourceId === syncId) return null;
+		const index = categoryKeys.indexOf(entry.categoryKey);
+		return index === -1 ? null : index;
+	}, [
+		canSync,
+		isLoading,
+		sync?.activeEntry,
+		syncId,
+		categoryKeys
+	]);
+	const effectiveIndex = safeHovered ?? followedIndex;
 	const onCategoryEnter = useCallback((categoryIndex) => {
 		if (disabled) return;
 		setHoveredIndex(categoryIndex);
@@ -22,22 +76,23 @@ function useChartInteraction({ categoryCount, seriesKeys, disabled = false, isLo
 	}, []);
 	const getMarkState = useCallback(({ categoryIndex, seriesKey }) => {
 		if (isLoading) return ChartMarkState.MUTED;
-		return categoryIndex !== void 0 && safeHovered !== null && categoryIndex !== safeHovered || seriesKey !== void 0 && safeHoveredSeries !== null && seriesKey !== safeHoveredSeries ? ChartMarkState.MUTED : ChartMarkState.ACTIVE;
+		return categoryIndex !== void 0 && effectiveIndex !== null && categoryIndex !== effectiveIndex || seriesKey !== void 0 && safeHoveredSeries !== null && seriesKey !== safeHoveredSeries ? ChartMarkState.MUTED : ChartMarkState.ACTIVE;
 	}, [
 		isLoading,
-		safeHovered,
+		effectiveIndex,
 		safeHoveredSeries
 	]);
 	return useMemo(() => ({
-		activeIndex: safeHovered,
+		activeIndex: effectiveIndex,
+		hasLocalHover: safeHovered !== null,
 		hoveredSeriesKey: safeHoveredSeries,
-		isEngaged: safeHovered !== null || safeHoveredSeries !== null,
 		getMarkState,
 		onCategoryEnter,
 		onCategoryLeave,
 		onSeriesEnter,
 		onSeriesLeave
 	}), [
+		effectiveIndex,
 		safeHovered,
 		safeHoveredSeries,
 		getMarkState,

package/dist/chips/Chip.d.ts

@@ -1,4 +1,5 @@
 import type { Icon as PhosphorIcon } from "@phosphor-icons/react";
+/** Chip color. Tints the background, border and label together. */
 export declare enum ChipVariant {
     PRIMARY = "PRIMARY",
     PRIMARY_ALT = "PRIMARY_ALT",
@@ -15,25 +16,43 @@ export declare enum ChipVariant {
     PURPLE = "PURPLE",
     TEAL = "TEAL"
 }
+/** Chip height. Also drives label and icon size. */
 export declare enum ChipSize {
     SMALL = "SMALL",
     MEDIUM = "MEDIUM",
     LARGE = "LARGE"
 }
 export interface ChipProps {
+    /** Chip text. Required unless `icon` is set — with neither, nothing renders. */
     label?: string | number;
+    /** @default ChipVariant.SECONDARY */
     variant?: ChipVariant;
+    /** @default ChipSize.MEDIUM */
     size?: ChipSize;
+    /** Custom leading graphic. Takes precedence over `icon`. */
     svg?: React.ReactNode;
+    /** Phosphor icon *component* — pass `TagIcon`, not `<TagIcon />`. */
     icon?: PhosphorIcon;
+    /** Adds a trailing × button. Omit and the chip isn't dismissible. */
     onDismiss?: () => void;
+    /** Also flips the cursor to `pointer`. */
     onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+    /** Fully rounded ends instead of the default small radius. */
     isPill?: boolean;
+    /** Drop the fill and keep only the border. */
     noBackground?: boolean;
+    /** Swap the label for a shimmer placeholder. */
     isLoading?: boolean;
+    /** Truncate a long label with an ellipsis. Needs a width-bounded parent. */
     isEllipsis?: boolean;
-    /** When true, shows active/selected styling with variant-colored border */
+    /** Selected styling — border picks up the variant color. */
     isActive?: boolean;
 }
+/**
+ * A compact tag for a value, filter, or status.
+ *
+ * Renders `null` when neither `label` nor `icon` is set. Adding `onDismiss`
+ * appends a × button; adding `onClick` makes the whole chip clickable.
+ */
 declare const Chip: ({ label, variant, size, svg, icon, onDismiss, onClick, isPill, noBackground, isLoading, isEllipsis, isActive, }: ChipProps) => import("react").JSX.Element | null;
 export default Chip;

package/dist/chips/Chip.js

@@ -12,6 +12,7 @@ import { match } from "ts-pattern";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { XIcon } from "@phosphor-icons/react";
 //#region src/chips/Chip.tsx
+/** Chip color. Tints the background, border and label together. */
 var ChipVariant = /* @__PURE__ */ function(ChipVariant) {
 	ChipVariant["PRIMARY"] = "PRIMARY";
 	ChipVariant["PRIMARY_ALT"] = "PRIMARY_ALT";
@@ -29,6 +30,7 @@ var ChipVariant = /* @__PURE__ */ function(ChipVariant) {
 	ChipVariant["TEAL"] = "TEAL";
 	return ChipVariant;
 }({});
+/** Chip height. Also drives label and icon size. */
 var ChipSize = /* @__PURE__ */ function(ChipSize) {
 	ChipSize["SMALL"] = "SMALL";
 	ChipSize["MEDIUM"] = "MEDIUM";
@@ -40,7 +42,7 @@ var _exp2 = () => ({ $size }) => {
 	return match($size).with("SMALL", () => "18px").with("MEDIUM", () => "20px").with("LARGE", () => "24px").exhaustive();
 };
 var _exp3 = () => ({ $size }) => {
-	return match($size).with("SMALL", () => "0 4px").with("MEDIUM", () => "0 6px").with("LARGE", () => "0 8px").exhaustive();
+	return match($size).with("SMALL", () => "0 5px").with("MEDIUM", () => "0 6px").with("LARGE", () => "0 8px").exhaustive();
 };
 var _exp4 = () => ({ theme, $variant, $noBackground }) => {
 	if ($noBackground) return "transparent";
@@ -111,6 +113,12 @@ var CHIP_SIZE_TO_TEXT_SIZE = {
 	["MEDIUM"]: TextSize.BODY_MD,
 	["LARGE"]: TextSize.BODY_LG
 };
+/**
+* A compact tag for a value, filter, or status.
+*
+* Renders `null` when neither `label` nor `icon` is set. Adding `onDismiss`
+* appends a × button; adding `onClick` makes the whole chip clickable.
+*/
 var Chip = ({ label, variant = "SECONDARY", size = "MEDIUM", svg, icon, onDismiss, onClick, isPill, noBackground, isLoading, isEllipsis, isActive }) => {
 	if (!label && !icon) return null;
 	if (isLoading) return /* @__PURE__ */ jsxs(StyledChip, {

package/dist/containers/FlexItem.d.ts

@@ -1,27 +1,24 @@
 import { type CSSProperties } from "react";
 import { AlignItems, JustifyContent } from "./FlexWrapper";
-interface FlexItemProps {
+export interface FlexItemProps {
+    /** @default "static" */
     position?: CSSProperties["position"];
-    /**
-     * flex-grow of this item within its parent flex container.
-     * Defaults to 0 (content-sized), matching the CSS default.
-     */
+    /** flex-grow within the parent flex container. @default 0 */
     grow?: number;
-    /**
-     * flex-shrink of this item within its parent flex container.
-     * Defaults to 1, matching the CSS default.
-     */
+    /** flex-shrink within the parent flex container. @default 1 */
     shrink?: number;
-    /**
-     * flex-basis of this item. Defaults to auto.
-     */
+    /** flex-basis. A number is px. @default "auto" */
     basis?: number | string;
     overflow?: CSSProperties["overflow"];
     whiteSpace?: CSSProperties["whiteSpace"];
     textOverflow?: CSSProperties["textOverflow"];
+    /** A number is px. */
     width?: number | string;
+    /** A number is px. */
     height?: number | string;
+    /** `width: 100%`. Takes precedence over `width`. */
     fillWidth?: boolean;
+    /** `height: 100%`. Takes precedence over `height`. */
     fillHeight?: boolean;
     /**
      * Defaults to "flex" (not "block"): a FlexItem is itself a flex container,
@@ -40,8 +37,13 @@ interface FlexItemProps {
     maxWidth?: number | string;
     maxHeight?: number | string;
     padding?: CSSProperties["padding"];
+    /** Also flips the cursor to `pointer`. */
     onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
 }
+/**
+ * A single child of a `FlexWrapper`, for when one item needs its own grow,
+ * shrink, or sizing rules. Reach for it only when the wrapper can't express it.
+ */
 declare const FlexItem: import("react").ForwardRefExoticComponent<FlexItemProps & {
     children?: import("react").ReactNode | undefined;
 } & import("react").RefAttributes<HTMLDivElement>>;

package/dist/containers/FlexItem.js

@@ -55,6 +55,10 @@ var StyledFlexItem = /*#__PURE__*/ styled("div")({
 		"s1he36jx-17": [_exp16()]
 	}
 });
+/**
+* A single child of a `FlexWrapper`, for when one item needs its own grow,
+* shrink, or sizing rules. Reach for it only when the wrapper can't express it.
+*/
 var FlexItem = forwardRef(({ children, position, grow, shrink, basis, overflow, whiteSpace, textOverflow, width, height, fillWidth, fillHeight, display, alignItems, justifyContent, minWidth, minHeight, maxWidth, maxHeight, padding, onClick }, ref) => {
 	return /* @__PURE__ */ jsx(StyledFlexItem, {
 		ref,

package/dist/containers/FlexWrapper.d.ts

@@ -1,9 +1,11 @@
+/** Main-axis direction of the flex container. */
 export declare enum FlexDirection {
     ROW = "row",
     COLUMN = "column",
     ROW_REVERSE = "row-reverse",
     COLUMN_REVERSE = "column-reverse"
 }
+/** Cross-axis alignment of children (`align-items`). */
 export declare enum AlignItems {
     START = "start",
     CENTER = "center",
@@ -11,6 +13,7 @@ export declare enum AlignItems {
     BASELINE = "baseline",
     STRETCH = "stretch"
 }
+/** Main-axis distribution of children (`justify-content`). */
 export declare enum JustifyContent {
     START = "start",
     CENTER = "center",
@@ -19,11 +22,13 @@ export declare enum JustifyContent {
     SPACE_AROUND = "space-around",
     SPACE_EVENLY = "space-evenly"
 }
+/** Wrapping behavior when children overflow the main axis. */
 export declare enum FlexWrap {
     NOWRAP = "nowrap",
     WRAP = "wrap",
     WRAP_REVERSE = "wrap-reverse"
 }
+/** Named steps on the spacing scale. `gap` also accepts a raw number of px. */
 export declare enum FlexGap {
     NONE = "0",
     XXSMALL = "2px",
@@ -34,129 +39,57 @@ export declare enum FlexGap {
     XLARGE = "24px",
     XXLARGE = "32px"
 }
-interface FlexWrapperProps {
-    /**
-     * Sets the direction of the flex container
-     * - ROW: Items are placed in a row (default)
-     * - COLUMN: Items are placed in a column
-     * - ROW_REVERSE: Items are placed in a row, from right to left
-     * - COLUMN_REVERSE: Items are placed in a column, from bottom to top
-     */
+export interface FlexWrapperProps {
+    /** @default FlexDirection.ROW */
     direction?: FlexDirection;
-    /**
-     * Defines how flex items are aligned along the cross axis
-     * - START: Items are aligned at the start (default)
-     * - CENTER: Items are centered
-     * - END: Items are aligned at the end
-     * - BASELINE: Items are aligned at their baselines
-     * - STRETCH: Items are stretched to fill the container
-     */
+    /** @default AlignItems.START */
     alignItems?: AlignItems;
-    /**
-     * Defines how flex items are aligned along the main axis
-     * - START: Items are aligned at the start (default)
-     * - CENTER: Items are centered
-     * - END: Items are aligned at the end
-     * - SPACE_BETWEEN: Items are evenly distributed with equal space between them
-     * - SPACE_AROUND: Items are evenly distributed with equal space around them
-     * - SPACE_EVENLY: Items are evenly distributed with equal space between and around them
-     */
+    /** @default JustifyContent.START */
     justifyContent?: JustifyContent;
-    /**
-     * Controls whether flex items should wrap when there isn't enough space
-     * - NOWRAP: Items will not wrap (default)
-     * - WRAP: Items will wrap onto multiple lines if needed
-     * - WRAP_REVERSE: Items will wrap onto multiple lines in reverse order
-     */
+    /** @default FlexWrap.NOWRAP */
     wrap?: FlexWrap;
-    /**
-     * Sets the gap between flex items in pixels or string (for other units)
-     */
+    /** Space between children. A number is px; use `FlexGap` for the scale. */
     gap?: number | string;
     /**
-     * flex-grow of this wrapper when it is itself a child of a flex container.
-     * Defaults to the CSS initial value (0). Saves wrapping in a FlexItem just
-     * to control how the wrapper flexes.
+     * flex-grow / -shrink / -basis of the wrapper itself, for when it is also a
+     * child of another flex container. Saves nesting it in a FlexItem.
      */
     grow?: number;
-    /**
-     * flex-shrink of this wrapper when it is itself a child of a flex container.
-     * Defaults to the CSS initial value (1).
-     */
     shrink?: number;
-    /**
-     * flex-basis of this wrapper when it is itself a child of a flex container.
-     * Defaults to the CSS initial value (auto).
-     */
     basis?: number | string;
-    /**
-     * Sets the width of the flex container in pixels
-     */
+    /** A number is px. @default "auto" */
     width?: number | string;
-    /**
-     * Sets the height of the flex container in pixels
-     */
+    /** A number is px. @default "auto" */
     height?: number | string;
-    /**
-     * Sets the minimum width of the flex container in pixels
-     */
+    /** Pass `0` to let this shrink below its content so nested text can ellipsize. */
     minWidth?: number | string;
-    /**
-     * Sets the maximum width of the flex container in pixels
-     */
     maxWidth?: number | string;
-    /**
-     * Sets the minimum height of the flex container in pixels
-     */
     minHeight?: number | string;
-    /**
-     * Sets the maximum height of the flex container in pixels
-     */
     maxHeight?: number | string;
-    /**
-     * When true, the container will fill its parent's width (equivalent to width: 100%)
-     */
+    /** `width: 100%`. Takes precedence over `width`. */
     fillWidth?: boolean;
-    /**
-     * When true, the container will fill its parent's height (equivalent to height: 100%)
-     */
+    /** `height: 100%`. Takes precedence over `height`. */
     fillHeight?: boolean;
-    /**
-     * Controls how content that overflows the container should be handled
-     * Default is 'visible'
-     */
+    /** @default "visible" */
     overflow?: React.CSSProperties["overflow"];
-    /**
-     * Sets the padding inside the container
-     * Can be a number (for pixels) or a string (for other units)
-     */
+    /** Inner spacing. Use this rather than `margin` — DLS spaces with gap and padding. */
     padding?: React.CSSProperties["padding"];
-    /**
-     * Sets the margin inside the container
-     * Can be a number (for pixels) or a string (for other units)
-     */
+    /** Escape hatch. DLS spaces with `gap` and `padding` — reach for those first. */
     margin?: React.CSSProperties["margin"];
-    /**
-     * Optional click handler for the flex container
-     */
+    /** Also flips the cursor to `pointer`. */
     onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
-    /**
-     * Optional mousedown handler for the flex container
-     */
     onMouseDown?: (event: React.MouseEvent<HTMLDivElement>) => void;
-    /**
-     * Optional mouseenter handler for the flex container
-     */
     onMouseEnter?: (event: React.MouseEvent<HTMLDivElement>) => void;
-    /**
-     * Optional mouseleave handler for the flex container
-     */
     onMouseLeave?: (event: React.MouseEvent<HTMLDivElement>) => void;
-    /**
-     * Optional scroll handler for the flex container
-     */
     onScroll?: (event: React.UIEvent<HTMLDivElement>) => void;
 }
+/**
+ * The layout workhorse — a `display: flex` div with every flex and sizing knob
+ * as a prop. Compose UI out of these plus whitespace rather than decorating.
+ *
+ * Sizing props respect an explicit `0`, so `minWidth={0}` works as the standard
+ * fix for letting a flex child shrink enough for nested text to ellipsize.
+ */
 declare const FlexWrapper: import("react").ForwardRefExoticComponent<FlexWrapperProps & {
     children?: import("react").ReactNode | undefined;
 } & import("react").RefAttributes<HTMLDivElement>>;

package/dist/containers/FlexWrapper.js

@@ -4,6 +4,7 @@ import { styled } from "@linaria/react";
 import { forwardRef } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/containers/FlexWrapper.tsx
+/** Main-axis direction of the flex container. */
 var FlexDirection = /* @__PURE__ */ function(FlexDirection) {
 	FlexDirection["ROW"] = "row";
 	FlexDirection["COLUMN"] = "column";
@@ -11,6 +12,7 @@ var FlexDirection = /* @__PURE__ */ function(FlexDirection) {
 	FlexDirection["COLUMN_REVERSE"] = "column-reverse";
 	return FlexDirection;
 }({});
+/** Cross-axis alignment of children (`align-items`). */
 var AlignItems = /* @__PURE__ */ function(AlignItems) {
 	AlignItems["START"] = "start";
 	AlignItems["CENTER"] = "center";
@@ -19,6 +21,7 @@ var AlignItems = /* @__PURE__ */ function(AlignItems) {
 	AlignItems["STRETCH"] = "stretch";
 	return AlignItems;
 }({});
+/** Main-axis distribution of children (`justify-content`). */
 var JustifyContent = /* @__PURE__ */ function(JustifyContent) {
 	JustifyContent["START"] = "start";
 	JustifyContent["CENTER"] = "center";
@@ -28,12 +31,14 @@ var JustifyContent = /* @__PURE__ */ function(JustifyContent) {
 	JustifyContent["SPACE_EVENLY"] = "space-evenly";
 	return JustifyContent;
 }({});
+/** Wrapping behavior when children overflow the main axis. */
 var FlexWrap = /* @__PURE__ */ function(FlexWrap) {
 	FlexWrap["NOWRAP"] = "nowrap";
 	FlexWrap["WRAP"] = "wrap";
 	FlexWrap["WRAP_REVERSE"] = "wrap-reverse";
 	return FlexWrap;
 }({});
+/** Named steps on the spacing scale. `gap` also accepts a raw number of px. */
 var FlexGap = /* @__PURE__ */ function(FlexGap) {
 	FlexGap["NONE"] = "0";
 	FlexGap["XXSMALL"] = "2px";
@@ -96,6 +101,13 @@ var StyledFlexWrapper = /*#__PURE__*/ styled("div")({
 		"s12krdms-17": [_exp16()]
 	}
 });
+/**
+* The layout workhorse — a `display: flex` div with every flex and sizing knob
+* as a prop. Compose UI out of these plus whitespace rather than decorating.
+*
+* Sizing props respect an explicit `0`, so `minWidth={0}` works as the standard
+* fix for letting a flex child shrink enough for nested text to ellipsize.
+*/
 var FlexWrapper = forwardRef(({ children, direction, alignItems, justifyContent, wrap, gap, grow, shrink, basis, width, height, minWidth, maxWidth, minHeight, maxHeight, fillWidth = false, fillHeight = false, overflow, padding, margin, onClick, onMouseDown, onMouseEnter, onMouseLeave, onScroll }, ref) => {
 	return /* @__PURE__ */ jsx(StyledFlexWrapper, {
 		ref,

package/dist/containers/GridWrapper.d.ts

@@ -1,16 +1,19 @@
 import type { PropsWithChildren } from "react";
+/** Block-axis alignment of each item inside its own grid area (`align-items`). */
 export declare enum GridAlignItems {
     START = "START",
     CENTER = "CENTER",
     END = "END",
     STRETCH = "STRETCH"
 }
+/** Inline-axis alignment of each item inside its own grid area (`justify-items`). */
 export declare enum GridJustifyItems {
     START = "START",
     CENTER = "CENTER",
     END = "END",
     STRETCH = "STRETCH"
 }
+/** Inline-axis distribution of the whole grid when it's narrower than its container. */
 export declare enum GridJustifyContent {
     START = "START",
     CENTER = "CENTER",
@@ -20,6 +23,7 @@ export declare enum GridJustifyContent {
     SPACE_EVENLY = "SPACE_EVENLY",
     STRETCH = "STRETCH"
 }
+/** Block-axis distribution of the whole grid when it's shorter than its container. */
 export declare enum GridAlignContent {
     START = "START",
     CENTER = "CENTER",
@@ -29,92 +33,47 @@ export declare enum GridAlignContent {
     SPACE_EVENLY = "SPACE_EVENLY",
     STRETCH = "STRETCH"
 }
-interface GridWrapperProps {
-    /**
-     * Number of columns in the grid, or a custom grid-template-columns value
-     * - number: Creates that many equal-width columns using repeat(n, 1fr)
-     * - string: Used directly as grid-template-columns value (e.g., "200px 1fr 1fr")
-     */
+export interface GridWrapperProps {
+    /** A number becomes `repeat(n, 1fr)`; a string is used as-is ("200px 1fr"). @default 1 */
     columns?: number | string;
-    /**
-     * Number of rows in the grid, or a custom grid-template-rows value
-     * - number: Creates that many equal-height rows using repeat(n, 1fr)
-     * - string: Used directly as grid-template-rows value
-     */
+    /** A number becomes `repeat(n, 1fr)`; a string is used as-is. @default "auto" */
     rows?: number | string;
-    /**
-     * Gap between grid items (both row and column gap)
-     * Can be a number (pixels) or string (e.g., "1rem")
-     */
+    /** Space between items on both axes. A number is px. */
     gap?: number | string;
-    /**
-     * Gap between rows only
-     */
+    /** Overrides `gap` on the row axis only. */
     rowGap?: number | string;
-    /**
-     * Gap between columns only
-     */
+    /** Overrides `gap` on the column axis only. */
     columnGap?: number | string;
-    /**
-     * Aligns grid items along the block (column) axis within their grid area
-     */
+    /** @default GridAlignItems.STRETCH */
     alignItems?: GridAlignItems;
-    /**
-     * Aligns grid items along the inline (row) axis within their grid area
-     */
+    /** @default GridJustifyItems.STRETCH */
     justifyItems?: GridJustifyItems;
-    /**
-     * Aligns the grid along the block (column) axis when grid is smaller than container
-     */
+    /** @default GridAlignContent.START */
     alignContent?: GridAlignContent;
-    /**
-     * Aligns the grid along the inline (row) axis when grid is smaller than container
-     */
+    /** @default GridJustifyContent.START */
     justifyContent?: GridJustifyContent;
-    /**
-     * Sets the width of the grid container
-     */
+    /** A number is px. @default "auto" */
     width?: number | string;
-    /**
-     * Sets the height of the grid container
-     */
+    /** A number is px. @default "auto" */
     height?: number | string;
-    /**
-     * Sets the minimum width of the grid container
-     */
     minWidth?: number | string;
-    /**
-     * Sets the maximum width of the grid container
-     */
     maxWidth?: number | string;
-    /**
-     * Sets the minimum height of the grid container
-     */
     minHeight?: number | string;
-    /**
-     * Sets the maximum height of the grid container
-     */
     maxHeight?: number | string;
-    /**
-     * When true, the container will fill its parent's width (width: 100%)
-     */
+    /** `width: 100%`. Takes precedence over `width`. */
     fillWidth?: boolean;
-    /**
-     * When true, the container will fill its parent's height (height: 100%)
-     */
+    /** `height: 100%`. Takes precedence over `height`. */
     fillHeight?: boolean;
-    /**
-     * Sets the padding inside the container
-     */
+    /** Inner spacing. A number is px. */
     padding?: number | string;
-    /**
-     * Sets the margin outside the container
-     */
+    /** Escape hatch. DLS spaces with `gap` and `padding` — reach for those first. */
     margin?: number | string;
-    /**
-     * Controls overflow behavior
-     */
+    /** @default "visible" */
     overflow?: React.CSSProperties["overflow"];
 }
+/**
+ * A `display: grid` container. Use it when children need to line up across both
+ * axes; for a single row or column `FlexWrapper` is the lighter choice.
+ */
 declare const GridWrapper: ({ children, columns, rows, gap, rowGap, columnGap, alignItems, justifyItems, alignContent, justifyContent, width, height, minWidth, maxWidth, minHeight, maxHeight, fillWidth, fillHeight, padding, margin, overflow, }: PropsWithChildren<GridWrapperProps>) => import("react").JSX.Element;
 export default GridWrapper;

package/dist/containers/GridWrapper.js

@@ -3,6 +3,7 @@ import { getCssSizeValue } from "../utils/linaria.js";
 import { styled } from "@linaria/react";
 import { jsx } from "react/jsx-runtime";
 //#region src/containers/GridWrapper.tsx
+/** Block-axis alignment of each item inside its own grid area (`align-items`). */
 var GridAlignItems = /* @__PURE__ */ function(GridAlignItems) {
 	GridAlignItems["START"] = "START";
 	GridAlignItems["CENTER"] = "CENTER";
@@ -10,6 +11,7 @@ var GridAlignItems = /* @__PURE__ */ function(GridAlignItems) {
 	GridAlignItems["STRETCH"] = "STRETCH";
 	return GridAlignItems;
 }({});
+/** Inline-axis alignment of each item inside its own grid area (`justify-items`). */
 var GridJustifyItems = /* @__PURE__ */ function(GridJustifyItems) {
 	GridJustifyItems["START"] = "START";
 	GridJustifyItems["CENTER"] = "CENTER";
@@ -17,6 +19,7 @@ var GridJustifyItems = /* @__PURE__ */ function(GridJustifyItems) {
 	GridJustifyItems["STRETCH"] = "STRETCH";
 	return GridJustifyItems;
 }({});
+/** Inline-axis distribution of the whole grid when it's narrower than its container. */
 var GridJustifyContent = /* @__PURE__ */ function(GridJustifyContent) {
 	GridJustifyContent["START"] = "START";
 	GridJustifyContent["CENTER"] = "CENTER";
@@ -27,6 +30,7 @@ var GridJustifyContent = /* @__PURE__ */ function(GridJustifyContent) {
 	GridJustifyContent["STRETCH"] = "STRETCH";
 	return GridJustifyContent;
 }({});
+/** Block-axis distribution of the whole grid when it's shorter than its container. */
 var GridAlignContent = /* @__PURE__ */ function(GridAlignContent) {
 	GridAlignContent["START"] = "START";
 	GridAlignContent["CENTER"] = "CENTER";
@@ -88,6 +92,10 @@ var StyledGridWrapper = /*#__PURE__*/ styled("div")({
 		"s40bxfr-17": [_exp16()]
 	}
 });
+/**
+* A `display: grid` container. Use it when children need to line up across both
+* axes; for a single row or column `FlexWrapper` is the lighter choice.
+*/
 var GridWrapper = ({ children, columns, rows, gap, rowGap, columnGap, alignItems, justifyItems, alignContent, justifyContent, width, height, minWidth, maxWidth, minHeight, maxHeight, fillWidth = false, fillHeight = false, padding, margin, overflow }) => {
 	return /* @__PURE__ */ jsx(StyledGridWrapper, {
 		columns,