feat: images support & unit tests (#4)

Author: styiannis

README.md

@@ -2,11 +2,11 @@
 
 A web component that creates layouts by treating your HTML elements as rectangles and packing them using a best-fit 2D strip-packing algorithm.
 
-## Why a Packing Algorithm for Web Layouts?
+## ⚙️ Why a Packing Algorithm for Web Layouts?
 
 Web browsers naturally manage elements as rectangles. `rectpackr-layout` leverages this by applying a best-fit strip-packing algorithm — the same approach used in industrial optimization problems — to web layout creation.
 
-## Intelligent Layouts Through Automated Measurement
+## 🤖 Layouts Through Automated Measurement
 
 The algorithm intelligently works with whatever dimensional information is available:
 
@@ -31,7 +31,7 @@ The algorithm intelligently works with whatever dimensional information is avail
 - **Production-ready precision** when you need exact control
 - **Best of both worlds** — automation when you want it, control when you need it
 
-## Installation
+## 📥 Installation
 
 ### Install the package via your preferred package manager:
 
@@ -68,7 +68,7 @@ Or directly in your HTML:
 </script>
 ```
 
-## API Reference
+## 📖 API Reference
 
 ### Attributes
 
@@ -77,9 +77,9 @@ Or directly in your HTML:
 Defines the CSS method used to position items.
 
 - `transform` (_Default_): Uses `transform: translate(x, y)`
-- `offset`: Uses CSS offset properties (`top`/`bottom` and `left`/`right`)
+- `offset`: Uses CSS `inset` property for precise positioning
 
-> **Performance Note:** The default `transform` value typically offers better performance through hardware acceleration. Use `offset` only when child elements already use `transform` for other purposes (animation etc.).
+> 💡 **Performance Note:** The default `transform` value typically offers better performance through hardware acceleration. Use `offset` only when child elements already use `transform` for other purposes (animation etc.).
 
 **`x-direction`**
 
@@ -97,21 +97,68 @@ Controls the vertical packing direction.
 
 ### A Note on Visual Order & Accessibility
 
-The `x-direction` and `y-direction` attributes control visual placement, which may differ from DOM order.
+The `x-direction` and `y-direction` attributes control visual placement, which may create a difference between the visual arrangement and the underlying DOM order.
 
-- **DOM Order is Preserved:** The library never changes the underlying HTML structure, ensuring correct tab order and screen reader navigation
-- **Visual Order is Optimized:** The algorithm places items for spatial efficiency, which may not match linear DOM order
+- **DOM Order is Preserved:** The underlying HTML structure remains unchanged
+- **Visual Order is Algorithm-Determined**: Item placement follows the packing logic and your direction settings
 
-**Best Practice:** Ensure your HTML source reflects the logical reading order.
+## 🚀 Usage Examples
 
-## Browser Support
+### Fluid, Responsive Layout
+
+```html
+<rectpackr-layout>
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+</rectpackr-layout>
+
+<style>
+  rectpackr-layout {
+    container-type: inline-size;
+    display: block;
+  }
+
+  rectpackr-layout > * {
+    /* Fluid width based on container queries */
+    width: 100%;
+  }
+
+  @container (min-width: 400px) {
+    rectpackr-layout > * {
+      width: 50%;
+    }
+  }
+
+  @container (min-width: 800px) {
+    rectpackr-layout > * {
+      width: 33.33%;
+    }
+  }
+</style>
+```
+
+### Dynamic Content Handling
+
+```html
+<rectpackr-layout id="dynamic-layout">
+  <!-- Content can be added/removed dynamically -->
+</rectpackr-layout>
+
+<script>
+  // The layout automatically adjusts to content changes
+  document.getElementById('dynamic-layout').appendChild(newElement);
+</script>
+```
+
+## ✅ Browser Support
 
 Modern browsers with Web Components support.
 
-## Issues and Support
+## 🔧 Issues and Support
 
 If you encounter any issues or have questions, please [open an issue](https://github.com/styiannis/rectpackr-layout/issues).
 
-## License
+## 📄 License
 
 This project is licensed under the [MIT License](https://github.com/styiannis/rectpackr-layout?tab=MIT-1-ov-file#readme).

jest.config.js

@@ -2,8 +2,10 @@
 module.exports = {
   preset: 'ts-jest/presets/js-with-ts',
   testEnvironment: 'jsdom',
+  setupFilesAfterEnv: ['<rootDir>/tests/mocks/index.ts'],
   modulePathIgnorePatterns: [
     '<rootDir>/build/',
+    '<rootDir>/code_documentation/',
     '<rootDir>/coverage_report/',
     '<rootDir>/dist/',
   ],

package.json

@@ -1,6 +1,6 @@
 {
   "name": "rectpackr-layout",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A web component that creates layouts by packing HTML elements as rectangles using a best-fit 2D strip-packing algorithm. Automatically measures dimensions and handles mixed content.",
   "keywords": [
     "best-fit",
@@ -29,8 +29,8 @@
   "source": "src/index.ts",
   "main": "dist/cjs/index.js",
   "module": "dist/es/index.js",
-  "unpkg": "./dist/umd/index.js",
-  "jsdelivr": "./dist/umd/index.js",
+  "unpkg": "dist/umd/index.js",
+  "jsdelivr": "dist/umd/index.js",
   "types": "dist/@types/index.d.ts",
   "files": [
     "CHANGELOG.md",
@@ -84,7 +84,8 @@
     ".": {
       "import": "./dist/es/index.js",
       "require": "./dist/cjs/index.js",
-      "default": "./dist/umd/index.js"
+      "types": "./dist/@types/index.d.ts",
+      "default": "./dist/es/index.js"
     }
   }
 }

scripts/validate-exports.js

@@ -2,29 +2,32 @@ const { readFileSync, existsSync } = require('node:fs');
 
 const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));
 
+const invalidPaths = [];
+
+['source', 'main', 'module', 'unpkg', 'jsdelivr', 'types'].forEach((k) => {
+  if (pkg[k] && !existsSync(pkg[k])) invalidPaths.push(pkg[k]);
+});
+
 if (pkg.exports) {
-  const invalidExports = Object.keys(pkg.exports).reduce((acc, curr) => {
+  Object.keys(pkg.exports).reduce((acc, curr) => {
+    const def = pkg.exports[curr].default;
     const imp = pkg.exports[curr].import;
     const req = pkg.exports[curr].require;
+    const typ = pkg.exports[curr].types;
 
-    if (imp) {
-      if (imp.types && !existsSync(imp.types)) acc.push(imp.types);
-      if (imp.default && !existsSync(imp.default)) acc.push(imp.default);
-    }
-
-    if (req) {
-      if (req.types && !existsSync(req.types)) acc.push(req.types);
-      if (req.default && !existsSync(req.default)) acc.push(req.default);
-    }
+    if (def && !existsSync(def)) acc.push(def);
+    if (imp && !existsSync(imp)) acc.push(imp);
+    if (req && !existsSync(req)) acc.push(req);
+    if (typ && !existsSync(typ)) acc.push(typ);
 
     return acc;
-  }, []);
+  }, invalidPaths);
+}
 
-  if (0 < invalidExports.length) {
-    throw Error(
-      `Found invalid export paths\n\n${invalidExports
-        .map((path, i) => `[${i}] ${path}`)
-        .join('\n')}\n`
-    );
-  }
+if (invalidPaths.length > 0) {
+  throw Error(
+    `Found missing exported files\n\n${invalidPaths
+      .map((path, i) => `[${i}] ${path}`)
+      .join('\n')}\n`
+  );
 }

src/RectpackrLayout.ts

@@ -18,14 +18,20 @@ const parseConfig = (config: {
 });
 
 const getStyleTextContent = (config: IRectpackrConfig) => {
-  const insetValue = {
-    ltr: { ttb: '0 auto auto 0', btt: 'auto auto 0 0' },
-    rtl: { ttb: '0 0 auto auto', btt: 'auto 0 0 auto' },
-  }[config['x-direction']][config['y-direction']];
+  let ret = `slot{ box-sizing: border-box; position: relative; display: block; width: 100% }`;
 
-  return `
-    slot{ box-sizing: border-box; position:relative; display:block; width:100% }    
-    ::slotted(:not([slot])){ position:absolute; inset:${insetValue} }`;
+  if (config.positioning === 'transform') {
+    const insetValue = {
+      ltr: { ttb: '0 auto auto 0', btt: 'auto auto 0 0' },
+      rtl: { ttb: '0 0 auto auto', btt: 'auto 0 0 auto' },
+    }[config['x-direction']][config['y-direction']];
+
+    ret = `${ret} ::slotted(:not([slot])){ position: absolute !important; inset: ${insetValue} !important }`;
+  } else {
+    ret = `${ret} ::slotted(:not([slot])){ position: absolute !important }`;
+  }
+
+  return ret;
 };
 
 /* ------------------------------------------------------------------------- */
@@ -70,11 +76,10 @@ export class RectpackrLayout extends HTMLElement {
   }
 
   attributeChangedCallback() {
-    if (!this.shadowRoot) {
-      return;
+    if (this.shadowRoot) {
+      this.#clear();
+      this.#render();
     }
-    this.#clear();
-    this.#render();
   }
 
   connectedCallback() {

src/core/rectpackr.ts

@@ -33,7 +33,9 @@ export function create<R extends IRectpackr>(
     container,
     children: [] as R['children'],
     childrenContainer,
+    loadingImages: new Map(),
     observers: { childrenContainerMutation, childrenResize, containerResize },
+    pendingStartObservingChildren: false,
     stripPack,
   } as R;
 

src/core/types.ts

@@ -17,10 +17,12 @@ export interface IRectpackr {
     width: number;
   }[];
   childrenContainer: HTMLElement;
+  loadingImages: Map<HTMLElement, (this: HTMLImageElement) => void>;
   observers: {
     childrenContainerMutation: MutationObserver;
     childrenResize: ResizeObserver;
     containerResize: ResizeObserver;
   };
+  pendingStartObservingChildren: boolean;
   stripPack: BestFitStripPack;
 }