@homebound/beam 2.417.5 → 2.417.7

package/dist/index.d.cts

@@ -5314,7 +5314,7 @@ declare function applyRowFn<R extends Kinded>(column: GridColumnWithId<R>, row:
 declare const ASC: "ASC";
 declare const DESC: "DESC";
 declare const emptyCell: GridCellContent;
-declare function getFirstOrLastCellCss<R extends Kinded>(style: GridStyle, columnIndex: number, columns: GridColumnWithId<R>[]): Properties;
+declare function getFirstOrLastCellCss<R extends Kinded>(style: GridStyle, columnIndex: number, columns: GridColumnWithId<R>[], colspan?: number): Properties;
 /** A heuristic to detect the result of `React.createElement` / i.e. JSX. */
 declare function isJSX(content: any): boolean;
 declare function getAlignment(column: GridColumnWithId<any>, maybeContent: ReactNode | GridCellContent): GridCellAlignment;
@@ -5392,23 +5392,27 @@ type LabelSuffixStyle = {
 interface GridStyle {
     /** Applied to the base div element. */
     rootCss?: Properties;
-    /** Applied with the owl operator between rows for rendering border lines. */
+    /**
+     * Applied as the base body-row cell styling (commonly used for row separators).
+     * This is applied to body rows broadly (including the last body row); use
+     * `lastRowCellCss`/`lastRowCss` to adjust/cancel any final-row treatment.
+     */
     betweenRowsCss?: Properties;
-    /** Applied on the last row of the table. */
+    /** Applied on the last row of the table, typically to override/cancel `betweenRowsCss`. */
     lastRowCss?: Properties;
     /** Applied on the first row of the table (could be the Header or Totals row). */
     firstRowCss?: Properties;
     /** Applied to every non-header row of the table */
     nonHeaderRowCss?: Properties;
-    /** Applied to the first non-header row, i.e. if you want to cancel out `betweenRowsCss`. */
-    firstNonHeaderRowCss?: Properties;
+    /** Applied to the first body row, i.e. if you want to cancel out `betweenRowsCss`. */
+    firstBodyRowCss?: Properties;
     /** Applied to all cell divs (via a selector off the base div). */
     cellCss?: Properties;
     /**
      * Applied to the header row divs.
      *
      * NOTE `as=virtual`: When using a virtual table with the goal of adding space
-     * between the header and the first row use `firstNonHeaderRowCss` with a
+     * between the header and the first row use `firstBodyRowCss` with a
      * margin-top instead. Using `headerCellCss` will not work since the header
      * rows are wrapper with Chrome rows.
      */
@@ -5423,6 +5427,18 @@ interface GridStyle {
     firstCellCss?: Properties;
     /** Applied to the last cell of all rows, i.e. for table-wide padding or right-side borders. */
     lastCellCss?: Properties;
+    /** Applied to every cell in the first table-head row (expandableHeader/header/totals). */
+    firstRowCellCss?: Properties;
+    /** Applied to the first cell in the first table-head row. */
+    firstRowFirstCellCss?: Properties;
+    /** Applied to the last cell in the first table-head row. */
+    firstRowLastCellCss?: Properties;
+    /** Applied to every cell in the last table-body row. */
+    lastRowCellCss?: Properties;
+    /** Applied to the first cell in the last table-body row. */
+    lastRowFirstCellCss?: Properties;
+    /** Applied to the last cell in the last table-body row. */
+    lastRowLastCellCss?: Properties;
     /** Applied if there is a fallback/overflow message showing. */
     firstRowMessageCss?: Properties;
     /** Applied on hover if a row has a rowLink/onClick set. */
@@ -5510,6 +5526,9 @@ interface RowProps<R extends Kinded> {
     cellHighlight: boolean;
     omitRowHover: boolean;
     hasExpandableHeader: boolean;
+    isFirstHeadRow: boolean;
+    isFirstBodyRow: boolean;
+    isLastBodyRow: boolean;
     resizedWidths: ResizedWidths;
     setResizedWidth: (columnId: string, width: number, columnIndex: number) => void;
     disableColumnResizing: boolean;
@@ -7155,22 +7174,60 @@ interface useResponsiveGridProps {
 /**
  * Returns container styles for a responsive CSS grid.
  *
- * Callers must provide the grid config via `ResponsiveGridContext` (or use the
- * `ResponsiveGrid` component) so that each item can call `useResponsiveGridItem`
- * and apply the returned `gridItemStyles` to achieve container-query-based
- * breakpoint behavior for multi-column spans.
+ * ## Layout algorithm
+ *
+ * The grid uses `auto-fill` columns with a clamped width:
+ *
+ * ```
+ * grid-template-columns: repeat(auto-fill, minmax(max(minColumnWidth, maxColumnWidth), 1fr))
+ * ```
+ *
+ * where `maxColumnWidth = (100% - totalGapWidth) / columns`.
+ *
+ * - The `max(minColumnWidth, maxColumnWidth)` clamp means each column is *at
+ *   least* `minColumnWidth` wide, but when the container is wide enough to fit
+ *   all `columns`, each column grows to fill the space equally.
+ * - `auto-fill` lets the browser drop columns automatically as the container
+ *   shrinks — once there isn't room for the next column at `minColumnWidth`,
+ *   the grid reflows to fewer columns.
+ * - The grid is also a CSS `container` (`container-type: inline-size`) so that
+ *   child items can use `@container` queries to adapt their `grid-column` span
+ *   based on the grid's current width. See `useResponsiveGridItem`.
+ *
+ * ### Trade-offs
+ *
+ * **Pros**
+ * - Fully CSS-driven reflow — no JS resize observers or manual breakpoint
+ *   bookkeeping; the browser handles column count changes natively.
+ * - Container queries keep span adjustments scoped to the grid's own width
+ *   rather than the viewport, so the grid works correctly inside any layout
+ *   (sidebars, split panes, etc.).
+ *
+ * **Cons**
+ * - `auto-fill` can produce an empty trailing column when the container is
+ *   slightly wider than `columns * minColumnWidth` but not wide enough for
+ *   `columns + 1` full columns.
+ * - Items that span multiple columns need coordinated `@container` queries
+ *   (via `useResponsiveGridItem`) to gracefully reduce their span — without
+ *   those styles an item requesting e.g. `span 3` will overflow or leave
+ *   blank tracks when only 2 columns fit.
+ *
+ * ## Usage
+ *
+ * When using the hooks directly (without `ResponsiveGrid`), pass the same
+ * config object to both hooks so that items can compute their container query
+ * breakpoints:
+ *
+ * ```tsx
+ * const gridConfig = { minColumnWidth: 276, columns: 4, gap: 24 };
+ * const { gridStyles } = useResponsiveGrid(gridConfig);
+ * const { gridItemProps, gridItemStyles } = useResponsiveGridItem({ colSpan: 3, gridConfig });
+ * ```
  */
 declare function useResponsiveGrid(props: useResponsiveGridProps): {
     gridStyles: Properties;
 };
 
-declare function useResponsiveGridItem({ colSpan }: {
-    colSpan?: number;
-}): {
-    gridItemProps: Record<string, number>;
-    gridItemStyles: Properties;
-};
-
 interface ResponsiveGridConfig {
     minColumnWidth: number;
     gap: number;
@@ -7178,6 +7235,47 @@ interface ResponsiveGridConfig {
 }
 declare const ResponsiveGridContext: React$1.Context<ResponsiveGridConfig | undefined>;
 
+interface UseResponsiveGridItemProps {
+    /** How many grid columns this item should span. Defaults to 1. */
+    colSpan?: number;
+    /**
+     * The grid configuration for computing container-query breakpoints.
+     *
+     * When items are rendered inside a `ResponsiveGrid` (or a manual
+     * `ResponsiveGridContext.Provider`), this is picked up from context
+     * automatically and can be omitted.
+     *
+     * When using the hooks directly (i.e. `useResponsiveGrid` +
+     * `useResponsiveGridItem` without a Provider), this **must** be supplied
+     * so the item can generate the correct `@container` query styles.
+     * Pass the same config object you gave to `useResponsiveGrid`:
+     *
+     * ```tsx
+     * const gridConfig = { minColumnWidth: 276, columns: 4, gap: 24 };
+     * const { gridStyles } = useResponsiveGrid(gridConfig);
+     * const { gridItemProps, gridItemStyles } = useResponsiveGridItem({ colSpan: 3, gridConfig });
+     * ```
+     */
+    gridConfig?: ResponsiveGridConfig;
+}
+/**
+ * Returns props and styles for a responsive grid item.
+ *
+ * - `gridItemProps` — a data attribute used to identify the item's requested
+ *   column span. Spread this onto the item's root element.
+ * - `gridItemStyles` — `@container` query CSS that gracefully reduces the
+ *   item's `grid-column` span as the grid container shrinks. Apply these to
+ *   the item's `css` prop.
+ *
+ * The container query breakpoints are derived from the grid config (see
+ * `UseResponsiveGridItemProps.gridConfig`). When `colSpan` is 1 or the
+ * config is unavailable, `gridItemStyles` will be an empty object.
+ */
+declare function useResponsiveGridItem(props: UseResponsiveGridItemProps): {
+    gridItemProps: Record<string, number>;
+    gridItemStyles: Properties;
+};
+
 interface HbLoadingSpinnerProps {
     /** Reverts loading text to `Loading...` if true. May override global noQuips by passing in noQuips={false}. */
     noQuips?: boolean;

package/dist/index.d.ts

@@ -5314,7 +5314,7 @@ declare function applyRowFn<R extends Kinded>(column: GridColumnWithId<R>, row:
 declare const ASC: "ASC";
 declare const DESC: "DESC";
 declare const emptyCell: GridCellContent;
-declare function getFirstOrLastCellCss<R extends Kinded>(style: GridStyle, columnIndex: number, columns: GridColumnWithId<R>[]): Properties;
+declare function getFirstOrLastCellCss<R extends Kinded>(style: GridStyle, columnIndex: number, columns: GridColumnWithId<R>[], colspan?: number): Properties;
 /** A heuristic to detect the result of `React.createElement` / i.e. JSX. */
 declare function isJSX(content: any): boolean;
 declare function getAlignment(column: GridColumnWithId<any>, maybeContent: ReactNode | GridCellContent): GridCellAlignment;
@@ -5392,23 +5392,27 @@ type LabelSuffixStyle = {
 interface GridStyle {
     /** Applied to the base div element. */
     rootCss?: Properties;
-    /** Applied with the owl operator between rows for rendering border lines. */
+    /**
+     * Applied as the base body-row cell styling (commonly used for row separators).
+     * This is applied to body rows broadly (including the last body row); use
+     * `lastRowCellCss`/`lastRowCss` to adjust/cancel any final-row treatment.
+     */
     betweenRowsCss?: Properties;
-    /** Applied on the last row of the table. */
+    /** Applied on the last row of the table, typically to override/cancel `betweenRowsCss`. */
     lastRowCss?: Properties;
     /** Applied on the first row of the table (could be the Header or Totals row). */
     firstRowCss?: Properties;
     /** Applied to every non-header row of the table */
     nonHeaderRowCss?: Properties;
-    /** Applied to the first non-header row, i.e. if you want to cancel out `betweenRowsCss`. */
-    firstNonHeaderRowCss?: Properties;
+    /** Applied to the first body row, i.e. if you want to cancel out `betweenRowsCss`. */
+    firstBodyRowCss?: Properties;
     /** Applied to all cell divs (via a selector off the base div). */
     cellCss?: Properties;
     /**
      * Applied to the header row divs.
      *
      * NOTE `as=virtual`: When using a virtual table with the goal of adding space
-     * between the header and the first row use `firstNonHeaderRowCss` with a
+     * between the header and the first row use `firstBodyRowCss` with a
      * margin-top instead. Using `headerCellCss` will not work since the header
      * rows are wrapper with Chrome rows.
      */
@@ -5423,6 +5427,18 @@ interface GridStyle {
     firstCellCss?: Properties;
     /** Applied to the last cell of all rows, i.e. for table-wide padding or right-side borders. */
     lastCellCss?: Properties;
+    /** Applied to every cell in the first table-head row (expandableHeader/header/totals). */
+    firstRowCellCss?: Properties;
+    /** Applied to the first cell in the first table-head row. */
+    firstRowFirstCellCss?: Properties;
+    /** Applied to the last cell in the first table-head row. */
+    firstRowLastCellCss?: Properties;
+    /** Applied to every cell in the last table-body row. */
+    lastRowCellCss?: Properties;
+    /** Applied to the first cell in the last table-body row. */
+    lastRowFirstCellCss?: Properties;
+    /** Applied to the last cell in the last table-body row. */
+    lastRowLastCellCss?: Properties;
     /** Applied if there is a fallback/overflow message showing. */
     firstRowMessageCss?: Properties;
     /** Applied on hover if a row has a rowLink/onClick set. */
@@ -5510,6 +5526,9 @@ interface RowProps<R extends Kinded> {
     cellHighlight: boolean;
     omitRowHover: boolean;
     hasExpandableHeader: boolean;
+    isFirstHeadRow: boolean;
+    isFirstBodyRow: boolean;
+    isLastBodyRow: boolean;
     resizedWidths: ResizedWidths;
     setResizedWidth: (columnId: string, width: number, columnIndex: number) => void;
     disableColumnResizing: boolean;
@@ -7155,22 +7174,60 @@ interface useResponsiveGridProps {
 /**
  * Returns container styles for a responsive CSS grid.
  *
- * Callers must provide the grid config via `ResponsiveGridContext` (or use the
- * `ResponsiveGrid` component) so that each item can call `useResponsiveGridItem`
- * and apply the returned `gridItemStyles` to achieve container-query-based
- * breakpoint behavior for multi-column spans.
+ * ## Layout algorithm
+ *
+ * The grid uses `auto-fill` columns with a clamped width:
+ *
+ * ```
+ * grid-template-columns: repeat(auto-fill, minmax(max(minColumnWidth, maxColumnWidth), 1fr))
+ * ```
+ *
+ * where `maxColumnWidth = (100% - totalGapWidth) / columns`.
+ *
+ * - The `max(minColumnWidth, maxColumnWidth)` clamp means each column is *at
+ *   least* `minColumnWidth` wide, but when the container is wide enough to fit
+ *   all `columns`, each column grows to fill the space equally.
+ * - `auto-fill` lets the browser drop columns automatically as the container
+ *   shrinks — once there isn't room for the next column at `minColumnWidth`,
+ *   the grid reflows to fewer columns.
+ * - The grid is also a CSS `container` (`container-type: inline-size`) so that
+ *   child items can use `@container` queries to adapt their `grid-column` span
+ *   based on the grid's current width. See `useResponsiveGridItem`.
+ *
+ * ### Trade-offs
+ *
+ * **Pros**
+ * - Fully CSS-driven reflow — no JS resize observers or manual breakpoint
+ *   bookkeeping; the browser handles column count changes natively.
+ * - Container queries keep span adjustments scoped to the grid's own width
+ *   rather than the viewport, so the grid works correctly inside any layout
+ *   (sidebars, split panes, etc.).
+ *
+ * **Cons**
+ * - `auto-fill` can produce an empty trailing column when the container is
+ *   slightly wider than `columns * minColumnWidth` but not wide enough for
+ *   `columns + 1` full columns.
+ * - Items that span multiple columns need coordinated `@container` queries
+ *   (via `useResponsiveGridItem`) to gracefully reduce their span — without
+ *   those styles an item requesting e.g. `span 3` will overflow or leave
+ *   blank tracks when only 2 columns fit.
+ *
+ * ## Usage
+ *
+ * When using the hooks directly (without `ResponsiveGrid`), pass the same
+ * config object to both hooks so that items can compute their container query
+ * breakpoints:
+ *
+ * ```tsx
+ * const gridConfig = { minColumnWidth: 276, columns: 4, gap: 24 };
+ * const { gridStyles } = useResponsiveGrid(gridConfig);
+ * const { gridItemProps, gridItemStyles } = useResponsiveGridItem({ colSpan: 3, gridConfig });
+ * ```
  */
 declare function useResponsiveGrid(props: useResponsiveGridProps): {
     gridStyles: Properties;
 };
 
-declare function useResponsiveGridItem({ colSpan }: {
-    colSpan?: number;
-}): {
-    gridItemProps: Record<string, number>;
-    gridItemStyles: Properties;
-};
-
 interface ResponsiveGridConfig {
     minColumnWidth: number;
     gap: number;
@@ -7178,6 +7235,47 @@ interface ResponsiveGridConfig {
 }
 declare const ResponsiveGridContext: React$1.Context<ResponsiveGridConfig | undefined>;
 
+interface UseResponsiveGridItemProps {
+    /** How many grid columns this item should span. Defaults to 1. */
+    colSpan?: number;
+    /**
+     * The grid configuration for computing container-query breakpoints.
+     *
+     * When items are rendered inside a `ResponsiveGrid` (or a manual
+     * `ResponsiveGridContext.Provider`), this is picked up from context
+     * automatically and can be omitted.
+     *
+     * When using the hooks directly (i.e. `useResponsiveGrid` +
+     * `useResponsiveGridItem` without a Provider), this **must** be supplied
+     * so the item can generate the correct `@container` query styles.
+     * Pass the same config object you gave to `useResponsiveGrid`:
+     *
+     * ```tsx
+     * const gridConfig = { minColumnWidth: 276, columns: 4, gap: 24 };
+     * const { gridStyles } = useResponsiveGrid(gridConfig);
+     * const { gridItemProps, gridItemStyles } = useResponsiveGridItem({ colSpan: 3, gridConfig });
+     * ```
+     */
+    gridConfig?: ResponsiveGridConfig;
+}
+/**
+ * Returns props and styles for a responsive grid item.
+ *
+ * - `gridItemProps` — a data attribute used to identify the item's requested
+ *   column span. Spread this onto the item's root element.
+ * - `gridItemStyles` — `@container` query CSS that gracefully reduces the
+ *   item's `grid-column` span as the grid container shrinks. Apply these to
+ *   the item's `css` prop.
+ *
+ * The container query breakpoints are derived from the grid config (see
+ * `UseResponsiveGridItemProps.gridConfig`). When `colSpan` is 1 or the
+ * config is unavailable, `gridItemStyles` will be an empty object.
+ */
+declare function useResponsiveGridItem(props: UseResponsiveGridItemProps): {
+    gridItemProps: Record<string, number>;
+    gridItemStyles: Properties;
+};
+
 interface HbLoadingSpinnerProps {
     /** Reverts loading text to `Loading...` if true. May override global noQuips by passing in noQuips={false}. */
     noQuips?: boolean;