Status: Experimental

widget-grid is a framework agnostic library for creating and manipulating widget grids.

📚 Examples

• ReactJs Basic

📖 Usage

const widgetGrid = createWidgetGrid<TPlaygroundContent>({
	cells: [
		['A', 'B', 'B'],
		['A', 'C', 'D'],
		['E', 'F', 'G']
	],
	widgets: [
		{ id: 'A', content: { type: 'item1' } },
		{ id: 'B', content: { type: 'item2' } },
		{ id: 'C', content: { type: 'item3' } },
		{ id: 'D', content: { type: 'item2' } },
		{ id: 'E', content: { type: 'item1' } },
		{ id: 'F', content: { type: 'item2' } },
		{ id: 'G', content: { type: 'item3' } }
	]
});

❓ FAQ

Why use a grid-based layout instead of item-based positioning?

Data Structure Comparison

Grid-Based Layout (Current):

{
    // O(1) access to any cell
    cells: [
        ['1', '1', '2'],
        ['1', '1', '2']
    ],
    // O(1) access to widget data
    items: {
        '1': { id: '1' },
        '2': { id: '2' }
    }
}

Item-Based Positioning (Alternative):

{
	// O(1) access to widget data
	items: [
		{
			id: '1',
			x: 0, // Requires collision detection
			y: 0,
			width: 2,
			height: 2
		},
		{ id: '2', x: 2, y: 0, width: 1, height: 2 }
	];
}

Key Advantages of Grid-Based Layout

1. Performance Characteristics

   • Grid Operations: O(n) where n = cells in affected region
   • Partial Updates: Only recompute affected grid areas
   • Initial Load: Can render skeleton layout immediately (and load visible widgets first)
   • Memory: Compact representation of layout

2. Safety & Validation

   • Grid structure prevents invalid states by design
   • Implicit validation through grid structure
   • Predictable widget boundaries

3. Developer Experience (DX)

   • Visual representation matches code structure
   • Clear separation of layout and widget data

When to Choose Item-Based?

Consider item-based positioning when you need:

• Free-form layouts without grid constraints
• Complex widget interactions (rotation, scaling)

If its not structured and predictable, you should probably use item-based positioning.

Why Grid-Based Works for Us

• Structured, predictable layouts
• High performance with many widgets (since it's basically a list of widgets)

💡 Resources / References

• Bento.me
• Swapy