@homebound/beam 2.417.5 → 2.417.6

package/dist/index.d.cts

@@ -7155,22 +7155,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 +7216,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

@@ -7155,22 +7155,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 +7216,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.js

@@ -18023,8 +18023,10 @@ function useResponsiveGrid(props) {
 
 // src/components/Grid/useResponsiveGridItem.ts
 import { useContext as useContext18, useMemo as useMemo45 } from "react";
-function useResponsiveGridItem({ colSpan = 1 }) {
-  const config = useContext18(ResponsiveGridContext);
+function useResponsiveGridItem(props) {
+  const { colSpan = 1, gridConfig } = props;
+  const contextConfig = useContext18(ResponsiveGridContext);
+  const config = gridConfig ?? contextConfig;
   const gridItemStyles = useMemo45(() => {
     if (!config || colSpan <= 1) return {};
     const { minColumnWidth, gap } = config;