@scalewing/react 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @scalewing/react
 
+## 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

@@ -68,7 +68,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/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/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/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.5.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",