@thangdevalone/meeting-grid-layout-react 1.4.1

package/dist/index.d.cts

@@ -0,0 +1,238 @@
+import * as React from 'react';
+import React__default, { RefObject, HTMLAttributes, ReactNode, CSSProperties } from 'react';
+import { GridDimensions, MeetGridOptions, MeetGridResult, SpringPreset, LayoutMode, ItemAspectRatio, ContentDimensions } from '@thangdevalone/meeting-grid-layout-core';
+export { ContentDimensions, GridDimensions, GridOptions, ItemAspectRatio, LayoutMode, MeetGridOptions, MeetGridResult, PaginationInfo, Position, SpringPreset, createGrid, createGridItemPositioner, createMeetGrid, getAspectRatio, getGridItemDimensions, getSpringConfig, springPresets } from '@thangdevalone/meeting-grid-layout-core';
+import { HTMLMotionProps, Transition } from 'motion/react';
+
+interface GridContextValue {
+    dimensions: GridDimensions;
+    grid: MeetGridResult | null;
+    springPreset: SpringPreset;
+}
+declare const GridContext: React.Context<GridContextValue | null>;
+/**
+ * Hook to access the grid context
+ */
+declare function useGridContext(): GridContextValue;
+
+/**
+ * A React hook to calculate dimensions of an element using ResizeObserver.
+ * @param ref An element ref
+ * @returns Dimensions of the element
+ */
+declare function useGridDimensions(ref: RefObject<HTMLElement | null>): GridDimensions;
+/**
+ * React hook for creating a meet-style responsive grid.
+ * @param options Grid options including dimensions, count, aspectRatio, gap, and layoutMode
+ * @returns Grid result with width, height, and position getter
+ */
+declare function useMeetGrid(options: MeetGridOptions): MeetGridResult;
+/**
+ * Hook to get animation configuration for Motion
+ */
+declare function useGridAnimation(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";
+};
+
+interface GridContainerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Children to render inside the grid */
+    children: ReactNode;
+    /** Aspect ratio in format "width:height" (e.g., "16:9") */
+    aspectRatio?: string;
+    /** Gap between items in pixels */
+    gap?: number;
+    /** Number of items (if not using GridItem children) */
+    count?: number;
+    /** Layout mode */
+    layoutMode?: LayoutMode;
+    /** Index of pinned/focused item (main participant for pin/spotlight 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';
+    /** Spring animation preset */
+    springPreset?: SpringPreset;
+    /** Custom container style */
+    style?: CSSProperties;
+    /** Additional class name */
+    className?: string;
+    /** 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 all items. With pin: limits "others". */
+    maxVisible?: number;
+    /** Current page for visible items (0-based), used when maxVisible > 0 */
+    currentVisiblePage?: number;
+    /**
+     * Per-item aspect ratio configurations.
+     * Use different ratios for mobile (9:16), desktop (16:9).
+     * @example ['16:9', '9:16', undefined]
+     */
+    itemAspectRatios?: (ItemAspectRatio | undefined)[];
+    /** Custom width for the floating PiP item in 2-person mode */
+    floatWidth?: number;
+    /** Custom height for the floating PiP item in 2-person mode */
+    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` for a ready-made 5-level responsive config.
+     * @example
+     * floatBreakpoints={DEFAULT_FLOAT_BREAKPOINTS}
+     * floatBreakpoints={[
+     *   { minWidth: 0, width: 80, height: 110 },
+     *   { minWidth: 600, width: 150, height: 200 },
+     * ]}
+     */
+    floatBreakpoints?: PipBreakpoint[];
+}
+/**
+ * Container component for the meet grid.
+ * Provides grid context to child GridItem components.
+ */
+declare const GridContainer: React__default.ForwardRefExoticComponent<GridContainerProps & React__default.RefAttributes<HTMLDivElement>>;
+interface GridItemProps extends Omit<HTMLMotionProps<'div'>, 'animate' | 'initial' | 'transition' | 'children'> {
+    /** Index of this item in the grid */
+    index: number;
+    /**
+     * Children to render inside the item.
+     * Can be a ReactNode or a render function that receives contentDimensions and visibility info.
+     * @example
+     * // Simple usage
+     * <GridItem index={0}><Video /></GridItem>
+     *
+     * // With contentDimensions for flexible aspect ratios
+     * <GridItem index={0}>
+     *   {({ contentDimensions }) => (
+     *     <Video style={{
+     *       width: contentDimensions.width,
+     *       height: contentDimensions.height,
+     *       marginTop: contentDimensions.offsetTop,
+     *       marginLeft: contentDimensions.offsetLeft
+     *     }} />
+     *   )}
+     * </GridItem>
+     *
+     * // With hidden count for '+X more' indicator
+     * <GridItem index={index}>
+     *   {({ isLastVisibleOther, hiddenCount }) => (
+     *     <div>
+     *       {isLastVisibleOther && hiddenCount > 0 && (
+     *         <span className="more-indicator">+{hiddenCount}</span>
+     *       )}
+     *     </div>
+     *   )}
+     * </GridItem>
+     */
+    children: ReactNode | ((props: {
+        contentDimensions: ContentDimensions;
+        /** True if this is the last visible item in the "others" section */
+        isLastVisibleOther: boolean;
+        /** Number of hidden items (for '+X more' indicator) */
+        hiddenCount: number;
+        /** True if this item is rendered as a floating PiP */
+        isFloat: boolean;
+    }) => ReactNode);
+    /** Optional item-specific aspect ratio (overrides itemAspectRatios from container) */
+    itemAspectRatio?: ItemAspectRatio;
+    /** Custom transition override */
+    transition?: Transition;
+    /** Whether to disable animations */
+    disableAnimation?: boolean;
+    /** Additional class name */
+    className?: string;
+    /** Custom style (merged with animated styles) */
+    style?: CSSProperties;
+}
+/**
+ * Grid item component with Motion animations.
+ * Automatically positions itself based on index in the grid.
+ * When the grid marks this item as float (2-person mode), renders as a draggable PiP.
+ */
+declare const GridItem: React__default.ForwardRefExoticComponent<Omit<GridItemProps, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
+interface FloatingGridItemProps extends Omit<HTMLMotionProps<'div'>, 'animate' | 'initial' | 'children'> {
+    /** Children to render inside the floating item */
+    children: ReactNode;
+    /** Width of the floating item (px). Overridden by `breakpoints` when provided. */
+    width?: number;
+    /** Height of the floating item (px). Overridden by `breakpoints` when provided. */
+    height?: number;
+    /**
+     * Responsive breakpoints for PiP sizing.
+     * When provided, width/height auto-adjust based on container width.
+     * Overrides the fixed `width`/`height` props.
+     * Use `DEFAULT_FLOAT_BREAKPOINTS` for a ready-made 5-level responsive config.
+     *
+     * @example
+     * // Use default responsive breakpoints
+     * breakpoints={DEFAULT_FLOAT_BREAKPOINTS}
+     *
+     * // Custom breakpoints
+     * breakpoints={[
+     *   { minWidth: 0, width: 80, height: 110 },
+     *   { minWidth: 600, width: 150, height: 200 },
+     *   { minWidth: 1200, width: 250, height: 330 },
+     * ]}
+     */
+    breakpoints?: PipBreakpoint[];
+    /** Initial position (x, y from container edges) */
+    initialPosition?: {
+        x: number;
+        y: number;
+    };
+    /** Which corner to anchor: 'top-left', 'top-right', 'bottom-left', 'bottom-right' */
+    anchor?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /** Whether the item is visible */
+    visible?: boolean;
+    /** Padding from container edges */
+    edgePadding?: number;
+    /** Callback when anchor changes after snap */
+    onAnchorChange?: (anchor: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right') => void;
+    /** Custom transition */
+    transition?: Transition;
+    /** Border radius */
+    borderRadius?: number;
+    /** Box shadow */
+    boxShadow?: string;
+    /** Additional class name */
+    className?: string;
+    /** Custom style */
+    style?: CSSProperties;
+}
+/**
+ * Floating Grid Item component that can be dragged around the screen.
+ * Snaps to the nearest corner when released (like iOS/Android PiP).
+ * Perfect for Picture-in-Picture style floating video in zoom mode.
+ */
+declare const FloatingGridItem: React__default.ForwardRefExoticComponent<Omit<FloatingGridItemProps, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
+interface GridOverlayProps extends HTMLAttributes<HTMLDivElement> {
+    /** Whether to show the overlay */
+    visible?: boolean;
+    /** Overlay background color */
+    backgroundColor?: string;
+}
+/**
+ * Overlay component for grid items (e.g., for muted indicator, name label)
+ */
+declare const GridOverlay: React__default.ForwardRefExoticComponent<GridOverlayProps & React__default.RefAttributes<HTMLDivElement>>;
+
+export { FloatingGridItem, GridContainer, GridContext, GridItem, GridOverlay, useGridAnimation, useGridContext, useGridDimensions, useMeetGrid };
+export type { FloatingGridItemProps, GridContainerProps, GridItemProps, GridOverlayProps };

package/dist/index.d.mts

@@ -0,0 +1,238 @@
+import * as React from 'react';
+import React__default, { RefObject, HTMLAttributes, ReactNode, CSSProperties } from 'react';
+import { GridDimensions, MeetGridOptions, MeetGridResult, SpringPreset, LayoutMode, ItemAspectRatio, ContentDimensions } from '@thangdevalone/meeting-grid-layout-core';
+export { ContentDimensions, GridDimensions, GridOptions, ItemAspectRatio, LayoutMode, MeetGridOptions, MeetGridResult, PaginationInfo, Position, SpringPreset, createGrid, createGridItemPositioner, createMeetGrid, getAspectRatio, getGridItemDimensions, getSpringConfig, springPresets } from '@thangdevalone/meeting-grid-layout-core';
+import { HTMLMotionProps, Transition } from 'motion/react';
+
+interface GridContextValue {
+    dimensions: GridDimensions;
+    grid: MeetGridResult | null;
+    springPreset: SpringPreset;
+}
+declare const GridContext: React.Context<GridContextValue | null>;
+/**
+ * Hook to access the grid context
+ */
+declare function useGridContext(): GridContextValue;
+
+/**
+ * A React hook to calculate dimensions of an element using ResizeObserver.
+ * @param ref An element ref
+ * @returns Dimensions of the element
+ */
+declare function useGridDimensions(ref: RefObject<HTMLElement | null>): GridDimensions;
+/**
+ * React hook for creating a meet-style responsive grid.
+ * @param options Grid options including dimensions, count, aspectRatio, gap, and layoutMode
+ * @returns Grid result with width, height, and position getter
+ */
+declare function useMeetGrid(options: MeetGridOptions): MeetGridResult;
+/**
+ * Hook to get animation configuration for Motion
+ */
+declare function useGridAnimation(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";
+};
+
+interface GridContainerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Children to render inside the grid */
+    children: ReactNode;
+    /** Aspect ratio in format "width:height" (e.g., "16:9") */
+    aspectRatio?: string;
+    /** Gap between items in pixels */
+    gap?: number;
+    /** Number of items (if not using GridItem children) */
+    count?: number;
+    /** Layout mode */
+    layoutMode?: LayoutMode;
+    /** Index of pinned/focused item (main participant for pin/spotlight 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';
+    /** Spring animation preset */
+    springPreset?: SpringPreset;
+    /** Custom container style */
+    style?: CSSProperties;
+    /** Additional class name */
+    className?: string;
+    /** 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 all items. With pin: limits "others". */
+    maxVisible?: number;
+    /** Current page for visible items (0-based), used when maxVisible > 0 */
+    currentVisiblePage?: number;
+    /**
+     * Per-item aspect ratio configurations.
+     * Use different ratios for mobile (9:16), desktop (16:9).
+     * @example ['16:9', '9:16', undefined]
+     */
+    itemAspectRatios?: (ItemAspectRatio | undefined)[];
+    /** Custom width for the floating PiP item in 2-person mode */
+    floatWidth?: number;
+    /** Custom height for the floating PiP item in 2-person mode */
+    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` for a ready-made 5-level responsive config.
+     * @example
+     * floatBreakpoints={DEFAULT_FLOAT_BREAKPOINTS}
+     * floatBreakpoints={[
+     *   { minWidth: 0, width: 80, height: 110 },
+     *   { minWidth: 600, width: 150, height: 200 },
+     * ]}
+     */
+    floatBreakpoints?: PipBreakpoint[];
+}
+/**
+ * Container component for the meet grid.
+ * Provides grid context to child GridItem components.
+ */
+declare const GridContainer: React__default.ForwardRefExoticComponent<GridContainerProps & React__default.RefAttributes<HTMLDivElement>>;
+interface GridItemProps extends Omit<HTMLMotionProps<'div'>, 'animate' | 'initial' | 'transition' | 'children'> {
+    /** Index of this item in the grid */
+    index: number;
+    /**
+     * Children to render inside the item.
+     * Can be a ReactNode or a render function that receives contentDimensions and visibility info.
+     * @example
+     * // Simple usage
+     * <GridItem index={0}><Video /></GridItem>
+     *
+     * // With contentDimensions for flexible aspect ratios
+     * <GridItem index={0}>
+     *   {({ contentDimensions }) => (
+     *     <Video style={{
+     *       width: contentDimensions.width,
+     *       height: contentDimensions.height,
+     *       marginTop: contentDimensions.offsetTop,
+     *       marginLeft: contentDimensions.offsetLeft
+     *     }} />
+     *   )}
+     * </GridItem>
+     *
+     * // With hidden count for '+X more' indicator
+     * <GridItem index={index}>
+     *   {({ isLastVisibleOther, hiddenCount }) => (
+     *     <div>
+     *       {isLastVisibleOther && hiddenCount > 0 && (
+     *         <span className="more-indicator">+{hiddenCount}</span>
+     *       )}
+     *     </div>
+     *   )}
+     * </GridItem>
+     */
+    children: ReactNode | ((props: {
+        contentDimensions: ContentDimensions;
+        /** True if this is the last visible item in the "others" section */
+        isLastVisibleOther: boolean;
+        /** Number of hidden items (for '+X more' indicator) */
+        hiddenCount: number;
+        /** True if this item is rendered as a floating PiP */
+        isFloat: boolean;
+    }) => ReactNode);
+    /** Optional item-specific aspect ratio (overrides itemAspectRatios from container) */
+    itemAspectRatio?: ItemAspectRatio;
+    /** Custom transition override */
+    transition?: Transition;
+    /** Whether to disable animations */
+    disableAnimation?: boolean;
+    /** Additional class name */
+    className?: string;
+    /** Custom style (merged with animated styles) */
+    style?: CSSProperties;
+}
+/**
+ * Grid item component with Motion animations.
+ * Automatically positions itself based on index in the grid.
+ * When the grid marks this item as float (2-person mode), renders as a draggable PiP.
+ */
+declare const GridItem: React__default.ForwardRefExoticComponent<Omit<GridItemProps, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
+interface FloatingGridItemProps extends Omit<HTMLMotionProps<'div'>, 'animate' | 'initial' | 'children'> {
+    /** Children to render inside the floating item */
+    children: ReactNode;
+    /** Width of the floating item (px). Overridden by `breakpoints` when provided. */
+    width?: number;
+    /** Height of the floating item (px). Overridden by `breakpoints` when provided. */
+    height?: number;
+    /**
+     * Responsive breakpoints for PiP sizing.
+     * When provided, width/height auto-adjust based on container width.
+     * Overrides the fixed `width`/`height` props.
+     * Use `DEFAULT_FLOAT_BREAKPOINTS` for a ready-made 5-level responsive config.
+     *
+     * @example
+     * // Use default responsive breakpoints
+     * breakpoints={DEFAULT_FLOAT_BREAKPOINTS}
+     *
+     * // Custom breakpoints
+     * breakpoints={[
+     *   { minWidth: 0, width: 80, height: 110 },
+     *   { minWidth: 600, width: 150, height: 200 },
+     *   { minWidth: 1200, width: 250, height: 330 },
+     * ]}
+     */
+    breakpoints?: PipBreakpoint[];
+    /** Initial position (x, y from container edges) */
+    initialPosition?: {
+        x: number;
+        y: number;
+    };
+    /** Which corner to anchor: 'top-left', 'top-right', 'bottom-left', 'bottom-right' */
+    anchor?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /** Whether the item is visible */
+    visible?: boolean;
+    /** Padding from container edges */
+    edgePadding?: number;
+    /** Callback when anchor changes after snap */
+    onAnchorChange?: (anchor: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right') => void;
+    /** Custom transition */
+    transition?: Transition;
+    /** Border radius */
+    borderRadius?: number;
+    /** Box shadow */
+    boxShadow?: string;
+    /** Additional class name */
+    className?: string;
+    /** Custom style */
+    style?: CSSProperties;
+}
+/**
+ * Floating Grid Item component that can be dragged around the screen.
+ * Snaps to the nearest corner when released (like iOS/Android PiP).
+ * Perfect for Picture-in-Picture style floating video in zoom mode.
+ */
+declare const FloatingGridItem: React__default.ForwardRefExoticComponent<Omit<FloatingGridItemProps, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
+interface GridOverlayProps extends HTMLAttributes<HTMLDivElement> {
+    /** Whether to show the overlay */
+    visible?: boolean;
+    /** Overlay background color */
+    backgroundColor?: string;
+}
+/**
+ * Overlay component for grid items (e.g., for muted indicator, name label)
+ */
+declare const GridOverlay: React__default.ForwardRefExoticComponent<GridOverlayProps & React__default.RefAttributes<HTMLDivElement>>;
+
+export { FloatingGridItem, GridContainer, GridContext, GridItem, GridOverlay, useGridAnimation, useGridContext, useGridDimensions, useMeetGrid };
+export type { FloatingGridItemProps, GridContainerProps, GridItemProps, GridOverlayProps };