@scalewing/react 1.4.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @scalewing/react
 
+## 1.6.0
+
+### Minor Changes
+
+- a42f7dd: `Dialog` is now fully controlled by `open`. Escape, a platform close request,
+  a backdrop press and a `<form method="dialog">` submit (the form's `method` or
+  the submitter's `formmethod`) are each prevented and ask `onClose()`; none of
+  them closes the native `<dialog>` itself. A dialog whose consumer keeps `open`
+  true (for example while a form is saving) stays shown, including on a repeated
+  Escape in Chromium. A consumer `onKeyDown`, `onCancel`, `onSubmit` or
+  `onPointerDown` that prevents the event vetoes that request (`onPointerDown`
+  used to be dropped). Escape in a search field that holds text clears the field
+  first, and a descendant's own `cancel` (a dismissed file picker) is not a close
+  request. A backdrop press counts only on the
+  dialog element itself, so a nested dialog's backdrop or an overflowing popover
+  does not close the outer dialog. See `docs/requests/teisoro-dialog-close.md`.
+
+  `Tooltip` now prevents the Escape it uses while it is visible, so one Escape
+  hides a tooltip inside a `Dialog` without also closing the dialog.
+
+  `ActionMenu` returns focus to its trigger before running a selected command,
+  as Escape already did, so a `Dialog` opened from a command returns focus to
+  the trigger when it closes (`docs/requests/teisoro-action-menu.md`).
+
+  Behavior change: `Dialog` no longer calls `onClose` when `open` turns false
+  (it used to echo the native `close` event). Migration: if you ran cleanup in
+  `onClose` after setting `open` to false yourself, run it where you set `open`
+  to false.
+
+  No prop or type is added or removed.
+
+## 1.5.0
+
+### Minor Changes
+
+- 7b51094: Add `columnSpan` to `Box` and every component built on it (`Stack`, `Inline`,
+  `Card`, `Grid`, …), so a direct child of a `Grid` can cover 1, 2, 3, 4 or 6
+  columns (see `docs/requests/teisoro-grid-column-span.md`). Three columns with a
+  two-column child give a two-to-one page:
+
+  ```tsx
+  <Grid columns={3} columnsBelow={{ md: 1 }} gap={4}>
+    <Stack columnSpan={2} gap={4}>
+      {form}
+    </Stack>
+    <Card variant="outlined">{panel}</Card>
+  </Grid>
+  ```
+
+  The generated `sw-grid-span-{1,2,3,4,6}` classes are capped at the
+  columns the grid has at the current width, so a span never adds an implicit
+  column and `columnsBelow` still stacks the page on a phone. A span outside the
+  catalog throws a `RangeError`. New exported types: `GridColumnSpan`,
+  `ColumnSpanProps`. Additive; no existing class or prop changes.
+
 ## 1.4.1
 
 ### Patch Changes

package/README.md

@@ -48,7 +48,9 @@ Import the CSS once at the application entry. Do not copy it into your source tr
 
 `Field` supports optional `description`, `error`, and `required` on one native input, select, or textarea child. It preserves an existing `aria-describedby`, appends a stable message ID, and replaces the hint with an alert when an error is supplied. `error` sets `aria-invalid` and token-owned invalid styling. The consumer owns validation and localized messages.
 
-`ActionMenu` opens independent commands from a labelled button. Provide localized command labels and callbacks; use `disabled` for unavailable commands and `destructive` for a dangerous command's presentation. Escape returns focus to the trigger, and outside interaction dismisses the menu.
+`ActionMenu` opens independent commands from a labelled button. Provide localized command labels and callbacks; use `disabled` for unavailable commands and `destructive` for a dangerous command's presentation. Escape and choosing a command both return focus to the trigger (before the command runs, so a `Dialog` it opens hands focus back to the trigger on close), and outside interaction dismisses the menu.
+
+`Dialog` is a modal `<dialog>` controlled by `open`. Escape, a backdrop press, a platform close request, and a `<form method="dialog">` submit (or a submitter with `formmethod="dialog"`) are each prevented and call `onClose`; none of them closes the dialog itself. A consumer `onKeyDown`, `onCancel`, `onSubmit` or `onPointerDown` that prevents the event vetoes that request. Escape in a search field that holds text clears the field first, and a descendant's own `cancel` (a dismissed file picker) is not a close request. Set `open` to false to close it, or keep it true (for example while a form is saving) and it stays shown. `onClose` is not called when `open` turns false, and it is required: a dialog that must not be dismissed passes a callback that keeps `open` true.
 
 `Switch` is a controlled on/off input. It keeps native checkbox keyboard behavior and exposes switch semantics. Provide the current `checked` value and update it in `onCheckedChange`.
 
@@ -68,7 +70,20 @@ Import the CSS once at the application entry. Do not copy it into your source tr
 
 `Text` takes an optional `align` (`start`, `center`, `end`) mapped to generated `sw-text-align-*` classes, for a heading that must stay centered when it wraps.
 
-`Grid` places children in one to four equal-width columns with a token `gap` step. `columnsBelow={{ md: 2 }}` drops to fewer columns below the `md` breakpoint so tiles and stat cards stay readable on a phone. It accepts every `Box` prop.
+`Grid` places children in one to four (or six) equal-width columns with a token `gap` step. `columnsBelow={{ md: 2 }}` drops to fewer columns below the `md` breakpoint so tiles and stat cards stay readable on a phone. It accepts every `Box` prop.
+
+Every `Box`-based component (`Box`, `Stack`, `Inline`, `Card`, `Grid`, …) takes `columnSpan` (1, 2, 3, 4 or 6) to cover several columns of the `Grid` it sits in directly, through the generated `sw-grid-span-*` classes. A span is capped at the columns the grid has at the current width, so it never adds an implicit column, and `columnsBelow` still decides the phone layout. A form about twice the width of a side panel, stacking below `md`:
+
+```tsx
+<Grid columns={3} columnsBelow={{ md: 1 }} gap={4}>
+  <Stack columnSpan={2} gap={4}>
+    {form}
+  </Stack>
+  <Card variant="outlined">{panel}</Card>
+</Grid>
+```
+
+Values outside the catalog throw a `RangeError`. There is no per-breakpoint span and no arbitrary column template.
 
 `DenominationGrid` shows integer counts per unit across a fixed set of columns. The `strip` layout is a captioned table: each row has a toned label with an icon slot, muted zero cells, optional signed deltas toned by sign, and an optional consumer-formatted `total` that moves under the label on a phone. The `tiles` layout stacks the column label, the count, and an optional `subtotal` string per column. The primitive does no arithmetic and no currency formatting; tones reuse the Badge vocabulary. Invalid columns, rows, or cells throw.
 

package/dist/column-span-classes.d.ts

@@ -0,0 +1,9 @@
+import { type GridColumnSpan } from './css/css-grid-span.js';
+export type ColumnSpanProps = {
+    /**
+     * Columns this box spans when it is a direct child of a `Grid`, capped at
+     * the grid's column count at the current width.
+     */
+    columnSpan?: GridColumnSpan;
+};
+export declare function columnSpanClassNames({ columnSpan, }: ColumnSpanProps): string[];

package/dist/column-span-classes.js

@@ -0,0 +1,8 @@
+import { gridSpanClass } from './css/css-grid-span.js';
+import { assertGridCount } from './grid-counts.js';
+export function columnSpanClassNames({ columnSpan, }) {
+    if (columnSpan === undefined)
+        return [];
+    assertGridCount('columnSpan', columnSpan);
+    return [gridSpanClass(columnSpan)];
+}

package/dist/components/ActionMenu.js

@@ -130,7 +130,9 @@ export function ActionMenu({ label, items, trigger, disabled = false, }) {
     function select(item) {
         if (!openRef.current || !enabled || item.disabled)
             return;
-        close();
+        // Focus leaves the hidden item first, so a dialog the command opens
+        // records the trigger as its opener and returns focus there on close.
+        close(true);
         item.onSelect();
     }
     return (_jsxs("div", { className: "sw-action-menu", ref: rootRef, children: [_jsx("button", { "aria-controls": open ? menuId : undefined, "aria-expanded": open, "aria-haspopup": "menu", "aria-label": label, className: "sw-action-menu-trigger", disabled: !enabled, onClick: () => (open ? close(true) : openMenu()), onKeyDown: onTriggerKeyDown, ref: triggerRef, type: "button", children: trigger ?? label }), _jsx("div", { "aria-label": label, className: "sw-action-menu-list", hidden: !open, id: menuId, onKeyDown: onMenuKeyDown, ref: menuRef, role: "menu", children: items.map((item, index) => (_jsxs("button", { className: cx('sw-action-menu-item', item.destructive && 'sw-action-menu-item-danger'), disabled: item.disabled, onClick: () => select(item), onFocus: () => setFocusIndex(index), onKeyDown: (event) => {

package/dist/components/Box.d.ts

@@ -1,15 +1,16 @@
 import { type RadiusStep, type SemanticColorKey } from '@scalewing/tokens';
 import { type AnchorHTMLAttributes, type HTMLAttributes } from 'react';
+import { type ColumnSpanProps } from '../column-span-classes.js';
 import { type SpacingProps } from '../spacing-classes.js';
 import { type VisibilityProps } from '../visibility-classes.js';
 export type BoxElement = 'div' | 'section' | 'article' | 'header' | 'footer' | 'main' | 'nav' | 'aside' | 'span' | 'a' | 'label';
-export type BoxProps = SpacingProps & VisibilityProps & HTMLAttributes<HTMLElement> & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, 'download' | 'href' | 'rel' | 'target'> & {
+export type BoxProps = SpacingProps & VisibilityProps & ColumnSpanProps & HTMLAttributes<HTMLElement> & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, 'download' | 'href' | 'rel' | 'target'> & {
     as?: BoxElement;
     background?: Extract<SemanticColorKey, 'background' | 'surface'>;
     radius?: RadiusStep;
     border?: boolean;
 };
-export declare const Box: import("react").ForwardRefExoticComponent<SpacingProps & VisibilityProps & HTMLAttributes<HTMLElement> & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "download" | "href" | "rel" | "target"> & {
+export declare const Box: import("react").ForwardRefExoticComponent<SpacingProps & VisibilityProps & ColumnSpanProps & HTMLAttributes<HTMLElement> & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "download" | "href" | "rel" | "target"> & {
     as?: BoxElement;
     background?: Extract<SemanticColorKey, "background" | "surface">;
     radius?: RadiusStep;

package/dist/components/Box.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, } from 'react';
 import { cx } from '../class-names.js';
+import { columnSpanClassNames, } from '../column-span-classes.js';
 import { spacingClassNames } from '../spacing-classes.js';
 import { visibilityClassNames, } from '../visibility-classes.js';
-export const Box = forwardRef(function Box({ as = 'div', background, border, className, hideBelow, hideFrom, padding, paddingBottom, paddingLeft, paddingRight, paddingTop, paddingX, paddingY, radius, style, ...rest }, ref) {
+export const Box = forwardRef(function Box({ as = 'div', background, border, className, columnSpan, hideBelow, hideFrom, padding, paddingBottom, paddingLeft, paddingRight, paddingTop, paddingX, paddingY, radius, style, ...rest }, ref) {
     const Component = as;
     return (_jsx(Component, { ref: ref, className: cx(...spacingClassNames({
             padding,
@@ -13,7 +14,7 @@ export const Box = forwardRef(function Box({ as = 'div', background, border, cla
             paddingTop,
             paddingX,
             paddingY,
-        }), ...visibilityClassNames({ hideBelow, hideFrom }), className), style: {
+        }), ...visibilityClassNames({ hideBelow, hideFrom }), ...columnSpanClassNames({ columnSpan }), className), style: {
             backgroundColor: background
                 ? `var(--sw-color-${background})`
                 : undefined,

package/dist/components/Dialog.d.ts

@@ -5,10 +5,20 @@ import { type DialogHTMLAttributes, type ReactNode } from 'react';
  */
 export type DialogSize = 'md' | 'lg';
 export type DialogProps = Omit<DialogHTMLAttributes<HTMLDialogElement>, 'onClose' | 'open' | 'title' | 'children'> & {
+    /** Whether the dialog is shown. The element follows it and nothing else. */
     open: boolean;
+    /**
+     * Asked on every close request: Escape, a backdrop press, a platform close
+     * request, or a `<form method="dialog">` submit. Each is prevented, so the
+     * element does not close itself. Set `open` to false to close; keep it true
+     * (for example while saving) and the dialog stays shown. It is not called
+     * when `open` turns false. A consumer `onKeyDown`, `onCancel`, `onSubmit`
+     * or `onPointerDown` that prevents the event vetoes that request. It is required: a dialog
+     * that must not be dismissed passes a callback that keeps `open` true.
+     */
     onClose: () => void;
     size?: DialogSize;
     title: string;
     children: ReactNode;
 };
-export declare function Dialog({ children, className, onClose, open, size, title, ...rest }: DialogProps): import("react").JSX.Element;
+export declare function Dialog({ children, className, onCancel, onClose, onKeyDown, onPointerDown, onSubmit, open, size, title, ...rest }: DialogProps): import("react").JSX.Element;

package/dist/components/Dialog.js

@@ -1,36 +1,20 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useRef, } from 'react';
+import { useId } from 'react';
 import { cx } from '../class-names.js';
 import { spacingClassNames } from '../spacing-classes.js';
+import { useDialogCloseRequests } from './dialog-close-requests.js';
 import { Stack } from './Stack.js';
 import { Text } from './Text.js';
-export function Dialog({ children, className, onClose, open, size = 'md', title, ...rest }) {
-    const nodeRef = useRef(null);
+export function Dialog({ children, className, onCancel, onClose, onKeyDown, onPointerDown, onSubmit, open, size = 'md', title, ...rest }) {
     const titleId = useId();
-    useEffect(() => {
-        const node = nodeRef.current;
-        if (!node) {
-            return;
-        }
-        if (open) {
-            if (!node.open) {
-                node.showModal();
-            }
-            return;
-        }
-        if (node.open) {
-            node.close();
-        }
-    }, [open]);
-    return (_jsx("dialog", { ...rest, ref: nodeRef, "aria-labelledby": titleId, className: cx('sw-dialog', size === 'lg' && 'sw-dialog-lg', ...spacingClassNames({ padding: 5 }), className), onClose: onClose, onPointerDown: (event) => {
-            const rect = event.currentTarget.getBoundingClientRect();
-            const inside = event.clientX >= rect.left &&
-                event.clientX <= rect.right &&
-                event.clientY >= rect.top &&
-                event.clientY <= rect.bottom;
-            if (!inside) {
-                onClose();
-            }
-        }, children: _jsxs(Stack, { gap: 4, children: [_jsx(Text, { id: titleId, variant: "title", children: title }), children] }) }));
+    const { nodeRef, handlers } = useDialogCloseRequests({
+        open,
+        onClose,
+        onCancel,
+        onKeyDown,
+        onPointerDown,
+        onSubmit,
+    });
+    return (_jsx("dialog", { ...rest, ref: nodeRef, "aria-labelledby": titleId, className: cx('sw-dialog', size === 'lg' && 'sw-dialog-lg', ...spacingClassNames({ padding: 5 }), className), ...handlers, children: _jsxs(Stack, { gap: 4, children: [_jsx(Text, { id: titleId, variant: "title", children: title }), children] }) }));
 }

package/dist/components/Grid.js

@@ -1,20 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../class-names.js';
 import { breakpoints } from '../css/breakpoints.js';
-import { gridColumnCounts, gridColumnsBelowClass, gridColumnsClass, } from '../css/css-grid.js';
+import { gridColumnsBelowClass, gridColumnsClass, } from '../css/css-grid.js';
 import { spacingClass } from '../css/spacing-classes.js';
+import { assertGridCount } from '../grid-counts.js';
 import { Box } from './Box.js';
-function assertColumns(columns) {
-    if (!gridColumnCounts.includes(columns))
-        throw new RangeError(`columns must be one of ${gridColumnCounts.join(', ')}`);
-}
 export function Grid({ className, columns = 1, columnsBelow, gap = 0, ...rest }) {
-    assertColumns(columns);
+    assertGridCount('columns', columns);
     const belowClasses = breakpoints.flatMap((breakpoint) => {
         const count = columnsBelow?.[breakpoint];
         if (count === undefined)
             return [];
-        assertColumns(count);
+        assertGridCount('columnsBelow', count);
         return [gridColumnsBelowClass(breakpoint, count)];
     });
     return (_jsx(Box, { className: cx('sw-grid', gridColumnsClass(columns), ...belowClasses, spacingClass('gap', 'all', gap), className), ...rest }));

package/dist/components/Tooltip.js

@@ -25,8 +25,12 @@ export function Tooltip({ content, trigger }) {
             if (!event.currentTarget.contains(event.relatedTarget))
                 setOpen(false);
         }, onFocusCapture: () => setOpen(true), onKeyDownCapture: (event) => {
-            if (event.key === 'Escape')
-                setOpen(false);
+            // Escape hides a visible tooltip and nothing else, so a surrounding
+            // Dialog does not also close. A hidden tooltip leaves Escape alone.
+            if (event.key !== 'Escape' || !open)
+                return;
+            event.preventDefault();
+            setOpen(false);
         }, onPointerEnter: (event) => {
             if (event.pointerType === 'mouse' || event.pointerType === 'pen')
                 setOpen(true);

package/dist/components/dialog-close-requests.d.ts

@@ -0,0 +1,38 @@
+import { type FormEvent, type FormEventHandler, type KeyboardEvent, type KeyboardEventHandler, type PointerEvent, type PointerEventHandler, type ReactEventHandler, type SyntheticEvent } from 'react';
+type CloseRequestOptions = {
+    open: boolean;
+    onClose: () => void;
+    onCancel?: ReactEventHandler<HTMLDialogElement>;
+    onKeyDown?: KeyboardEventHandler<HTMLDialogElement>;
+    onPointerDown?: PointerEventHandler<HTMLDialogElement>;
+    onSubmit?: FormEventHandler<HTMLDialogElement>;
+};
+/**
+ * Keeps a native modal `<dialog>` controlled by `open`.
+ *
+ * Every close request (Escape, a platform close request such as Android back,
+ * a backdrop press, a `<form method="dialog">` submit) is prevented and
+ * becomes one `onClose()` call. The caller answers by setting `open` to
+ * false, or keeps it true (for example while a form is saving) and the
+ * dialog stays shown without being closed and shown again.
+ *
+ * Escape is taken at `keydown`, before the browser turns it into a close
+ * request: Chromium only lets a page cancel one close request per user
+ * activation, so a second Escape would otherwise close the element even
+ * though its `cancel` event was prevented. Two closes cannot be prevented: a
+ * repeated platform close request whose `cancel` is not cancelable, and an
+ * Escape that never reaches the dialog (focus fell to the body). Those are
+ * reconciled with `open` after the caller's update, which shows the dialog
+ * again only if `open` is still true.
+ */
+export declare function useDialogCloseRequests({ open, onClose, onCancel, onKeyDown, onPointerDown, onSubmit, }: CloseRequestOptions): {
+    nodeRef: import("react").RefObject<HTMLDialogElement | null>;
+    handlers: {
+        onCancel: (event: SyntheticEvent<HTMLDialogElement>) => void;
+        onClose: (event: SyntheticEvent<HTMLDialogElement>) => void;
+        onKeyDown: (event: KeyboardEvent<HTMLDialogElement>) => void;
+        onPointerDown: (event: PointerEvent<HTMLDialogElement>) => void;
+        onSubmit: (event: FormEvent<HTMLDialogElement>) => void;
+    };
+};
+export {};

package/dist/components/dialog-close-requests.js

@@ -0,0 +1,141 @@
+import { useEffect, useRef, useState, } from 'react';
+/**
+ * A press on the backdrop: the target is the dialog element itself (not a
+ * child, a nested dialog's backdrop, or a popover that overflows the box)
+ * and the point lies outside the dialog's box.
+ */
+function isBackdropPress(event) {
+    if (event.target !== event.currentTarget)
+        return false;
+    const rect = event.currentTarget.getBoundingClientRect();
+    return (event.clientX < rect.left ||
+        event.clientX > rect.right ||
+        event.clientY < rect.top ||
+        event.clientY > rect.bottom);
+}
+/** Escape typed into an input method (Safari reports it as keyCode 229). */
+function isComposing(event) {
+    return event.nativeEvent.isComposing || event.keyCode === 229;
+}
+/**
+ * Escape in a search field that holds text clears the field (the browser's
+ * own default action) and does not close the dialog.
+ */
+function clearsSearchField(event) {
+    const target = event.target;
+    return (target instanceof HTMLInputElement &&
+        target.type === 'search' &&
+        target.value !== '');
+}
+/**
+ * A submit that the browser would turn into closing this dialog: the
+ * submitter's `formmethod`, or else the form's `method`, is `dialog`, and the
+ * form belongs to this dialog rather than to a nested one.
+ */
+function isDialogSubmit(event) {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement))
+        return false;
+    if (form.closest('dialog') !== event.currentTarget)
+        return false;
+    const submitter = event.nativeEvent.submitter;
+    const method = submitter?.getAttribute('formmethod') ?? form.getAttribute('method');
+    return method?.trim().toLowerCase() === 'dialog';
+}
+/**
+ * Keeps a native modal `<dialog>` controlled by `open`.
+ *
+ * Every close request (Escape, a platform close request such as Android back,
+ * a backdrop press, a `<form method="dialog">` submit) is prevented and
+ * becomes one `onClose()` call. The caller answers by setting `open` to
+ * false, or keeps it true (for example while a form is saving) and the
+ * dialog stays shown without being closed and shown again.
+ *
+ * Escape is taken at `keydown`, before the browser turns it into a close
+ * request: Chromium only lets a page cancel one close request per user
+ * activation, so a second Escape would otherwise close the element even
+ * though its `cancel` event was prevented. Two closes cannot be prevented: a
+ * repeated platform close request whose `cancel` is not cancelable, and an
+ * Escape that never reaches the dialog (focus fell to the body). Those are
+ * reconciled with `open` after the caller's update, which shows the dialog
+ * again only if `open` is still true.
+ */
+export function useDialogCloseRequests({ open, onClose, onCancel, onKeyDown, onPointerDown, onSubmit, }) {
+    const nodeRef = useRef(null);
+    const openRef = useRef(open);
+    // The last `cancel` could not be prevented, so its `close` follows and
+    // `onClose` has already been asked.
+    const forcedCloseRef = useRef(false);
+    const [browserCloses, setBrowserCloses] = useState(0);
+    useEffect(() => {
+        openRef.current = open;
+        const node = nodeRef.current;
+        if (!node)
+            return;
+        if (open && !node.open)
+            node.showModal();
+        if (!open && node.open)
+            node.close();
+    }, [open, browserCloses]);
+    function handleKeyDown(event) {
+        onKeyDown?.(event);
+        // A nested control (a menu, a listbox, a tooltip, an inner dialog) or the
+        // consumer that used Escape prevents it.
+        if (event.key !== 'Escape' ||
+            event.defaultPrevented ||
+            isComposing(event) ||
+            clearsSearchField(event)) {
+            return;
+        }
+        event.preventDefault();
+        onClose();
+    }
+    function handleCancel(event) {
+        onCancel?.(event);
+        // A descendant's own `cancel` (a file picker dismissed from an
+        // `<input type="file">` bubbles one) is not a close request for the dialog.
+        if (event.target !== event.currentTarget)
+            return;
+        const vetoed = event.defaultPrevented;
+        event.preventDefault();
+        if (!event.cancelable)
+            forcedCloseRef.current = true;
+        if (!vetoed)
+            onClose();
+    }
+    function handleSubmit(event) {
+        onSubmit?.(event);
+        if (event.defaultPrevented || !isDialogSubmit(event))
+            return;
+        event.preventDefault();
+        onClose();
+    }
+    function handleClose(event) {
+        // A nested dialog's `close` is not this dialog's.
+        if (event.target !== event.currentTarget)
+            return;
+        const forced = forcedCloseRef.current;
+        forcedCloseRef.current = false;
+        // Closed by the `open` prop, or a stale event after it opened again.
+        if (!openRef.current || nodeRef.current?.open)
+            return;
+        if (!forced)
+            onClose();
+        setBrowserCloses((count) => count + 1);
+    }
+    function handlePointerDown(event) {
+        onPointerDown?.(event);
+        if (!event.defaultPrevented && isBackdropPress(event))
+            onClose();
+    }
+    return {
+        nodeRef,
+        handlers: {
+            onCancel: handleCancel,
+            onClose: handleClose,
+            onKeyDown: handleKeyDown,
+            onPointerDown: handlePointerDown,
+            onSubmit: handleSubmit,
+        },
+    };
+}

package/dist/css/css-components.js

@@ -22,6 +22,7 @@ import { cssTabsClasses } from './css-tabs.js';
 import { cssResponsiveClasses } from './css-responsive.js';
 import { cssFilterChipsClasses } from './css-filter-chips.js';
 import { cssGridClasses } from './css-grid.js';
+import { cssGridSpanClasses } from './css-grid-span.js';
 import { cssDenominationGridClasses } from './css-denomination-grid.js';
 import { cssFieldClasses } from './css-field.js';
 import { cssToastClasses } from './css-toast.js';
@@ -149,6 +150,7 @@ ${cssTabsClasses()}
 ${cssFilterChipsClasses()}
 
 ${cssGridClasses()}
+${cssGridSpanClasses()}
 ${cssDenominationGridClasses()}
 
 ${cssFieldClasses()}

package/dist/css/css-grid-span.d.ts

@@ -0,0 +1,7 @@
+import { type GridColumns } from './css-grid.js';
+/** A child spans one of the same bounded counts a `Grid` can have. */
+export type GridColumnSpan = GridColumns;
+export declare const gridColumnSpans: readonly [1, 2, 3, 4, 6];
+export declare function gridSpanClass(span: GridColumnSpan): string;
+export declare function cssGridSpanClasses(): string;
+export declare function gridSpanClassCatalog(): string[];

package/dist/css/css-grid-span.js

@@ -0,0 +1,35 @@
+import { breakpointQuery, breakpoints } from './breakpoints.js';
+import { gridColumnCounts, gridColumnsBelowClass, gridColumnsClass, } from './css-grid.js';
+export const gridColumnSpans = gridColumnCounts;
+export function gridSpanClass(span) {
+    return `sw-grid-span-${span}`;
+}
+function spanRule(selector, span) {
+    return `${selector} { grid-column: span ${span}; }`;
+}
+/**
+ * Caps a span at the columns its grid has at the current width, so a wide
+ * child never adds an implicit column. `:where()` keeps the cap at one class
+ * of specificity; source order lets it override the plain span rule.
+ */
+function capRule(gridClass, columns, span) {
+    return spanRule(`:where(.${gridClass}) > .${gridSpanClass(span)}`, Math.min(span, columns));
+}
+function widerSpans(columns) {
+    return gridColumnSpans.filter((span) => span > columns);
+}
+export function cssGridSpanClasses() {
+    const spans = gridColumnSpans.map((span) => spanRule(`.${gridSpanClass(span)}`, span));
+    const caps = gridColumnCounts.flatMap((columns) => widerSpans(columns).map((span) => capRule(gridColumnsClass(columns), columns, span)));
+    // Below a breakpoint every span wider than one is restated for the phone
+    // column count, which also undoes a desktop cap when that count is larger.
+    const below = breakpoints.map((breakpoint) => `@media ${breakpointQuery('below', breakpoint)} {
+${gridColumnCounts
+        .flatMap((columns) => widerSpans(1).map((span) => `  ${capRule(gridColumnsBelowClass(breakpoint, columns), columns, span)}`))
+        .join('\n')}
+}`);
+    return [...spans, ...caps, ...below].join('\n');
+}
+export function gridSpanClassCatalog() {
+    return gridColumnSpans.map((span) => gridSpanClass(span));
+}

package/dist/css/stylesheet.js

@@ -14,6 +14,7 @@ import { tabsClassCatalog } from './css-tabs.js';
 import { responsiveClassCatalog } from './css-responsive.js';
 import { filterChipsClassCatalog } from './css-filter-chips.js';
 import { gridClassCatalog } from './css-grid.js';
+import { gridSpanClassCatalog } from './css-grid-span.js';
 import { denominationGridClassCatalog } from './css-denomination-grid.js';
 import { fieldClassCatalog } from './css-field.js';
 import { cssComponentClasses } from './css-components.js';
@@ -63,6 +64,7 @@ export function utilityClassCatalog() {
         ...tabsClassCatalog(),
         ...filterChipsClassCatalog(),
         ...gridClassCatalog(),
+        ...gridSpanClassCatalog(),
         ...denominationGridClassCatalog(),
         ...fieldClassCatalog(),
         ...splitClassCatalog(),

package/dist/grid-counts.d.ts

@@ -0,0 +1,3 @@
+import { type GridColumns } from './css/css-grid.js';
+/** Fails closed on a column count or span outside the bounded catalog. */
+export declare function assertGridCount(prop: string, value: number): asserts value is GridColumns;

package/dist/grid-counts.js

@@ -0,0 +1,6 @@
+import { gridColumnCounts } from './css/css-grid.js';
+/** Fails closed on a column count or span outside the bounded catalog. */
+export function assertGridCount(prop, value) {
+    if (!gridColumnCounts.includes(value))
+        throw new RangeError(`${prop} must be one of ${gridColumnCounts.join(', ')}`);
+}

package/dist/index.d.ts

@@ -38,6 +38,8 @@ export { Separator } from './components/Separator.js';
 export type { SeparatorOrientation, SeparatorProps, } from './components/Separator.js';
 export { Grid } from './components/Grid.js';
 export type { GridColumns, GridProps } from './components/Grid.js';
+export type { GridColumnSpan } from './css/css-grid-span.js';
+export type { ColumnSpanProps } from './column-span-classes.js';
 export { DenominationGrid } from './components/DenominationGrid.js';
 export type { DenominationGridColumn, DenominationGridLayout, DenominationGridProps, DenominationGridRow, DenominationGridTone, } from './components/DenominationGrid.js';
 export { FilterChips } from './components/FilterChips.js';

package/dist/styles.css

@@ -2166,6 +2166,43 @@ body {
 .sw-grid-cols-below-md-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
 .sw-grid-cols-below-md-6 { grid-template-columns: repeat(6, minmax(0, 1fr)); }
 }
+.sw-grid-span-1 { grid-column: span 1; }
+.sw-grid-span-2 { grid-column: span 2; }
+.sw-grid-span-3 { grid-column: span 3; }
+.sw-grid-span-4 { grid-column: span 4; }
+.sw-grid-span-6 { grid-column: span 6; }
+:where(.sw-grid-cols-1) > .sw-grid-span-2 { grid-column: span 1; }
+:where(.sw-grid-cols-1) > .sw-grid-span-3 { grid-column: span 1; }
+:where(.sw-grid-cols-1) > .sw-grid-span-4 { grid-column: span 1; }
+:where(.sw-grid-cols-1) > .sw-grid-span-6 { grid-column: span 1; }
+:where(.sw-grid-cols-2) > .sw-grid-span-3 { grid-column: span 2; }
+:where(.sw-grid-cols-2) > .sw-grid-span-4 { grid-column: span 2; }
+:where(.sw-grid-cols-2) > .sw-grid-span-6 { grid-column: span 2; }
+:where(.sw-grid-cols-3) > .sw-grid-span-4 { grid-column: span 3; }
+:where(.sw-grid-cols-3) > .sw-grid-span-6 { grid-column: span 3; }
+:where(.sw-grid-cols-4) > .sw-grid-span-6 { grid-column: span 4; }
+@media not all and (min-width: 48rem) {
+  :where(.sw-grid-cols-below-md-1) > .sw-grid-span-2 { grid-column: span 1; }
+  :where(.sw-grid-cols-below-md-1) > .sw-grid-span-3 { grid-column: span 1; }
+  :where(.sw-grid-cols-below-md-1) > .sw-grid-span-4 { grid-column: span 1; }
+  :where(.sw-grid-cols-below-md-1) > .sw-grid-span-6 { grid-column: span 1; }
+  :where(.sw-grid-cols-below-md-2) > .sw-grid-span-2 { grid-column: span 2; }
+  :where(.sw-grid-cols-below-md-2) > .sw-grid-span-3 { grid-column: span 2; }
+  :where(.sw-grid-cols-below-md-2) > .sw-grid-span-4 { grid-column: span 2; }
+  :where(.sw-grid-cols-below-md-2) > .sw-grid-span-6 { grid-column: span 2; }
+  :where(.sw-grid-cols-below-md-3) > .sw-grid-span-2 { grid-column: span 2; }
+  :where(.sw-grid-cols-below-md-3) > .sw-grid-span-3 { grid-column: span 3; }
+  :where(.sw-grid-cols-below-md-3) > .sw-grid-span-4 { grid-column: span 3; }
+  :where(.sw-grid-cols-below-md-3) > .sw-grid-span-6 { grid-column: span 3; }
+  :where(.sw-grid-cols-below-md-4) > .sw-grid-span-2 { grid-column: span 2; }
+  :where(.sw-grid-cols-below-md-4) > .sw-grid-span-3 { grid-column: span 3; }
+  :where(.sw-grid-cols-below-md-4) > .sw-grid-span-4 { grid-column: span 4; }
+  :where(.sw-grid-cols-below-md-4) > .sw-grid-span-6 { grid-column: span 4; }
+  :where(.sw-grid-cols-below-md-6) > .sw-grid-span-2 { grid-column: span 2; }
+  :where(.sw-grid-cols-below-md-6) > .sw-grid-span-3 { grid-column: span 3; }
+  :where(.sw-grid-cols-below-md-6) > .sw-grid-span-4 { grid-column: span 4; }
+  :where(.sw-grid-cols-below-md-6) > .sw-grid-span-6 { grid-column: span 6; }
+}
 .sw-denomination-grid {
   color: var(--sw-color-text);
   font-family: var(--sw-font-sans);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",