@thangdevalone/meet-layout-grid-core 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# @meet-layout-grid/core
+
+Core grid calculation logic for meet-layout-grid library. Zero dependencies, framework-agnostic.
+
+## Installation
+
+```bash
+npm install @meet-layout-grid/core
+```
+
+## Usage
+
+```typescript
+import { createMeetGrid, createGrid } from '@meet-layout-grid/core'
+
+// Basic grid
+const grid = createGrid({
+  dimensions: { width: 800, height: 600 },
+  count: 6,
+  aspectRatio: '16:9',
+  gap: 8,
+})
+
+console.log(`Item size: ${grid.width}x${grid.height}`)
+console.log(`Grid: ${grid.cols} cols, ${grid.rows} rows`)
+
+// Position each item
+for (let i = 0; i < 6; i++) {
+  const { top, left } = grid.getPosition(i)
+  console.log(`Item ${i}: top=${top}, left=${left}`)
+}
+
+// Meet-style grid with layout modes
+const meetGrid = createMeetGrid({
+  dimensions: { width: 800, height: 600 },
+  count: 6,
+  aspectRatio: '16:9',
+  gap: 8,
+  layoutMode: 'speaker', // 'gallery' | 'speaker' | 'spotlight' | 'sidebar'
+  speakerIndex: 0,
+})
+
+// Items may have different sizes in speaker mode
+for (let i = 0; i < 6; i++) {
+  const { width, height } = meetGrid.getItemDimensions(i)
+  const isMain = meetGrid.isMainItem(i)
+  console.log(`Item ${i}: ${width}x${height}, main: ${isMain}`)
+}
+```
+
+## API
+
+### `createGrid(options)`
+
+Creates a basic responsive grid.
+
+**Options:**
+- `dimensions: { width, height }` - Container dimensions
+- `count: number` - Number of items
+- `aspectRatio: string` - Aspect ratio (e.g., "16:9")
+- `gap: number` - Gap between items in pixels
+
+**Returns:**
+- `width: number` - Item width
+- `height: number` - Item height
+- `rows: number` - Number of rows
+- `cols: number` - Number of columns
+- `getPosition(index): { top, left }` - Position getter
+
+### `createMeetGrid(options)`
+
+Creates a meet-style grid with layout modes.
+
+**Additional Options:**
+- `layoutMode: 'gallery' | 'speaker' | 'spotlight' | 'sidebar'`
+- `pinnedIndex?: number` - Index of pinned item
+- `speakerIndex?: number` - Index of active speaker
+- `sidebarPosition?: 'left' | 'right' | 'bottom'`
+- `sidebarRatio?: number` - Sidebar width ratio (0-1)
+
+**Additional Returns:**
+- `layoutMode: LayoutMode` - Current layout mode
+- `getItemDimensions(index): { width, height }` - Per-item dimensions
+- `isMainItem(index): boolean` - Check if item is featured
+
+## Layout Modes
+
+- **Gallery** - Equal-sized tiles in a responsive grid
+- **Speaker** - Active speaker takes larger space (65% height)
+- **Spotlight** - Single participant in focus, others hidden
+- **Sidebar** - Main view with thumbnail strip
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,349 @@
+'use strict';
+
+function getAspectRatio(ratio) {
+  const [width, height] = ratio.split(":");
+  if (!width || !height) {
+    throw new Error(
+      'meet-layout-grid: Invalid aspect ratio provided, expected format is "width:height".'
+    );
+  }
+  return Number.parseInt(height) / Number.parseInt(width);
+}
+function parseAspectRatio(ratio) {
+  const [width, height] = ratio.split(":").map(Number);
+  if (!width || !height || isNaN(width) || isNaN(height)) {
+    throw new Error(
+      'meet-layout-grid: Invalid aspect ratio provided, expected format is "width:height".'
+    );
+  }
+  return { widthRatio: width, heightRatio: height };
+}
+function getGridItemDimensions({
+  count,
+  dimensions,
+  aspectRatio,
+  gap
+}) {
+  let { width: W, height: H } = dimensions;
+  if (W === 0 || H === 0 || count === 0) {
+    return { width: 0, height: 0, rows: 1, cols: 1 };
+  }
+  W -= gap * 2;
+  H -= gap * 2;
+  const s = gap;
+  const N = count;
+  const r = getAspectRatio(aspectRatio);
+  let w = 0;
+  let h = 0;
+  let a = 1;
+  let b = 1;
+  const widths = [];
+  for (let n = 1; n <= N; n++) {
+    widths.push((W - s * (n - 1)) / n, (H - s * (n - 1)) / (n * r));
+  }
+  widths.sort((a2, b2) => b2 - a2);
+  for (const width of widths) {
+    w = width;
+    h = w * r;
+    a = Math.floor((W + s) / (w + s));
+    b = Math.floor((H + s) / (h + s));
+    if (a * b >= N) {
+      a = Math.ceil(N / b);
+      b = Math.ceil(N / a);
+      break;
+    }
+  }
+  return { width: w, height: h, rows: b, cols: a };
+}
+function createGridItemPositioner({
+  parentDimensions,
+  dimensions,
+  rows,
+  cols,
+  count,
+  gap
+}) {
+  const { width: W, height: H } = parentDimensions;
+  const { width: w, height: h } = dimensions;
+  const firstTop = (H - (h * rows + (rows - 1) * gap)) / 2;
+  let firstLeft = (W - (w * cols + (cols - 1) * gap)) / 2;
+  const topAdd = h + gap;
+  const leftAdd = w + gap;
+  let col = 0;
+  let row = 0;
+  const incompleteRowCols = count % cols;
+  function getPosition(index) {
+    const remaining = count - index;
+    if (remaining === incompleteRowCols && incompleteRowCols > 0) {
+      firstLeft = (W - (w * remaining + (remaining - 1) * gap)) / 2;
+    }
+    const top = firstTop + row * topAdd;
+    const left = firstLeft + col * leftAdd;
+    col++;
+    if ((index + 1) % cols === 0) {
+      row++;
+      col = 0;
+    }
+    return { top, left };
+  }
+  return getPosition;
+}
+function createGrid({ aspectRatio, count, dimensions, gap }) {
+  const { width, height, rows, cols } = getGridItemDimensions({
+    aspectRatio,
+    count,
+    dimensions,
+    gap
+  });
+  const getPosition = createGridItemPositioner({
+    parentDimensions: dimensions,
+    dimensions: { width, height },
+    rows,
+    cols,
+    count,
+    gap
+  });
+  return {
+    width,
+    height,
+    rows,
+    cols,
+    getPosition
+  };
+}
+function createSidebarGrid(options) {
+  const { dimensions, gap, aspectRatio, count, sidebarPosition = "right", sidebarRatio = 0.25, pinnedIndex = 0 } = options;
+  if (count === 0) {
+    return createEmptyMeetGridResult("sidebar");
+  }
+  const { width: W, height: H } = dimensions;
+  const ratio = getAspectRatio(aspectRatio);
+  const isVertical = sidebarPosition === "bottom";
+  let mainWidth;
+  let mainHeight;
+  let sidebarWidth;
+  let sidebarHeight;
+  if (isVertical) {
+    mainHeight = H * (1 - sidebarRatio) - gap;
+    mainWidth = W - gap * 2;
+    sidebarHeight = H * sidebarRatio - gap;
+    sidebarWidth = W - gap * 2;
+  } else {
+    mainWidth = W * (1 - sidebarRatio) - gap * 2;
+    mainHeight = H - gap * 2;
+    sidebarWidth = W * sidebarRatio - gap;
+    sidebarHeight = H - gap * 2;
+  }
+  let mainItemWidth = mainWidth;
+  let mainItemHeight = mainItemWidth * ratio;
+  if (mainItemHeight > mainHeight) {
+    mainItemHeight = mainHeight;
+    mainItemWidth = mainItemHeight / ratio;
+  }
+  const sidebarCount = count - 1;
+  let thumbWidth;
+  let thumbHeight;
+  if (sidebarCount > 0) {
+    if (isVertical) {
+      thumbWidth = Math.min((sidebarWidth - (sidebarCount - 1) * gap) / sidebarCount, sidebarHeight / ratio);
+      thumbHeight = thumbWidth * ratio;
+    } else {
+      thumbHeight = Math.min((sidebarHeight - (sidebarCount - 1) * gap) / sidebarCount, sidebarWidth / ratio);
+      thumbWidth = thumbHeight / ratio;
+    }
+  } else {
+    thumbWidth = 0;
+    thumbHeight = 0;
+  }
+  const positions = [];
+  const mainLeft = isVertical ? gap + (mainWidth - mainItemWidth) / 2 : sidebarPosition === "left" ? sidebarWidth + gap * 2 + (mainWidth - mainItemWidth) / 2 : gap + (mainWidth - mainItemWidth) / 2;
+  const mainTop = isVertical ? gap + (mainHeight - mainItemHeight) / 2 : gap + (mainHeight - mainItemHeight) / 2;
+  positions[pinnedIndex] = {
+    position: { top: mainTop, left: mainLeft },
+    dimensions: { width: mainItemWidth, height: mainItemHeight }
+  };
+  let sidebarIndex = 0;
+  for (let i = 0; i < count; i++) {
+    if (i === pinnedIndex)
+      continue;
+    let left;
+    let top;
+    if (isVertical) {
+      const totalThumbWidth = sidebarCount * thumbWidth + (sidebarCount - 1) * gap;
+      const startLeft = gap + (sidebarWidth - totalThumbWidth) / 2;
+      left = startLeft + sidebarIndex * (thumbWidth + gap);
+      top = mainHeight + gap * 2;
+    } else {
+      left = sidebarPosition === "left" ? gap : mainWidth + gap * 2;
+      const totalThumbHeight = sidebarCount * thumbHeight + (sidebarCount - 1) * gap;
+      const startTop = gap + (sidebarHeight - totalThumbHeight) / 2;
+      top = startTop + sidebarIndex * (thumbHeight + gap);
+    }
+    positions[i] = {
+      position: { top, left },
+      dimensions: { width: thumbWidth, height: thumbHeight }
+    };
+    sidebarIndex++;
+  }
+  return {
+    width: mainItemWidth,
+    height: mainItemHeight,
+    rows: isVertical ? 2 : 1,
+    cols: isVertical ? 1 : 2,
+    layoutMode: "sidebar",
+    getPosition: (index) => positions[index]?.position ?? { top: 0, left: 0 },
+    getItemDimensions: (index) => positions[index]?.dimensions ?? { width: 0, height: 0 },
+    isMainItem: (index) => index === pinnedIndex
+  };
+}
+function createSpeakerGrid(options) {
+  const { dimensions, gap, aspectRatio, count, speakerIndex = 0 } = options;
+  if (count === 0) {
+    return createEmptyMeetGridResult("speaker");
+  }
+  if (count === 1) {
+    const grid = createGrid({ ...options, count: 1 });
+    return {
+      ...grid,
+      layoutMode: "speaker",
+      getItemDimensions: () => ({ width: grid.width, height: grid.height }),
+      isMainItem: () => true
+    };
+  }
+  const { width: W, height: H } = dimensions;
+  const ratio = getAspectRatio(aspectRatio);
+  const speakerHeight = (H - gap * 3) * 0.65;
+  const othersHeight = (H - gap * 3) * 0.35;
+  let speakerW = W - gap * 2;
+  let speakerH = speakerW * ratio;
+  if (speakerH > speakerHeight) {
+    speakerH = speakerHeight;
+    speakerW = speakerH / ratio;
+  }
+  const othersCount = count - 1;
+  let otherW = Math.min((W - gap * 2 - (othersCount - 1) * gap) / othersCount, othersHeight / ratio);
+  let otherH = otherW * ratio;
+  if (otherH > othersHeight) {
+    otherH = othersHeight;
+    otherW = otherH / ratio;
+  }
+  const positions = [];
+  positions[speakerIndex] = {
+    position: {
+      top: gap + (speakerHeight - speakerH) / 2,
+      left: gap + (W - gap * 2 - speakerW) / 2
+    },
+    dimensions: { width: speakerW, height: speakerH }
+  };
+  const totalOthersWidth = othersCount * otherW + (othersCount - 1) * gap;
+  const startLeft = gap + (W - gap * 2 - totalOthersWidth) / 2;
+  let otherIndex = 0;
+  for (let i = 0; i < count; i++) {
+    if (i === speakerIndex)
+      continue;
+    positions[i] = {
+      position: {
+        top: speakerHeight + gap * 2 + (othersHeight - otherH) / 2,
+        left: startLeft + otherIndex * (otherW + gap)
+      },
+      dimensions: { width: otherW, height: otherH }
+    };
+    otherIndex++;
+  }
+  return {
+    width: speakerW,
+    height: speakerH,
+    rows: 2,
+    cols: othersCount,
+    layoutMode: "speaker",
+    getPosition: (index) => positions[index]?.position ?? { top: 0, left: 0 },
+    getItemDimensions: (index) => positions[index]?.dimensions ?? { width: 0, height: 0 },
+    isMainItem: (index) => index === speakerIndex
+  };
+}
+function createSpotlightGrid(options) {
+  const { dimensions, gap, aspectRatio, pinnedIndex = 0 } = options;
+  const { width: W, height: H } = dimensions;
+  const ratio = getAspectRatio(aspectRatio);
+  let spotWidth = W - gap * 2;
+  let spotHeight = spotWidth * ratio;
+  if (spotHeight > H - gap * 2) {
+    spotHeight = H - gap * 2;
+    spotWidth = spotHeight / ratio;
+  }
+  const position = {
+    top: gap + (H - gap * 2 - spotHeight) / 2,
+    left: gap + (W - gap * 2 - spotWidth) / 2
+  };
+  return {
+    width: spotWidth,
+    height: spotHeight,
+    rows: 1,
+    cols: 1,
+    layoutMode: "spotlight",
+    getPosition: (index) => index === pinnedIndex ? position : { top: -9999, left: -9999 },
+    getItemDimensions: (index) => index === pinnedIndex ? { width: spotWidth, height: spotHeight } : { width: 0, height: 0 },
+    isMainItem: (index) => index === pinnedIndex
+  };
+}
+function createEmptyMeetGridResult(layoutMode) {
+  return {
+    width: 0,
+    height: 0,
+    rows: 0,
+    cols: 0,
+    layoutMode,
+    getPosition: () => ({ top: 0, left: 0 }),
+    getItemDimensions: () => ({ width: 0, height: 0 }),
+    isMainItem: () => false
+  };
+}
+function createMeetGrid(options) {
+  const { layoutMode = "gallery", count } = options;
+  if (count === 0) {
+    return createEmptyMeetGridResult(layoutMode);
+  }
+  switch (layoutMode) {
+    case "spotlight":
+      return createSpotlightGrid(options);
+    case "speaker":
+      return createSpeakerGrid(options);
+    case "sidebar":
+      return createSidebarGrid(options);
+    case "gallery":
+    default: {
+      const grid = createGrid(options);
+      return {
+        ...grid,
+        layoutMode: "gallery",
+        getItemDimensions: () => ({ width: grid.width, height: grid.height }),
+        isMainItem: () => false
+      };
+    }
+  }
+}
+const springPresets = {
+  /** Snappy animations for UI interactions */
+  snappy: { stiffness: 400, damping: 30 },
+  /** Smooth animations for layout changes */
+  smooth: { stiffness: 300, damping: 30 },
+  /** Gentle animations for subtle effects */
+  gentle: { stiffness: 200, damping: 25 },
+  /** Bouncy animations for playful effects */
+  bouncy: { stiffness: 400, damping: 15 }
+};
+function getSpringConfig(preset = "smooth") {
+  return {
+    type: "spring",
+    ...springPresets[preset]
+  };
+}
+
+exports.createGrid = createGrid;
+exports.createGridItemPositioner = createGridItemPositioner;
+exports.createMeetGrid = createMeetGrid;
+exports.getAspectRatio = getAspectRatio;
+exports.getGridItemDimensions = getGridItemDimensions;
+exports.getSpringConfig = getSpringConfig;
+exports.parseAspectRatio = parseAspectRatio;
+exports.springPresets = springPresets;

package/dist/index.d.cts

@@ -0,0 +1,168 @@
+/**
+ * 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: Equal-sized tiles in a responsive grid
+ * - speaker: Active speaker takes larger space (2x size)
+ * - spotlight: Single participant in focus, others hidden
+ * - sidebar: Main view with thumbnail strip on the side
+ */
+type LayoutMode = 'gallery' | 'speaker' | 'spotlight' | 'sidebar';
+/**
+ * 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;
+}
+/**
+ * Extended options for meet-style grid with layout modes
+ */
+interface MeetGridOptions extends GridOptions {
+    /** Layout mode for the grid */
+    layoutMode?: LayoutMode;
+    /** Index of pinned item (for speaker/spotlight modes) */
+    pinnedIndex?: number;
+    /** Index of active speaker */
+    speakerIndex?: number;
+    /** Sidebar position (for sidebar mode) */
+    sidebarPosition?: 'left' | 'right' | 'bottom';
+    /** Sidebar width ratio (0-1) */
+    sidebarRatio?: 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;
+}
+/**
+ * Extended result for meet-style grid
+ */
+interface MeetGridResult extends GridResult {
+    /** Layout mode used */
+    layoutMode: LayoutMode;
+    /** Get item dimensions (may vary by index in some modes) */
+    getItemDimensions: (index: number) => GridDimensions;
+    /** Check if item is the main/featured item */
+    isMainItem: (index: number) => boolean;
+}
+/**
+ * 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;
+};
+/**
+ * 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 { createGrid, createGridItemPositioner, createMeetGrid, getAspectRatio, getGridItemDimensions, getSpringConfig, parseAspectRatio, springPresets };
+export type { GridDimensions, GridOptions, GridResult, LayoutMode, MeetGridOptions, MeetGridResult, Position, SpringPreset };

package/dist/index.d.mts

@@ -0,0 +1,168 @@
+/**
+ * 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: Equal-sized tiles in a responsive grid
+ * - speaker: Active speaker takes larger space (2x size)
+ * - spotlight: Single participant in focus, others hidden
+ * - sidebar: Main view with thumbnail strip on the side
+ */
+type LayoutMode = 'gallery' | 'speaker' | 'spotlight' | 'sidebar';
+/**
+ * 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;
+}
+/**
+ * Extended options for meet-style grid with layout modes
+ */
+interface MeetGridOptions extends GridOptions {
+    /** Layout mode for the grid */
+    layoutMode?: LayoutMode;
+    /** Index of pinned item (for speaker/spotlight modes) */
+    pinnedIndex?: number;
+    /** Index of active speaker */
+    speakerIndex?: number;
+    /** Sidebar position (for sidebar mode) */
+    sidebarPosition?: 'left' | 'right' | 'bottom';
+    /** Sidebar width ratio (0-1) */
+    sidebarRatio?: 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;
+}
+/**
+ * Extended result for meet-style grid
+ */
+interface MeetGridResult extends GridResult {
+    /** Layout mode used */
+    layoutMode: LayoutMode;
+    /** Get item dimensions (may vary by index in some modes) */
+    getItemDimensions: (index: number) => GridDimensions;
+    /** Check if item is the main/featured item */
+    isMainItem: (index: number) => boolean;
+}
+/**
+ * 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;
+};
+/**
+ * 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 { createGrid, createGridItemPositioner, createMeetGrid, getAspectRatio, getGridItemDimensions, getSpringConfig, parseAspectRatio, springPresets };
+export type { GridDimensions, GridOptions, GridResult, LayoutMode, MeetGridOptions, MeetGridResult, Position, SpringPreset };

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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: Equal-sized tiles in a responsive grid
+ * - speaker: Active speaker takes larger space (2x size)
+ * - spotlight: Single participant in focus, others hidden
+ * - sidebar: Main view with thumbnail strip on the side
+ */
+type LayoutMode = 'gallery' | 'speaker' | 'spotlight' | 'sidebar';
+/**
+ * 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;
+}
+/**
+ * Extended options for meet-style grid with layout modes
+ */
+interface MeetGridOptions extends GridOptions {
+    /** Layout mode for the grid */
+    layoutMode?: LayoutMode;
+    /** Index of pinned item (for speaker/spotlight modes) */
+    pinnedIndex?: number;
+    /** Index of active speaker */
+    speakerIndex?: number;
+    /** Sidebar position (for sidebar mode) */
+    sidebarPosition?: 'left' | 'right' | 'bottom';
+    /** Sidebar width ratio (0-1) */
+    sidebarRatio?: 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;
+}
+/**
+ * Extended result for meet-style grid
+ */
+interface MeetGridResult extends GridResult {
+    /** Layout mode used */
+    layoutMode: LayoutMode;
+    /** Get item dimensions (may vary by index in some modes) */
+    getItemDimensions: (index: number) => GridDimensions;
+    /** Check if item is the main/featured item */
+    isMainItem: (index: number) => boolean;
+}
+/**
+ * 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;
+};
+/**
+ * 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 { createGrid, createGridItemPositioner, createMeetGrid, getAspectRatio, getGridItemDimensions, getSpringConfig, parseAspectRatio, springPresets };
+export type { GridDimensions, GridOptions, GridResult, LayoutMode, MeetGridOptions, MeetGridResult, Position, SpringPreset };

package/dist/index.mjs

@@ -0,0 +1,340 @@
+function getAspectRatio(ratio) {
+  const [width, height] = ratio.split(":");
+  if (!width || !height) {
+    throw new Error(
+      'meet-layout-grid: Invalid aspect ratio provided, expected format is "width:height".'
+    );
+  }
+  return Number.parseInt(height) / Number.parseInt(width);
+}
+function parseAspectRatio(ratio) {
+  const [width, height] = ratio.split(":").map(Number);
+  if (!width || !height || isNaN(width) || isNaN(height)) {
+    throw new Error(
+      'meet-layout-grid: Invalid aspect ratio provided, expected format is "width:height".'
+    );
+  }
+  return { widthRatio: width, heightRatio: height };
+}
+function getGridItemDimensions({
+  count,
+  dimensions,
+  aspectRatio,
+  gap
+}) {
+  let { width: W, height: H } = dimensions;
+  if (W === 0 || H === 0 || count === 0) {
+    return { width: 0, height: 0, rows: 1, cols: 1 };
+  }
+  W -= gap * 2;
+  H -= gap * 2;
+  const s = gap;
+  const N = count;
+  const r = getAspectRatio(aspectRatio);
+  let w = 0;
+  let h = 0;
+  let a = 1;
+  let b = 1;
+  const widths = [];
+  for (let n = 1; n <= N; n++) {
+    widths.push((W - s * (n - 1)) / n, (H - s * (n - 1)) / (n * r));
+  }
+  widths.sort((a2, b2) => b2 - a2);
+  for (const width of widths) {
+    w = width;
+    h = w * r;
+    a = Math.floor((W + s) / (w + s));
+    b = Math.floor((H + s) / (h + s));
+    if (a * b >= N) {
+      a = Math.ceil(N / b);
+      b = Math.ceil(N / a);
+      break;
+    }
+  }
+  return { width: w, height: h, rows: b, cols: a };
+}
+function createGridItemPositioner({
+  parentDimensions,
+  dimensions,
+  rows,
+  cols,
+  count,
+  gap
+}) {
+  const { width: W, height: H } = parentDimensions;
+  const { width: w, height: h } = dimensions;
+  const firstTop = (H - (h * rows + (rows - 1) * gap)) / 2;
+  let firstLeft = (W - (w * cols + (cols - 1) * gap)) / 2;
+  const topAdd = h + gap;
+  const leftAdd = w + gap;
+  let col = 0;
+  let row = 0;
+  const incompleteRowCols = count % cols;
+  function getPosition(index) {
+    const remaining = count - index;
+    if (remaining === incompleteRowCols && incompleteRowCols > 0) {
+      firstLeft = (W - (w * remaining + (remaining - 1) * gap)) / 2;
+    }
+    const top = firstTop + row * topAdd;
+    const left = firstLeft + col * leftAdd;
+    col++;
+    if ((index + 1) % cols === 0) {
+      row++;
+      col = 0;
+    }
+    return { top, left };
+  }
+  return getPosition;
+}
+function createGrid({ aspectRatio, count, dimensions, gap }) {
+  const { width, height, rows, cols } = getGridItemDimensions({
+    aspectRatio,
+    count,
+    dimensions,
+    gap
+  });
+  const getPosition = createGridItemPositioner({
+    parentDimensions: dimensions,
+    dimensions: { width, height },
+    rows,
+    cols,
+    count,
+    gap
+  });
+  return {
+    width,
+    height,
+    rows,
+    cols,
+    getPosition
+  };
+}
+function createSidebarGrid(options) {
+  const { dimensions, gap, aspectRatio, count, sidebarPosition = "right", sidebarRatio = 0.25, pinnedIndex = 0 } = options;
+  if (count === 0) {
+    return createEmptyMeetGridResult("sidebar");
+  }
+  const { width: W, height: H } = dimensions;
+  const ratio = getAspectRatio(aspectRatio);
+  const isVertical = sidebarPosition === "bottom";
+  let mainWidth;
+  let mainHeight;
+  let sidebarWidth;
+  let sidebarHeight;
+  if (isVertical) {
+    mainHeight = H * (1 - sidebarRatio) - gap;
+    mainWidth = W - gap * 2;
+    sidebarHeight = H * sidebarRatio - gap;
+    sidebarWidth = W - gap * 2;
+  } else {
+    mainWidth = W * (1 - sidebarRatio) - gap * 2;
+    mainHeight = H - gap * 2;
+    sidebarWidth = W * sidebarRatio - gap;
+    sidebarHeight = H - gap * 2;
+  }
+  let mainItemWidth = mainWidth;
+  let mainItemHeight = mainItemWidth * ratio;
+  if (mainItemHeight > mainHeight) {
+    mainItemHeight = mainHeight;
+    mainItemWidth = mainItemHeight / ratio;
+  }
+  const sidebarCount = count - 1;
+  let thumbWidth;
+  let thumbHeight;
+  if (sidebarCount > 0) {
+    if (isVertical) {
+      thumbWidth = Math.min((sidebarWidth - (sidebarCount - 1) * gap) / sidebarCount, sidebarHeight / ratio);
+      thumbHeight = thumbWidth * ratio;
+    } else {
+      thumbHeight = Math.min((sidebarHeight - (sidebarCount - 1) * gap) / sidebarCount, sidebarWidth / ratio);
+      thumbWidth = thumbHeight / ratio;
+    }
+  } else {
+    thumbWidth = 0;
+    thumbHeight = 0;
+  }
+  const positions = [];
+  const mainLeft = isVertical ? gap + (mainWidth - mainItemWidth) / 2 : sidebarPosition === "left" ? sidebarWidth + gap * 2 + (mainWidth - mainItemWidth) / 2 : gap + (mainWidth - mainItemWidth) / 2;
+  const mainTop = isVertical ? gap + (mainHeight - mainItemHeight) / 2 : gap + (mainHeight - mainItemHeight) / 2;
+  positions[pinnedIndex] = {
+    position: { top: mainTop, left: mainLeft },
+    dimensions: { width: mainItemWidth, height: mainItemHeight }
+  };
+  let sidebarIndex = 0;
+  for (let i = 0; i < count; i++) {
+    if (i === pinnedIndex)
+      continue;
+    let left;
+    let top;
+    if (isVertical) {
+      const totalThumbWidth = sidebarCount * thumbWidth + (sidebarCount - 1) * gap;
+      const startLeft = gap + (sidebarWidth - totalThumbWidth) / 2;
+      left = startLeft + sidebarIndex * (thumbWidth + gap);
+      top = mainHeight + gap * 2;
+    } else {
+      left = sidebarPosition === "left" ? gap : mainWidth + gap * 2;
+      const totalThumbHeight = sidebarCount * thumbHeight + (sidebarCount - 1) * gap;
+      const startTop = gap + (sidebarHeight - totalThumbHeight) / 2;
+      top = startTop + sidebarIndex * (thumbHeight + gap);
+    }
+    positions[i] = {
+      position: { top, left },
+      dimensions: { width: thumbWidth, height: thumbHeight }
+    };
+    sidebarIndex++;
+  }
+  return {
+    width: mainItemWidth,
+    height: mainItemHeight,
+    rows: isVertical ? 2 : 1,
+    cols: isVertical ? 1 : 2,
+    layoutMode: "sidebar",
+    getPosition: (index) => positions[index]?.position ?? { top: 0, left: 0 },
+    getItemDimensions: (index) => positions[index]?.dimensions ?? { width: 0, height: 0 },
+    isMainItem: (index) => index === pinnedIndex
+  };
+}
+function createSpeakerGrid(options) {
+  const { dimensions, gap, aspectRatio, count, speakerIndex = 0 } = options;
+  if (count === 0) {
+    return createEmptyMeetGridResult("speaker");
+  }
+  if (count === 1) {
+    const grid = createGrid({ ...options, count: 1 });
+    return {
+      ...grid,
+      layoutMode: "speaker",
+      getItemDimensions: () => ({ width: grid.width, height: grid.height }),
+      isMainItem: () => true
+    };
+  }
+  const { width: W, height: H } = dimensions;
+  const ratio = getAspectRatio(aspectRatio);
+  const speakerHeight = (H - gap * 3) * 0.65;
+  const othersHeight = (H - gap * 3) * 0.35;
+  let speakerW = W - gap * 2;
+  let speakerH = speakerW * ratio;
+  if (speakerH > speakerHeight) {
+    speakerH = speakerHeight;
+    speakerW = speakerH / ratio;
+  }
+  const othersCount = count - 1;
+  let otherW = Math.min((W - gap * 2 - (othersCount - 1) * gap) / othersCount, othersHeight / ratio);
+  let otherH = otherW * ratio;
+  if (otherH > othersHeight) {
+    otherH = othersHeight;
+    otherW = otherH / ratio;
+  }
+  const positions = [];
+  positions[speakerIndex] = {
+    position: {
+      top: gap + (speakerHeight - speakerH) / 2,
+      left: gap + (W - gap * 2 - speakerW) / 2
+    },
+    dimensions: { width: speakerW, height: speakerH }
+  };
+  const totalOthersWidth = othersCount * otherW + (othersCount - 1) * gap;
+  const startLeft = gap + (W - gap * 2 - totalOthersWidth) / 2;
+  let otherIndex = 0;
+  for (let i = 0; i < count; i++) {
+    if (i === speakerIndex)
+      continue;
+    positions[i] = {
+      position: {
+        top: speakerHeight + gap * 2 + (othersHeight - otherH) / 2,
+        left: startLeft + otherIndex * (otherW + gap)
+      },
+      dimensions: { width: otherW, height: otherH }
+    };
+    otherIndex++;
+  }
+  return {
+    width: speakerW,
+    height: speakerH,
+    rows: 2,
+    cols: othersCount,
+    layoutMode: "speaker",
+    getPosition: (index) => positions[index]?.position ?? { top: 0, left: 0 },
+    getItemDimensions: (index) => positions[index]?.dimensions ?? { width: 0, height: 0 },
+    isMainItem: (index) => index === speakerIndex
+  };
+}
+function createSpotlightGrid(options) {
+  const { dimensions, gap, aspectRatio, pinnedIndex = 0 } = options;
+  const { width: W, height: H } = dimensions;
+  const ratio = getAspectRatio(aspectRatio);
+  let spotWidth = W - gap * 2;
+  let spotHeight = spotWidth * ratio;
+  if (spotHeight > H - gap * 2) {
+    spotHeight = H - gap * 2;
+    spotWidth = spotHeight / ratio;
+  }
+  const position = {
+    top: gap + (H - gap * 2 - spotHeight) / 2,
+    left: gap + (W - gap * 2 - spotWidth) / 2
+  };
+  return {
+    width: spotWidth,
+    height: spotHeight,
+    rows: 1,
+    cols: 1,
+    layoutMode: "spotlight",
+    getPosition: (index) => index === pinnedIndex ? position : { top: -9999, left: -9999 },
+    getItemDimensions: (index) => index === pinnedIndex ? { width: spotWidth, height: spotHeight } : { width: 0, height: 0 },
+    isMainItem: (index) => index === pinnedIndex
+  };
+}
+function createEmptyMeetGridResult(layoutMode) {
+  return {
+    width: 0,
+    height: 0,
+    rows: 0,
+    cols: 0,
+    layoutMode,
+    getPosition: () => ({ top: 0, left: 0 }),
+    getItemDimensions: () => ({ width: 0, height: 0 }),
+    isMainItem: () => false
+  };
+}
+function createMeetGrid(options) {
+  const { layoutMode = "gallery", count } = options;
+  if (count === 0) {
+    return createEmptyMeetGridResult(layoutMode);
+  }
+  switch (layoutMode) {
+    case "spotlight":
+      return createSpotlightGrid(options);
+    case "speaker":
+      return createSpeakerGrid(options);
+    case "sidebar":
+      return createSidebarGrid(options);
+    case "gallery":
+    default: {
+      const grid = createGrid(options);
+      return {
+        ...grid,
+        layoutMode: "gallery",
+        getItemDimensions: () => ({ width: grid.width, height: grid.height }),
+        isMainItem: () => false
+      };
+    }
+  }
+}
+const springPresets = {
+  /** Snappy animations for UI interactions */
+  snappy: { stiffness: 400, damping: 30 },
+  /** Smooth animations for layout changes */
+  smooth: { stiffness: 300, damping: 30 },
+  /** Gentle animations for subtle effects */
+  gentle: { stiffness: 200, damping: 25 },
+  /** Bouncy animations for playful effects */
+  bouncy: { stiffness: 400, damping: 15 }
+};
+function getSpringConfig(preset = "smooth") {
+  return {
+    type: "spring",
+    ...springPresets[preset]
+  };
+}
+
+export { createGrid, createGridItemPositioner, createMeetGrid, getAspectRatio, getGridItemDimensions, getSpringConfig, parseAspectRatio, springPresets };

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@thangdevalone/meet-layout-grid-core",
+    "version": "1.0.0",
+    "description": "Core grid calculation logic for meet-layout-grid",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.mts",
+                "default": "./dist/index.mjs"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "unbuild",
+        "dev": "unbuild --watch",
+        "clean": "rimraf dist",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "keywords": [
+        "grid",
+        "responsive",
+        "meeting",
+        "video",
+        "layout"
+    ],
+    "author": "ThangDevAlone",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/thangdevalone/meet-layout-grid"
+    },
+    "devDependencies": {
+        "unbuild": "^2.0.0",
+        "vitest": "^1.0.0",
+        "rimraf": "^5.0.0"
+    }
+}