bento-grid-builder 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,408 @@
+import React, { ReactNode, CSSProperties, ComponentType } from 'react';
+
+/**
+ * Definition for a card component that can be rendered in the bento grid
+ * Users register their card components with this interface
+ */
+interface BentoCardDefinition<TProps = any> {
+    /** Unique identifier for this card type */
+    id: string;
+    /** The React component to render */
+    component: ComponentType<TProps>;
+    /** Default column span (defaults to 1) */
+    colSpan?: number;
+    /** Default row span (defaults to 1) */
+    rowSpan?: number;
+}
+/**
+ * Unified card definition that combines component, layout, and data mapping
+ * This is the preferred way to define cards - cleaner than separate arrays
+ * @template TData - The shape of your data source
+ * @template TProps - The props your card component expects
+ */
+interface UnifiedCardDefinition<TData = unknown, TProps = any> {
+    /** Unique identifier for this card */
+    id: string;
+    /** The React component to render */
+    component: ComponentType<TProps>;
+    /** Function that extracts props from your data for this card */
+    propsSelector: (data: TData) => TProps;
+    /** Default column span (defaults to 1) */
+    colSpan?: number;
+    /** Default row span (defaults to 1) */
+    rowSpan?: number;
+    /** Whether this card should be visible (defaults to true) */
+    visible?: boolean | ((data: TData) => boolean);
+    /** Whether this card is in a loading state */
+    loading?: boolean | ((data: TData) => boolean);
+    /** Custom loading component for this card */
+    loadingComponent?: ComponentType;
+}
+/**
+ * Position and size of a card in the grid
+ */
+interface CardPlacement {
+    /** Card definition ID to render */
+    cardId: string;
+    /** Starting column (1-indexed) */
+    col: number;
+    /** Starting row (1-indexed) */
+    row: number;
+    /** Number of columns to span (overrides card default) */
+    colSpan?: number;
+    /** Number of rows to span (overrides card default) */
+    rowSpan?: number;
+}
+/**
+ * Explicit slot-to-card mapping for preset layouts
+ * Allows users to specify which card goes in which slot by name
+ */
+interface PresetSlotMapping {
+    /** Slot index (0-based) or slot name if preset supports named slots */
+    slot: number | string;
+    /** Card ID to place in this slot */
+    cardId: string;
+}
+/**
+ * Complete layout configuration for the bento grid
+ */
+interface BentoLayoutConfig {
+    /** Number of columns in the grid */
+    columns: number;
+    /** Number of rows (optional - auto-calculated if not provided) */
+    rows?: number;
+    /** Gap between cards in pixels (applies to both row and column) */
+    gap?: number;
+    /** Gap between columns in pixels (overrides gap for columns) */
+    columnGap?: number;
+    /** Gap between rows in pixels (overrides gap for rows) */
+    rowGap?: number;
+    /** Card placements in the grid */
+    placements: CardPlacement[];
+}
+/**
+ * Breakpoint configuration for responsive layouts
+ */
+interface BreakpointConfig {
+    /** Minimum viewport width for this breakpoint (in pixels) */
+    minWidth: number;
+    /** Layout to use at this breakpoint */
+    layout: BentoLayoutConfig | PresetLayoutName;
+}
+/**
+ * Responsive layout configuration
+ * Allows different layouts at different viewport widths
+ */
+interface ResponsiveLayoutConfig {
+    /** Default layout (used when no breakpoint matches) */
+    default: BentoLayoutConfig | PresetLayoutName;
+    /** Breakpoint-specific layouts (applied when viewport >= minWidth) */
+    breakpoints: BreakpointConfig[];
+}
+/**
+ * Maps data from your data source to a specific card's props
+ * @template TData - The shape of your data source
+ */
+interface CardDataMapping<TData = unknown> {
+    /** Card definition ID this mapping applies to */
+    cardId: string;
+    /** Function that extracts props from your data for this card */
+    propsSelector: (data: TData) => Record<string, unknown>;
+}
+/** Available preset layout names */
+type PresetLayoutName = "2x2" | "3x2" | "3x3" | "4x2" | "2x1-hero-left" | "2x1-hero-right" | "dashboard-9";
+/**
+ * Preset layout definition
+ */
+interface PresetLayout {
+    name: PresetLayoutName;
+    columns: number;
+    rows: number;
+    /** Slot positions for cards - users just provide cardIds in order */
+    slots: Array<{
+        /** Optional name for this slot (e.g., "hero", "sidebar") */
+        name?: string;
+        col: number;
+        row: number;
+        colSpan?: number;
+        rowSpan?: number;
+    }>;
+}
+/**
+ * Props for the main BentoGrid component
+ * @template TData - The shape of your data source
+ */
+interface BentoGridProps<TData = unknown> {
+    /** Layout configuration, preset name, or responsive config */
+    layout: BentoLayoutConfig | PresetLayoutName | ResponsiveLayoutConfig;
+    /** Registered card definitions */
+    cards: BentoCardDefinition[];
+    /** Your data source */
+    data: TData;
+    /** Maps your data to each card's props */
+    dataMapping: CardDataMapping<TData>[];
+    /** Additional CSS class for the grid container */
+    className?: string;
+    /** Additional inline styles for the grid container */
+    style?: CSSProperties;
+    /** Custom card wrapper component */
+    cardWrapper?: ComponentType<CardWrapperProps>;
+    /** Called when a card fails to render */
+    onCardError?: (cardId: string, error: Error) => void;
+    /** Accessible label for the grid region */
+    ariaLabel?: string;
+    /** ID of element that labels this grid */
+    ariaLabelledBy?: string;
+    /** Enable enter/exit animations for cards */
+    animated?: boolean;
+    /** Animation duration in milliseconds (default: 300) */
+    animationDuration?: number;
+    /** CSS class for grid cells */
+    cellClassName?: string | ((cardId: string) => string);
+}
+/**
+ * Props for the unified BentoGrid component (preferred API)
+ * Combines cards and data mapping into a single prop
+ * @template TData - The shape of your data source
+ */
+interface UnifiedBentoGridProps<TData = unknown> {
+    /** Layout configuration, preset name, or responsive config */
+    layout: BentoLayoutConfig | PresetLayoutName | ResponsiveLayoutConfig;
+    /** Unified card definitions with components and data selectors */
+    cards: UnifiedCardDefinition<TData, any>[];
+    /** Your data source */
+    data: TData;
+    /** Additional CSS class for the grid container */
+    className?: string;
+    /** Additional inline styles for the grid container */
+    style?: CSSProperties;
+    /** Custom card wrapper component */
+    cardWrapper?: ComponentType<CardWrapperProps>;
+    /** Called when a card fails to render */
+    onCardError?: (cardId: string, error: Error) => void;
+    /** Accessible label for the grid region */
+    ariaLabel?: string;
+    /** ID of element that labels this grid */
+    ariaLabelledBy?: string;
+    /** Enable enter/exit animations for cards */
+    animated?: boolean;
+    /** Animation duration in milliseconds (default: 300) */
+    animationDuration?: number;
+    /** Global loading component for all cards */
+    loadingComponent?: ComponentType;
+    /** CSS class for grid cells */
+    cellClassName?: string | ((cardId: string) => string);
+}
+/**
+ * Props passed to the card wrapper component
+ */
+interface CardWrapperProps {
+    children: ReactNode;
+    cardId: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Props for the default BentoCard wrapper
+ */
+interface BentoCardProps {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+
+/**
+ * BentoGrid - A flexible, configurable bento grid layout system
+ *
+ * @example
+ * ```tsx
+ * <BentoGrid
+ *   layout="3x3"
+ *   cards={[
+ *     { id: 'stats', component: StatsCard },
+ *     { id: 'chart', component: ChartCard },
+ *   ]}
+ *   data={myData}
+ *   dataMapping={[
+ *     { cardId: 'stats', propsSelector: (d) => ({ count: d.total }) },
+ *     { cardId: 'chart', propsSelector: (d) => ({ points: d.chartData }) },
+ *   ]}
+ * />
+ * ```
+ */
+declare function BentoGrid<TData>({ layout, cards, data, dataMapping, className, style, cardWrapper, onCardError, ariaLabel, ariaLabelledBy, animated, animationDuration, cellClassName, }: BentoGridProps<TData>): React.ReactElement;
+/**
+ * UnifiedBentoGrid - Cleaner API that combines cards and data mapping
+ *
+ * This is the preferred way to use BentoGrid. Instead of separate `cards` and
+ * `dataMapping` arrays, you define everything in one place.
+ *
+ * @example
+ * ```tsx
+ * <UnifiedBentoGrid
+ *   layout="3x2"
+ *   cards={[
+ *     {
+ *       id: 'stats',
+ *       component: StatsCard,
+ *       propsSelector: (d) => ({ count: d.total, label: 'Users' }),
+ *       colSpan: 2,
+ *     },
+ *     {
+ *       id: 'chart',
+ *       component: ChartCard,
+ *       propsSelector: (d) => ({ data: d.chartData }),
+ *       visible: (d) => d.chartData.length > 0,
+ *       loading: (d) => d.isLoading,
+ *     },
+ *   ]}
+ *   data={myData}
+ *   animated
+ * />
+ * ```
+ */
+declare function UnifiedBentoGrid<TData>({ layout, cards, data, className, style, cardWrapper, onCardError, ariaLabel, ariaLabelledBy, animated, animationDuration, loadingComponent: GlobalLoadingComponent, cellClassName, }: UnifiedBentoGridProps<TData>): React.ReactElement;
+
+/**
+ * Default card wrapper component
+ * Provides basic styling - users can override with their own wrapper
+ * Uses CSS custom properties for easy theming
+ */
+declare const BentoCard: React.FC<BentoCardProps>;
+
+/**
+ * Check if a layout config is a responsive config
+ */
+declare function isResponsiveConfig(layout: BentoLayoutConfig | PresetLayoutName | ResponsiveLayoutConfig): layout is ResponsiveLayoutConfig;
+/**
+ * Hook to handle responsive layouts based on viewport width
+ * Returns the appropriate layout for the current viewport
+ *
+ * @example
+ * ```tsx
+ * const layout = useResponsiveLayout({
+ *   default: "2x2",
+ *   breakpoints: [
+ *     { minWidth: 768, layout: "3x2" },
+ *     { minWidth: 1024, layout: "4x2" },
+ *   ],
+ * });
+ * ```
+ */
+declare function useResponsiveLayout(config: BentoLayoutConfig | PresetLayoutName | ResponsiveLayoutConfig): BentoLayoutConfig | PresetLayoutName;
+/**
+ * Hook to track window width with debouncing
+ */
+declare function useWindowWidth(debounceMs?: number): number;
+/**
+ * Hook to create card definitions from an object map
+ * Provides a cleaner API for defining cards
+ *
+ * @example
+ * ```tsx
+ * const cards = useCardDefinitions({
+ *   stats: { component: StatsCard, colSpan: 2 },
+ *   chart: { component: ChartCard },
+ *   list: { component: ListCard, rowSpan: 2 },
+ * });
+ * ```
+ */
+declare function useCardDefinitions<T extends Record<string, Omit<BentoCardDefinition<any>, "id">>>(definitions: T): BentoCardDefinition<any>[];
+/**
+ * Hook to create data mappings from an object map
+ * Provides a cleaner API for mapping data to cards
+ *
+ * @example
+ * ```tsx
+ * const dataMapping = useDataMapping<MyDataType>({
+ *   stats: (data) => ({ count: data.total, label: 'Items' }),
+ *   chart: (data) => ({ points: data.chartData }),
+ * });
+ * ```
+ */
+declare function useDataMapping<TData>(mappings: Record<string, (data: TData) => Record<string, unknown>>): CardDataMapping<TData>[];
+/**
+ * Hook to create a layout configuration
+ * Handles both preset names and custom configs
+ *
+ * @example
+ * ```tsx
+ * // Using preset
+ * const layout = useLayout("3x3", ["stats", "chart", "list", ...]);
+ *
+ * // Using custom config
+ * const layout = useLayout({
+ *   columns: 3,
+ *   placements: [
+ *     { cardId: "stats", col: 1, row: 1, colSpan: 2 },
+ *     { cardId: "chart", col: 3, row: 1 },
+ *   ]
+ * });
+ * ```
+ */
+declare function useLayout(config: PresetLayoutName | BentoLayoutConfig, cardIds?: string[]): BentoLayoutConfig;
+
+/**
+ * Create a simple grid layout where cards are placed sequentially
+ * Useful for quick prototyping
+ *
+ * @example
+ * ```ts
+ * const layout = createSimpleLayout(3, ["a", "b", "c", "d", "e", "f"]);
+ * // Creates a 3-column grid with cards placed left-to-right, top-to-bottom
+ * ```
+ */
+declare function createSimpleLayout(columns: number, cardIds: string[], gap?: number): BentoLayoutConfig;
+/**
+ * Layout builder for fluent API
+ *
+ * @example
+ * ```ts
+ * const layout = layoutBuilder(3)
+ *   .gap(16)
+ *   .columnGap(20)
+ *   .rowGap(12)
+ *   .place("hero", 1, 1, { colSpan: 2, rowSpan: 2 })
+ *   .place("stats", 3, 1)
+ *   .place("chart", 3, 2)
+ *   .build();
+ * ```
+ */
+declare function layoutBuilder(columns: number): {
+    gap(value: number): /*elided*/ any;
+    columnGap(value: number): /*elided*/ any;
+    rowGap(value: number): /*elided*/ any;
+    rows(value: number): /*elided*/ any;
+    place(cardId: string, col: number, row: number, options?: {
+        colSpan?: number;
+        rowSpan?: number;
+    }): /*elided*/ any;
+    build(): BentoLayoutConfig;
+};
+/**
+ * Validate a layout configuration
+ * Returns array of validation errors (empty if valid)
+ */
+declare function validateLayout(layout: BentoLayoutConfig): string[];
+
+/**
+ * Preset layout definitions
+ * Users can use these by name instead of defining custom layouts
+ */
+declare const PRESET_LAYOUTS: Record<PresetLayoutName, PresetLayout>;
+/**
+ * Convert a preset name to a full layout config with card IDs
+ * Supports both legacy array-based assignment and explicit slot mapping
+ */
+declare function presetToLayout(presetName: PresetLayoutName, cardIdsOrMapping: string[] | PresetSlotMapping[]): BentoLayoutConfig;
+/**
+ * Get available slot names for a preset layout
+ * Useful for discovering what slots are available
+ */
+declare function getPresetSlotNames(presetName: PresetLayoutName): string[];
+/**
+ * Check if a value is a preset layout name
+ */
+declare function isPresetName(value: unknown): value is PresetLayoutName;
+
+export { BentoCard, type BentoCardDefinition, type BentoCardProps, BentoGrid, type BentoGridProps, type BentoLayoutConfig, type BreakpointConfig, type CardDataMapping, type CardPlacement, type CardWrapperProps, PRESET_LAYOUTS, type PresetLayout, type PresetLayoutName, type PresetSlotMapping, type ResponsiveLayoutConfig, UnifiedBentoGrid, type UnifiedBentoGridProps, type UnifiedCardDefinition, createSimpleLayout, getPresetSlotNames, isPresetName, isResponsiveConfig, layoutBuilder, presetToLayout, useCardDefinitions, useDataMapping, useLayout, useResponsiveLayout, useWindowWidth, validateLayout };