@thangdevalone/meeting-grid-layout-core 1.4.1

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Dimensions of an element (width and height in pixels)
+ */
+interface GridDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Position of a grid item
+ */
+interface Position {
+    top: number;
+    left: number;
+}
+/**
+ * Layout modes for the grid
+ * - gallery: Flexible grid that fills all available space. Supports pin mode with pinnedIndex.
+ * - spotlight: Single participant in focus, others hidden
+ */
+type LayoutMode = 'gallery' | 'spotlight';
+/**
+ * Options for creating a basic grid
+ */
+interface GridOptions {
+    /** Aspect ratio in format "width:height" (e.g., "16:9", "4:3") */
+    aspectRatio: string;
+    /** Number of items in the grid */
+    count: number;
+    /** Container dimensions */
+    dimensions: GridDimensions;
+    /** Gap between items in pixels */
+    gap: number;
+}
+/**
+ * Aspect ratio configuration for individual items
+ * - string: Custom ratio like "16:9", "9:16", "4:3", "1:1"
+ * - 'auto': Use actual content dimensions (requires callback)
+ */
+type ItemAspectRatio = string | 'auto';
+/**
+ * Extended options for meet-style grid with layout modes
+ */
+interface MeetGridOptions extends GridOptions {
+    /** Layout mode for the grid */
+    layoutMode?: LayoutMode;
+    /** Index of pinned/focused item (main participant for spotlight/pin modes) */
+    pinnedIndex?: number;
+    /**
+     * Position of "others" thumbnails when a participant is pinned.
+     * In portrait containers, this is forced to 'bottom'.
+     * @default 'right'
+     */
+    othersPosition?: 'left' | 'right' | 'top' | 'bottom';
+    /** Maximum items per page for pagination (0 = no pagination) */
+    maxItemsPerPage?: number;
+    /** Current page index (0-based) for pagination */
+    currentPage?: number;
+    /**
+     * Maximum visible items (0 = show all).
+     * - In gallery mode without pin: limits total items displayed
+     * - In gallery mode with pin: limits "others" thumbnails (pinned item always visible)
+     * When set, shows a '+X' indicator on the last visible item.
+     * @default 0
+     */
+    maxVisible?: number;
+    /** Current page for items (0-based), used when maxVisible > 0 for pagination */
+    currentVisiblePage?: number;
+    /**
+     * Per-item aspect ratio configurations (index-based)
+     * Allows different aspect ratios per participant:
+     * - Use "9:16" for mobile/portrait participants
+     * - Use "16:9" for desktop/landscape participants
+     * - Use undefined to inherit from global aspectRatio
+     * @example
+     * itemAspectRatios: ["16:9", "9:16", undefined]
+     */
+    itemAspectRatios?: (ItemAspectRatio | undefined)[];
+    /**
+     * Custom width for the floating PiP item in 2-person mode.
+     * When set, overrides the width resolved from floatBreakpoints.
+     */
+    floatWidth?: number;
+    /**
+     * Custom height for the floating PiP item in 2-person mode.
+     * When set, overrides the height resolved from floatBreakpoints.
+     */
+    floatHeight?: number;
+    /**
+     * Responsive breakpoints for the floating PiP in 2-person mode.
+     * When provided, PiP size auto-adjusts based on container width.
+     * Use `DEFAULT_FLOAT_BREAKPOINTS` as a starting point or define your own.
+     * `floatWidth`/`floatHeight` still override the resolved size when set.
+     *
+     * @example
+     * // Use default 5-level responsive breakpoints
+     * floatBreakpoints: DEFAULT_FLOAT_BREAKPOINTS
+     *
+     * // Custom breakpoints
+     * floatBreakpoints: [
+     *   { minWidth: 0, width: 80, height: 110 },
+     *   { minWidth: 600, width: 150, height: 200 },
+     *   { minWidth: 1200, width: 250, height: 330 },
+     * ]
+     */
+    floatBreakpoints?: PipBreakpoint[];
+}
+/**
+ * Pagination info returned with grid result
+ */
+interface PaginationInfo {
+    /** Whether pagination is enabled */
+    enabled: boolean;
+    /** Current page (0-based) */
+    currentPage: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Items shown on current page */
+    itemsOnPage: number;
+    /** Start index of items on current page */
+    startIndex: number;
+    /** End index of items on current page (exclusive) */
+    endIndex: number;
+}
+/**
+ * Result from grid calculations
+ */
+interface GridResult {
+    /** Width of each grid item */
+    width: number;
+    /** Height of each grid item */
+    height: number;
+    /** Number of rows */
+    rows: number;
+    /** Number of columns */
+    cols: number;
+    /** Function to get position of item at index */
+    getPosition: (index: number) => Position;
+}
+/**
+ * Content dimensions result with positioning info
+ */
+interface ContentDimensions extends GridDimensions {
+    /** Offset from cell top to center the content */
+    offsetTop: number;
+    /** Offset from cell left to center the content */
+    offsetLeft: number;
+}
+/**
+ * Responsive breakpoint configuration for PiP sizing.
+ * The system selects the breakpoint with the largest `minWidth` that is <= container width.
+ *
+ * @example
+ * // Custom breakpoints
+ * const breakpoints: PipBreakpoint[] = [
+ *   { minWidth: 0, width: 80, height: 110 },      // Small mobile
+ *   { minWidth: 480, width: 120, height: 160 },    // Mobile
+ *   { minWidth: 768, width: 160, height: 215 },    // Tablet
+ *   { minWidth: 1024, width: 200, height: 270 },   // Desktop
+ * ]
+ */
+interface PipBreakpoint {
+    /** Minimum container width (px) for this breakpoint to apply */
+    minWidth: number;
+    /** PiP width at this breakpoint (px) */
+    width: number;
+    /** PiP height at this breakpoint (px) */
+    height: number;
+}
+/**
+ * Default responsive breakpoints for PiP sizing.
+ * Provides 5 levels from small mobile to large desktop.
+ *
+ * | Breakpoint     | Container Width | PiP Size   |
+ * | -------------- | --------------- | ---------- |
+ * | Small mobile   | 0 – 479px       | 100 × 135  |
+ * | Mobile/Tablet  | 480 – 767px     | 130 × 175  |
+ * | Tablet         | 768 – 1023px    | 160 × 215  |
+ * | Desktop        | 1024 – 1439px   | 180 × 240  |
+ * | Large Desktop  | 1440px+         | 220 × 295  |
+ */
+declare const DEFAULT_FLOAT_BREAKPOINTS: PipBreakpoint[];
+/**
+ * Resolve PiP size from responsive breakpoints based on container width.
+ * Selects the breakpoint with the largest `minWidth` that is <= `containerWidth`.
+ *
+ * @param containerWidth - Current container width in pixels
+ * @param breakpoints - Array of PipBreakpoint configurations
+ * @returns Resolved { width, height } for the PiP
+ */
+declare function resolveFloatSize(containerWidth: number, breakpoints: PipBreakpoint[]): GridDimensions;
+/**
+ * Extended result for meet-style grid
+ */
+interface MeetGridResult extends GridResult {
+    /** Layout mode used */
+    layoutMode: LayoutMode;
+    /** Get item cell dimensions (the grid cell size, may vary by index in some modes) */
+    getItemDimensions: (index: number) => GridDimensions;
+    /** Check if item is the main/featured item */
+    isMainItem: (index: number) => boolean;
+    /** Pagination info (if pagination is enabled) */
+    pagination: PaginationInfo;
+    /** Check if item should be visible on current page */
+    isItemVisible: (index: number) => boolean;
+    /**
+     * Number of hidden items (for '+X more' indicator).
+     * When maxVisible is set and there are more participants than allowed,
+     * this indicates how many are hidden.
+     */
+    hiddenCount: number;
+    /**
+     * Get the last visible item index in the "others" section.
+     * Returns -1 if no items are visible or if there's no "others" section.
+     * Useful for showing '+X more' indicator on the last visible item.
+     */
+    getLastVisibleOthersIndex: () => number;
+    /**
+     * Get the actual content dimensions within a cell.
+     * Use this when items have different aspect ratios (e.g., phone vs desktop).
+     * Returns dimensions fitted within the cell while maintaining the item's aspect ratio.
+     *
+     * @param index - The item index
+     * @param itemRatio - The item's aspect ratio ("16:9", "9:16", or undefined for cell dimensions)
+     * @returns Content dimensions with offset for centering within the cell
+     *
+     * @example
+     * // For a mobile participant (9:16)
+     * const content = grid.getItemContentDimensions(0, "9:16")
+     *
+     * // Apply in React:
+     * <div style={{
+     *   width: content.width,
+     *   height: content.height,
+     *   marginTop: content.offsetTop,
+     *   marginLeft: content.offsetLeft
+     * }}>
+     */
+    getItemContentDimensions: (index: number, itemRatio?: ItemAspectRatio) => ContentDimensions;
+    /**
+     * Index of the item that should be rendered as a floating PiP overlay.
+     * When set, the component layer (GridItem) should render this item as a
+     * draggable FloatingGridItem instead of a regular positioned item.
+     * Used automatically in 2-person mode (Zoom-style layout).
+     */
+    floatIndex?: number;
+    /**
+     * Dimensions for the floating PiP item.
+     * Only set when floatIndex is defined.
+     */
+    floatDimensions?: GridDimensions;
+}
+/**
+ * Parses the Aspect Ratio string to actual ratio (height/width)
+ * @param ratio The aspect ratio in the format of "width:height" (e.g., "16:9")
+ * @returns The parsed value of aspect ratio (height/width)
+ */
+declare function getAspectRatio(ratio: string): number;
+/**
+ * Parse aspect ratio to get width/height multiplier
+ */
+declare function parseAspectRatio(ratio: string): {
+    widthRatio: number;
+    heightRatio: number;
+};
+/**
+ * Calculate content dimensions that fit within a cell while maintaining aspect ratio
+ * @param cellDimensions - The cell dimensions to fit content into
+ * @param itemRatio - The content's aspect ratio ("16:9", "9:16", etc.)
+ * @param defaultRatio - The default aspect ratio to use if itemRatio is undefined
+ * @returns Content dimensions with offset for centering
+ */
+declare function calculateContentDimensions(cellDimensions: GridDimensions, itemRatio?: ItemAspectRatio, defaultRatio?: string): ContentDimensions;
+/**
+ * Calculates grid item dimensions for items that can fit in a container.
+ * Adapted from: https://stackoverflow.com/a/28268965
+ */
+declare function getGridItemDimensions({ count, dimensions, aspectRatio, gap }: GridOptions): {
+    width: number;
+    height: number;
+    rows: number;
+    cols: number;
+};
+/**
+ * Creates a utility function which helps you position grid items in a container.
+ */
+declare function createGridItemPositioner({ parentDimensions, dimensions, rows, cols, count, gap, }: {
+    parentDimensions: GridDimensions;
+    dimensions: GridDimensions;
+    rows: number;
+    cols: number;
+    count: number;
+    gap: number;
+}): (index: number) => Position;
+/**
+ * Calculates data required for making a responsive grid.
+ */
+declare function createGrid({ aspectRatio, count, dimensions, gap }: GridOptions): GridResult;
+/**
+ * Create a meet-style grid with support for different layout modes.
+ * This is the main function for creating video conferencing-style layouts.
+ */
+declare function createMeetGrid(options: MeetGridOptions): MeetGridResult;
+/**
+ * Spring animation configuration presets
+ */
+declare const springPresets: {
+    /** Snappy animations for UI interactions */
+    readonly snappy: {
+        readonly stiffness: 400;
+        readonly damping: 30;
+    };
+    /** Smooth animations for layout changes */
+    readonly smooth: {
+        readonly stiffness: 300;
+        readonly damping: 30;
+    };
+    /** Gentle animations for subtle effects */
+    readonly gentle: {
+        readonly stiffness: 200;
+        readonly damping: 25;
+    };
+    /** Bouncy animations for playful effects */
+    readonly bouncy: {
+        readonly stiffness: 400;
+        readonly damping: 15;
+    };
+};
+type SpringPreset = keyof typeof springPresets;
+/**
+ * Get spring configuration for Motion animations
+ */
+declare function getSpringConfig(preset?: SpringPreset): {
+    stiffness: 400;
+    damping: 30;
+    type: "spring";
+} | {
+    stiffness: 300;
+    damping: 30;
+    type: "spring";
+} | {
+    stiffness: 200;
+    damping: 25;
+    type: "spring";
+} | {
+    stiffness: 400;
+    damping: 15;
+    type: "spring";
+};
+
+export { DEFAULT_FLOAT_BREAKPOINTS, calculateContentDimensions, createGrid, createGridItemPositioner, createMeetGrid, getAspectRatio, getGridItemDimensions, getSpringConfig, parseAspectRatio, resolveFloatSize, springPresets };
+export type { ContentDimensions, GridDimensions, GridOptions, GridResult, ItemAspectRatio, LayoutMode, MeetGridOptions, MeetGridResult, PaginationInfo, PipBreakpoint, Position, SpringPreset };