🎡 v 0.1.0

.github/workflows/lint.yml

@@ -0,0 +1,35 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  run-linters:
+    name: Run linters
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          cache: 'yarn'
+
+      - name: Setup yarn
+        run: npm install -g yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run linte
+        run: yarn lint

.github/workflows/test.yaml

@@ -0,0 +1,35 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          cache: 'yarn'
+
+      - name: Setup yarn
+        run: npm install -g yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run tests
+        run: yarn test

.prettierignore

@@ -6,6 +6,7 @@ node_modules
 .env
 .env.*
 !.env.example
+/coverage
 
 # Ignore files for PNPM, NPM and YARN
 pnpm-lock.yaml

README.md

@@ -30,24 +30,77 @@ pnpm install svelte-grid-extended
 
 ## Props
 
-List of all available props:
-
-| prop     | description                                                                        | type                                                              | default  |
-| -------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------- |
-| cols     | Grid columns count. If set to 0, grid will grow infinitly. Must be >= 0.           | number                                                            | 0        |
-| rows     | Grid rows count. If set to 0, grid will grow infinitly. Must be >= 0.              | number                                                            | 0        |
-| itemSize | Size of the grid item. If not set, grid will calculate it based on container size. | { width?: number, height?: number }                               | {}       |
-| items    | Array of grid items.                                                               | Array<{ id: string, x: number, y: number, w: number, h: number }> | requried |
-| gap      | Gap between grid items.                                                            | number                                                            | 10       |
-| bounds   | Should grid items be bounded by the grid container.                                | boolean                                                           | false    |
+### Main props
+
+| prop     | description                                                                        | type                                | default  |
+| -------- | ---------------------------------------------------------------------------------- | ----------------------------------- | -------- |
+| cols     | Grid columns count. If set to 0, grid will grow infinitly. Must be >= 0.           | number                              | 0        |
+| rows     | Grid rows count. If set to 0, grid will grow infinitly. Must be >= 0.              | number                              | 0        |
+| itemSize | Size of the grid item. If not set, grid will calculate it based on container size. | { width?: number, height?: number } | {}       |
+| items    | Array of grid items.                                                               | [Layout\<T\>](#layout-type)         | requried |
+| gap      | Gap between grid items.                                                            | number                              | 10       |
+| bounds   | Should grid items be bounded by the grid container.                                | boolean                             | false    |
+| readonly | If true disables interaction with grid items.                                      | boolean                             | false    |
 
 > ⚠️ if `cols` or/and `rows` are set to 0, `itemSize.width` or/and `itemSize.height` must be setted.
 
+### Layout
+
+`Layout<T>` are represented as an array of objects, items of which must have the following properties:
+
+| prop      | description                                                         | type    | default   |
+| --------- | ------------------------------------------------------------------- | ------- | --------- |
+| id        | Unique id of the item. Used to compare items during collision tests | string  | requried  |
+| x         | X position of the item in grid units.                               | number  | requried  |
+| y         | Y position of the item in grid units.                               | number  | requried  |
+| w         | Width of the item in grid units.                                    | number  | requried  |
+| h         | Height of the item in grid units.                                   | number  | requried  |
+| movable   | If true, item can be moved by user.                                 | boolean | true      |
+| resizable | If true, item can be resized by user.                               | boolean | true      |
+| data      | Custom attributes. 🦌                                               | T       | undefined |
+
+### Style related props:
+
+Component can be styled with css framework of your choice or with global classes. To do so, you can use the following props:
+
+- `class` - class name for grid container.
+- `itemClass` - class name for grid item.
+- `itemActiveClass` - class name that applies when item is currently being dragged or resized. By default, it is used to make active grid item transparent.
+- `itemPreviewClass` - class name for preview where item will be placed after interaction.
+- `resizerClass` - class name for item's resize handle.
+
+To understand how to use these props, look at `<Grid />` component simplified structure.
+
+> 📄 `active` is variable that indicates if grid item is currently being dragged or resized:
+
+```svelte
+<!-- Grid -->
+<div class={class}>
+	<!-- GridItem -->
+	<div class={itemClass} class:itemActiveClass={active}>
+		<slot />
+		<!-- Resizer -->
+		<div class={resizerClass} />
+		<!-- Resizer -->
+	</div>
+
+	{#if active}
+		<!-- GridItemGhost -->
+		<div class={itemPreviewClass} />
+	{/if}
+
+	<!-- /GridItem -->
+</div>
+<!-- /Grid -->
+```
+
 ## Usage
 
 - [Basic](#basic)
 - [Static grid](#static-grid)
 - [Grid without bounds](#grid-without-bounds)
+- [Styling](#styling)
+- [Disable interactions](#disable-interactions)
 
 ### Basic
 
@@ -138,3 +191,92 @@ It can be set to both dimensions or just one.
 	<div>Content</div>
 </Grid>
 ```
+
+### Styling
+
+Grid can be styled with classes passed to various props. Check [Style related props](#style-related-props) section for more info.
+
+✨ [repl](https://svelte.dev/repl/b158b6fbb2234241b7ea9737b7e2fc24?version=3.53.1)
+
+```svelte
+<script lang="ts">
+	import Grid from 'svelte-grid-extended';
+
+	const items = [
+		{ id: '0', x: 0, y: 0, w: 1, h: 1 },
+		{ id: '1', x: 0, y: 1, w: 1, h: 1 }
+	];
+</script>
+
+<Grid
+	{items}
+	class="grid-container"
+	itemClass="grid-item"
+	itemActiveClass="grid-item-active"
+	itemPreviewClass="bg-red-500 rounded"
+>
+	<div>Content</div>
+</Grid>
+
+<style>
+	:global(.grid-container) {
+		opacity: 0.7;
+	}
+
+	:global(.grid-item) {
+		transition: width 4s, height 4s;
+		transition: transform 4s, opacity 4s;
+	}
+
+	:global(.grid-item-active) {
+		opacity: 0.1;
+	}
+
+	/* tailwind classes */
+	:global(.bg-red-500) {
+		background-color: rgb(202, 33, 33);
+	}
+
+	:global(.rounded) {
+		border-radius: 0.25rem;
+	}
+</style>
+```
+
+### Disable interactions
+
+To disable interactions, set `readOnly` prop to `true`. Or set `movable` and/or `resizable` to `false` on specific item.
+
+Read Only grid: ✨ [repl](https://svelte.dev/repl/29ce85a23a714c51b6638f12f5ecdd7c?version=3.53.1)
+
+```svelte
+<script lang="ts">
+	import Grid from 'svelte-grid-extended';
+
+	const items = [
+		{ id: '0', x: 0, y: 0, w: 1, h: 1 },
+		{ id: '1', x: 0, y: 1, w: 1, h: 1 }
+	];
+</script>
+
+<Grid {items} cols={10} rows={10} readOnly>
+	<div>Content</div>
+</Grid>
+```
+
+Make item non-interactive: ✨ [repl](https://svelte.dev/repl/1b3b9b9b9b9b9b9b9b9b9b9b9b9b9b9b?version=3.53.1)
+
+```svelte
+<script lang="ts">
+	import Grid from 'svelte-grid-extended';
+
+	const items = [
+		{ id: '0', x: 0, y: 0, w: 1, h: 1, movable: false },
+		{ id: '1', x: 0, y: 1, w: 1, h: 1, movable: false, resizable: false }
+	];
+</script>
+
+<Grid {items} cols={10} rows={10}>
+	<div>Content</div>
+</Grid>
+```

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "svelte-grid-extended",
-	"version": "0.0.3",
+	"version": "0.1.0",
 	"description": "A draggable and resizable grid layout, for Svelte",
 	"repository": "https://github.com/cuire/svelte-grid-extended",
 	"scripts": {

src/lib/Grid.svelte

@@ -6,7 +6,7 @@
 	import { findGridSize } from './utils/breakpoints';
 	import { getGridDimensions } from './utils/grid';
 
-	import type { Breakpoints, ItemSize, GridSize, Item } from './types';
+	import type { Breakpoints, ItemSize, GridSize, LayoutItem } from './types';
 
 	export let cols: GridSize = 0;
 
@@ -16,7 +16,16 @@
 
 	export let gap = 10;
 
-	export let items: Item[];
+	type T = $$Generic;
+
+	interface $$Slots {
+		default: {
+			item: LayoutItem<T>;
+		};
+		loader: Record<string, never>;
+	}
+
+	export let items: LayoutItem<T>[];
 
 	export let breakpoints: Breakpoints = {
 		xxl: 1536,
@@ -31,6 +40,8 @@
 
 	export let bounds = false;
 
+	export let readOnly = false;
+
 	export let debug = false;
 
 	let classes = '';
@@ -67,7 +78,7 @@
 
 	$: if (typeof rows === 'number') _rows = rows;
 
-	$: if (itemSize?.width && itemSize?.height) _itemSize = itemSize as ItemSize;
+	$: if (itemSize?.width && itemSize?.height) _itemSize = { ...itemSize } as ItemSize;
 
 	$: if (itemSize?.width && _itemSize?.width) containerWidth = _cols * (_itemSize.width + gap + 1);
 
@@ -92,7 +103,7 @@
 		items = [...items];
 	}
 
-	function updateGridDimensions(event: CustomEvent<{ item: Item }>) {
+	function updateGridDimensions(event: CustomEvent<{ item: LayoutItem }>) {
 		const { item } = event.detail;
 		calculatedGridSize = getGridDimensions([...items.filter((i) => i.id !== item.id), item]);
 	}
@@ -108,7 +119,7 @@
 			const height = entry.contentRect.height;
 
 			_cols = findGridSize(cols, width, breakpoints);
-			_rows = findGridSize(rows, width, breakpoints);
+			_rows = findGridSize(rows, height, breakpoints);
 
 			shouldExpandCols = _cols === 0;
 			shouldExpandRows = _rows === 0;
@@ -142,7 +153,8 @@
 					maxCols,
 					maxRows,
 					bounds,
-					items
+					items,
+					readOnly
 				}}
 				activeClass={itemActiveClass}
 				previewClass={itemPreviewClass}