{"id":31545254,"url":"https://github.com/styiannis/rectpackr-layout","last_synced_at":"2026-01-20T16:57:09.566Z","repository":{"id":316778445,"uuid":"1062916678","full_name":"styiannis/rectpackr-layout","owner":"styiannis","description":"Web component that packs HTML elements as rectangles using best-fit 2D strip-packing algorithms. Automatically measures dimensions and handles mixed content.","archived":false,"fork":false,"pushed_at":"2025-10-03T16:14:36.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T18:30:50.999Z","etag":null,"topics":["best-fit","custom-element","custom-elements","dom","layout","masonry","masonry-layout","rectangle-packer","responsive","responsive-layout","strip-packing","web-component","web-components"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/styiannis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T23:12:15.000Z","updated_at":"2025-09-26T15:51:00.000Z","dependencies_parsed_at":"2025-09-26T17:43:38.629Z","dependency_job_id":null,"html_url":"https://github.com/styiannis/rectpackr-layout","commit_stats":null,"previous_names":["styiannis/rectpackr-layout"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/styiannis/rectpackr-layout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/styiannis%2Frectpackr-layout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/styiannis%2Frectpackr-layout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/styiannis%2Frectpackr-layout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/styiannis%2Frectpackr-layout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/styiannis","download_url":"https://codeload.github.com/styiannis/rectpackr-layout/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/styiannis%2Frectpackr-layout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278219817,"owners_count":25950358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["best-fit","custom-element","custom-elements","dom","layout","masonry","masonry-layout","rectangle-packer","responsive","responsive-layout","strip-packing","web-component","web-components"],"created_at":"2025-10-04T14:43:24.222Z","updated_at":"2026-01-20T16:57:09.561Z","avatar_url":"https://github.com/styiannis.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rectpackr Layout\n\n[![NPM Version](https://img.shields.io/npm/v/rectpackr-layout)](https://www.npmjs.com/package/rectpackr-layout)\n[![Coverage Status](https://img.shields.io/coverallsCoverage/github/styiannis/rectpackr-layout)](https://coveralls.io/github/styiannis/rectpackr-layout?branch=main)\n[![CodePen Demos](https://img.shields.io/badge/CodePen-Demos-blue)](https://codepen.io/collection/dGpeLa)\n\nA web component that creates layouts by treating your HTML elements as rectangles and packing them using a best-fit 2D strip-packing algorithm.\n\n## ⚙️ Why a Packing Algorithm for Web Layouts?\n\nWeb 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.\n\n## 🤖 Layouts Through Automated Measurement\n\nThe algorithm intelligently works with whatever dimensional information is available:\n\n### How It Works:\n\n- **Automatically measures** element dimensions through browser APIs\n- **Uses width as the primary constraint** for predictable flow\n- **Adapts to any height** — whether fixed, aspect-ratio based, or content-determined\n- **Handles mixed content seamlessly** without manual configuration\n\n### You Can:\n\n- Set explicit widths for pixel-perfect control\n- Use percentage-based or responsive widths\n- Let elements determine their own natural sizes\n- Mix and match approaches within the same layout\n\n### What This Enables:\n\n- **Truly flexible layouts** that work with your existing CSS approach\n- **Zero-configuration setups** for rapid prototyping\n- **Production-ready precision** when you need exact control\n- **Best of both worlds** — automation when you want it, control when you need it\n\n## 📥 Installation\n\n### Install the package via your preferred package manager:\n\n#### npm\n\n```bash\nnpm install rectpackr-layout\n```\n\n#### yarn\n\n```bash\nyarn add rectpackr-layout\n```\n\n#### pnpm\n\n```bash\npnpm install rectpackr-layout\n```\n\nThen import it in your JavaScript:\n\n```javascript\n// In your main.js or component file\nimport 'rectpackr-layout';\n```\n\nOr directly in your HTML:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import 'rectpackr-layout';\n\u003c/script\u003e\n```\n\n### Using a CDN (No Build Step Needed)\n\nInclude it directly in your HTML via CDN:\n\n#### unpkg\n\n```html\n\u003cscript type=\"module\" src=\"https://unpkg.com/rectpackr-layout\"\u003e\u003c/script\u003e\n```\n\n#### jsDelivr\n\n```html\n\u003cscript\n  type=\"module\"\n  src=\"https://cdn.jsdelivr.net/npm/rectpackr-layout\"\n\u003e\u003c/script\u003e\n```\n\n#### esm.sh\n\n```html\n\u003cscript type=\"module\" src=\"https://esm.sh/rectpackr-layout\"\u003e\u003c/script\u003e\n```\n\n### Once installed, use the web component anywhere in your HTML:\n\n```html\n\u003crectpackr-layout\u003e\n  \u003cdiv\u003eYour content here\u003c/div\u003e\n\u003c/rectpackr-layout\u003e\n```\n\n## 📖 API Reference\n\n### Attributes\n\n**`positioning`**\n\nDefines the CSS method used to position items.\n\n- `transform` (_Default_): Uses `transform: translate(x, y)`\n- `offset`: Uses CSS `inset` property for precise positioning\n\n\u003e 💡 **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.).\n\n**`x-direction`**\n\nControls the horizontal packing direction.\n\n- `ltr` (_Default_): Left-to-right packing\n- `rtl`: Right-to-left packing\n\n**`y-direction`**\n\nControls the vertical packing direction.\n\n- `ttb` (_Default_): Top-to-bottom packing\n- `btt`: Bottom-to-top packing\n\n### A Note on Visual Order \u0026 Accessibility\n\nThe `x-direction` and `y-direction` attributes control visual placement, which may create a difference between the visual arrangement and the underlying DOM order.\n\n- **DOM Order is Preserved:** The underlying HTML structure remains unchanged\n- **Visual Order is Algorithm-Determined**: Item placement follows the packing logic and your direction settings\n\n## 🚀 Usage Examples\n\n### Fluid, Responsive Layout\n\n```html\n\u003crectpackr-layout\u003e\n  \u003cdiv\u003eCard 1\u003c/div\u003e\n  \u003cdiv\u003eCard 2\u003c/div\u003e\n  \u003cdiv\u003eCard 3\u003c/div\u003e\n\u003c/rectpackr-layout\u003e\n\n\u003cstyle\u003e\n  rectpackr-layout {\n    container-type: inline-size;\n    display: block;\n  }\n\n  rectpackr-layout \u003e * {\n    /* Fluid width based on container queries */\n    width: 100%;\n  }\n\n  @container (min-width: 400px) {\n    rectpackr-layout \u003e * {\n      width: 50%;\n    }\n  }\n\n  @container (min-width: 800px) {\n    rectpackr-layout \u003e * {\n      width: 33.33%;\n    }\n  }\n\u003c/style\u003e\n```\n\n### Dynamic Content Handling\n\n```html\n\u003crectpackr-layout id=\"dynamic-layout\"\u003e\n  \u003c!-- Content can be added/removed dynamically --\u003e\n\u003c/rectpackr-layout\u003e\n\n\u003cscript\u003e\n  // The layout automatically adjusts to content changes\n  document.getElementById('dynamic-layout').appendChild(newElement);\n\u003c/script\u003e\n```\n\n## 🎯 Live Demos\n\n### Consistent Width Gallery\n\nSee predictable masonry-style layouts with equal-width elements\n\n[View on CodePen](https://codepen.io/styiannis/pen/ogbzBXg)\n\n### Mixed Dimension Gallery\n\nExplore optimal packing of variably-sized elements and aspect ratios\n\n[View on CodePen](https://codepen.io/styiannis/pen/XJXjayR)\n\n### Interactive Playground\n\nExperiment with real-time controls and dynamic content manipulation\n\n[View on CodePen](https://codepen.io/styiannis/pen/qEbqMBZ)\n\n## ✅ Browser Support\n\nModern browsers with Web Components support.\n\n## 🔧 Issues and Support\n\nIf you encounter any issues or have questions, please [open an issue](https://github.com/styiannis/rectpackr-layout/issues).\n\n## 📄 License\n\nThis project is licensed under the [MIT License](https://github.com/styiannis/rectpackr-layout?tab=MIT-1-ov-file#readme).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstyiannis%2Frectpackr-layout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstyiannis%2Frectpackr-layout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstyiannis%2Frectpackr-layout/lists"}