rectflow 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+# Rectflow
+
+A lightweight **JavaScript layout engine** inspired by CSS Grid, designed for **programmatic layouts**, canvas-heavy apps, charting tools, editors, and environments where CSS Grid is not flexible enough.
+
+Rectflow lets you define rows, columns, gaps, and named areas — then calculates and applies absolute positions automatically.
+
+---
+
+## ✨ Features
+
+-   CSS-Grid–like API (rows, columns, areas)
+-   Works **without CSS Grid** (pure JS layout engine)
+-   Supports:
+
+    -   `fr`, `px`, `auto` tracks
+    -   Gaps
+    -   Named areas
+
+-   Automatic DOM creation for missing areas
+-   Resize-aware (re-layout on container resize)
+-   CDN-ready bundle + npm package
+
+---
+
+## 📦 Installation
+
+### Using npm
+
+```bash
+npm install rectflow
+```
+
+```ts
+import { Rectflow } from 'rectflow'
+```
+
+### Using CDN
+
+```html
+<script src="https://unpkg.com/rectflow/dist/rectflow.umd.js"></script>
+<script>
+    const rectflow = new Rectflow(...)
+</script>
+```
+
+---
+
+## 🚀 Basic Usage
+
+### HTML
+
+```html
+<div class="main"></div>
+```
+
+### JavaScript
+
+```ts
+const mainElem = document.querySelector('.main')
+
+const rectflow = new Rectflow({
+    container: mainElem,
+    layout: {
+        rows: '50px auto 50px',
+        columns: '50px auto 100px',
+        gap: 5,
+        areas: [
+            ['tool tool tool'], 
+            ['drawing chart widget'], 
+            ['drawing base widget']
+        ],
+    },
+})
+
+rectflow.layout()
+```
+
+---
+
+## 🧩 Areas Syntax
+
+Rectflow supports **two area formats**:
+
+### Shortcut (recommended)
+
+```ts
+areas: [
+    ['tool tool'], 
+    ['drawing chart']
+]
+```
+
+### Expanded form
+
+```ts
+areas: [
+    ['tool', 'tool'],
+    ['drawing', 'chart'],
+]
+```
+
+Both are equivalent.
+
+---
+
+## 🧠 Automatic Area Creation
+
+If an area is defined in `areas` but **not registered**, Rectflow will:
+
+-   Automatically create a `<div>`
+-   Assign it the area name
+-   Insert it into the container
+-   Apply a random background color (for debugging)
+
+This makes rapid prototyping easy.
+
+---
+
+## 🔁 Resize Handling
+
+Rectflow listens to container resize events and automatically recalculates layout:
+
+-   Uses `ResizeObserver`
+-   Re-applies positions when size changes
+
+No manual resize handling required.
+
+---
+
+## ⚙️ API Reference
+
+### `new Rectflow(config)`
+
+#### config
+
+```ts
+{
+    container: HTMLElement
+    layout: {
+        rows: string
+        columns: string
+        gap?: number
+        areas: string[][]
+    }
+}
+```
+
+---
+
+### `registerArea(name, element)`
+
+Registers an existing DOM element for an area.
+
+```ts
+rectflow.registerArea('chart', chartElement)
+```
+
+---
+
+### `layout()`
+
+Calculates layout and applies styles.
+
+```ts
+rectflow.layout()
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## ❤️ Inspiration
+
+Inspired by:
+
+-   CSS Grid
+-   Game UI layout systems
+-   Charting & trading platforms
+-   Dashboards
+
+---
+
+If you’re building editors, dashboards, charting tools, or canvas-heavy apps — Rectflow is built for you.

package/dist/AreaRenderer.d.ts

@@ -0,0 +1,11 @@
+import type { RectflowConfig } from './Rectflow';
+export declare class AreaRenderer {
+    private readonly config;
+    private areas;
+    private engine;
+    constructor(config: RectflowConfig);
+    registerArea(name: string, elem: HTMLElement): void;
+    layout(): void;
+    private ensureArea;
+    clearArea(): void;
+}

package/dist/Grid.d.ts

@@ -0,0 +1,16 @@
+export type AreaName = string;
+export type TrackSize = number | `${number}px` | `${number}fr` | 'auto';
+export type GridAreas = string[][];
+export interface GridConfig {
+    rows: string;
+    columns: string;
+    gap?: number;
+    areas: GridAreas;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type ComputedLayout = Record<AreaName, Rect>;

package/dist/LayoutEngine.d.ts

@@ -0,0 +1,9 @@
+import type { Rect, ComputedLayout, GridConfig } from './Grid';
+export declare class LayoutEngine {
+    private config;
+    constructor(config: GridConfig);
+    compute(container: Rect): ComputedLayout;
+    private normalizeAreas;
+    private parseTracks;
+    private accumulate;
+}

package/dist/Rectflow.d.ts

@@ -0,0 +1,13 @@
+import type { GridConfig } from './Grid';
+export type RectflowConfig = {
+    container: HTMLElement;
+    layout: GridConfig;
+};
+export declare class Rectflow {
+    private areaRenderer;
+    private observer;
+    constructor(config: RectflowConfig);
+    registerArea(area: string, elem: HTMLElement): void;
+    layout(): void;
+    destroy(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './Rectflow';

package/dist/rectflow.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class g{constructor(e){this.config=e}compute(e){const t=this.parseTracks(this.config.rows,e.height),r=this.parseTracks(this.config.columns,e.width),i=this.config.gap??0,n=this.accumulate(t,i),a=this.accumulate(r,i),l=this.normalizeAreas(this.config.areas),h={};for(let s=0;s<l.length;s++)for(let o=0;o<l[s].length;o++){const u=l[s][o];if(u!==".")if(!h[u])h[u]={x:a[o],y:n[s],width:r[o],height:t[s]};else{const c=h[u];a[o]+r[o]>c.x+c.width&&(c.width=a[o]+r[o]-c.x),n[s]+t[s]>c.y+c.height&&(c.height=n[s]+t[s]-c.y)}}return h}normalizeAreas(e){return e.map(t=>t.length===1?t[0].trim().split(/\s+/):t)}parseTracks(e,t){const r=e.split(/\s+/),i=this.config.gap??0;let n=0,a=0;for(const s of r)s.endsWith("px")?n+=parseFloat(s):s.endsWith("fr")?a+=parseFloat(s):s==="auto"&&(a+=1);const l=t-n-(r.length-1)*i,h=a>0?l/a:0;return r.map(s=>s.endsWith("px")?parseFloat(s):s.endsWith("fr")?parseFloat(s)*h:s==="auto"?h:0)}accumulate(e,t){const r=[];let i=0;for(const n of e)r.push(i),i+=n+t;return r}}class d{constructor(e){this.config=e,this.engine=new g(e.layout)}areas=new Map;engine;registerArea(e,t){const r=this.areas.get(e);r?.auto&&r.elem.remove(),t.style.position="absolute",this.areas.set(e,{elem:t,auto:!1})}layout(){const e={x:0,y:0,width:this.config.container.clientWidth,height:this.config.container.clientHeight},t=this.engine.compute(e);for(const r in t){const i=this.ensureArea(r),n=t[r];Object.assign(i.style,{left:`${n.x}px`,top:`${n.y}px`,width:`${n.width}px`,height:`${n.height}px`})}}ensureArea(e){function t(){return`hsl(${Math.floor(Math.random()*360)}, 70%, 70%)`}const r=this.areas.get(e);if(r)return r.elem;const i=document.createElement("div");return i.dataset.rectflowArea=e,i.style.background=t(),i.style.position="absolute",this.config.container.appendChild(i),this.areas.set(e,{elem:i,auto:!0}),i}clearArea(){this.areas.clear()}}class p{areaRenderer;observer;constructor(e){e.container.style.position="relative",this.areaRenderer=new d(e),this.observer=new ResizeObserver(()=>this.layout()),this.observer.observe(e.container)}registerArea(e,t){this.areaRenderer.registerArea(e,t)}layout(){this.areaRenderer.layout()}destroy(){this.observer.disconnect(),this.areaRenderer.clearArea()}}exports.Rectflow=p;

package/dist/rectflow.es.js

@@ -0,0 +1,105 @@
+class g {
+  constructor(e) {
+    this.config = e;
+  }
+  compute(e) {
+    const t = this.parseTracks(this.config.rows, e.height), r = this.parseTracks(this.config.columns, e.width), i = this.config.gap ?? 0, n = this.accumulate(t, i), a = this.accumulate(r, i), l = this.normalizeAreas(this.config.areas), h = {};
+    for (let s = 0; s < l.length; s++)
+      for (let o = 0; o < l[s].length; o++) {
+        const u = l[s][o];
+        if (u !== ".")
+          if (!h[u])
+            h[u] = {
+              x: a[o],
+              y: n[s],
+              width: r[o],
+              height: t[s]
+            };
+          else {
+            const c = h[u];
+            a[o] + r[o] > c.x + c.width && (c.width = a[o] + r[o] - c.x), n[s] + t[s] > c.y + c.height && (c.height = n[s] + t[s] - c.y);
+          }
+      }
+    return h;
+  }
+  normalizeAreas(e) {
+    return e.map((t) => t.length === 1 ? t[0].trim().split(/\s+/) : t);
+  }
+  parseTracks(e, t) {
+    const r = e.split(/\s+/), i = this.config.gap ?? 0;
+    let n = 0, a = 0;
+    for (const s of r)
+      s.endsWith("px") ? n += parseFloat(s) : s.endsWith("fr") ? a += parseFloat(s) : s === "auto" && (a += 1);
+    const l = t - n - (r.length - 1) * i, h = a > 0 ? l / a : 0;
+    return r.map((s) => s.endsWith("px") ? parseFloat(s) : s.endsWith("fr") ? parseFloat(s) * h : s === "auto" ? h : 0);
+  }
+  accumulate(e, t) {
+    const r = [];
+    let i = 0;
+    for (const n of e)
+      r.push(i), i += n + t;
+    return r;
+  }
+}
+class p {
+  constructor(e) {
+    this.config = e, this.engine = new g(e.layout);
+  }
+  areas = /* @__PURE__ */ new Map();
+  engine;
+  registerArea(e, t) {
+    const r = this.areas.get(e);
+    r?.auto && r.elem.remove(), t.style.position = "absolute", this.areas.set(e, {
+      elem: t,
+      auto: !1
+    });
+  }
+  layout() {
+    const e = {
+      x: 0,
+      y: 0,
+      width: this.config.container.clientWidth,
+      height: this.config.container.clientHeight
+    }, t = this.engine.compute(e);
+    for (const r in t) {
+      const i = this.ensureArea(r), n = t[r];
+      Object.assign(i.style, {
+        left: `${n.x}px`,
+        top: `${n.y}px`,
+        width: `${n.width}px`,
+        height: `${n.height}px`
+      });
+    }
+  }
+  ensureArea(e) {
+    function t() {
+      return `hsl(${Math.floor(Math.random() * 360)}, 70%, 70%)`;
+    }
+    const r = this.areas.get(e);
+    if (r) return r.elem;
+    const i = document.createElement("div");
+    return i.dataset.rectflowArea = e, i.style.background = t(), i.style.position = "absolute", this.config.container.appendChild(i), this.areas.set(e, { elem: i, auto: !0 }), i;
+  }
+  clearArea() {
+    this.areas.clear();
+  }
+}
+class d {
+  areaRenderer;
+  observer;
+  constructor(e) {
+    e.container.style.position = "relative", this.areaRenderer = new p(e), this.observer = new ResizeObserver(() => this.layout()), this.observer.observe(e.container);
+  }
+  registerArea(e, t) {
+    this.areaRenderer.registerArea(e, t);
+  }
+  layout() {
+    this.areaRenderer.layout();
+  }
+  destroy() {
+    this.observer.disconnect(), this.areaRenderer.clearArea();
+  }
+}
+export {
+  d as Rectflow
+};

package/dist/rectflow.umd.js

@@ -0,0 +1 @@
+(function(l,u){typeof exports=="object"&&typeof module<"u"?u(exports):typeof define=="function"&&define.amd?define(["exports"],u):(l=typeof globalThis<"u"?globalThis:l||self,u(l.Rectflow={}))})(this,(function(l){"use strict";class u{constructor(e){this.config=e}compute(e){const t=this.parseTracks(this.config.rows,e.height),r=this.parseTracks(this.config.columns,e.width),i=this.config.gap??0,n=this.accumulate(t,i),a=this.accumulate(r,i),f=this.normalizeAreas(this.config.areas),h={};for(let s=0;s<f.length;s++)for(let o=0;o<f[s].length;o++){const d=f[s][o];if(d!==".")if(!h[d])h[d]={x:a[o],y:n[s],width:r[o],height:t[s]};else{const c=h[d];a[o]+r[o]>c.x+c.width&&(c.width=a[o]+r[o]-c.x),n[s]+t[s]>c.y+c.height&&(c.height=n[s]+t[s]-c.y)}}return h}normalizeAreas(e){return e.map(t=>t.length===1?t[0].trim().split(/\s+/):t)}parseTracks(e,t){const r=e.split(/\s+/),i=this.config.gap??0;let n=0,a=0;for(const s of r)s.endsWith("px")?n+=parseFloat(s):s.endsWith("fr")?a+=parseFloat(s):s==="auto"&&(a+=1);const f=t-n-(r.length-1)*i,h=a>0?f/a:0;return r.map(s=>s.endsWith("px")?parseFloat(s):s.endsWith("fr")?parseFloat(s)*h:s==="auto"?h:0)}accumulate(e,t){const r=[];let i=0;for(const n of e)r.push(i),i+=n+t;return r}}class p{constructor(e){this.config=e,this.engine=new u(e.layout)}areas=new Map;engine;registerArea(e,t){const r=this.areas.get(e);r?.auto&&r.elem.remove(),t.style.position="absolute",this.areas.set(e,{elem:t,auto:!1})}layout(){const e={x:0,y:0,width:this.config.container.clientWidth,height:this.config.container.clientHeight},t=this.engine.compute(e);for(const r in t){const i=this.ensureArea(r),n=t[r];Object.assign(i.style,{left:`${n.x}px`,top:`${n.y}px`,width:`${n.width}px`,height:`${n.height}px`})}}ensureArea(e){function t(){return`hsl(${Math.floor(Math.random()*360)}, 70%, 70%)`}const r=this.areas.get(e);if(r)return r.elem;const i=document.createElement("div");return i.dataset.rectflowArea=e,i.style.background=t(),i.style.position="absolute",this.config.container.appendChild(i),this.areas.set(e,{elem:i,auto:!0}),i}clearArea(){this.areas.clear()}}class m{areaRenderer;observer;constructor(e){e.container.style.position="relative",this.areaRenderer=new p(e),this.observer=new ResizeObserver(()=>this.layout()),this.observer.observe(e.container)}registerArea(e,t){this.areaRenderer.registerArea(e,t)}layout(){this.areaRenderer.layout()}destroy(){this.observer.disconnect(),this.areaRenderer.clearArea()}}l.Rectflow=m,Object.defineProperty(l,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "rectflow",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "Absolute-position layout engine with grid-like DSL",
+    "main": "./dist/rectflow.cjs.js",
+    "module": "./dist/rectflow.es.js",
+    "unpkg": "./dist/rectflow.umd.js",
+    "jsdelivr": "./dist/rectflow.umd.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc && vite build",
+        "preview": "vite preview"
+    },
+    "keywords": [
+        "layout",
+        "grid",
+        "dashboard",
+        "absolute-layout",
+        "ui-engine",
+        "dock",
+        "panel"
+    ],
+    "author": "Danish Ahmed Khan",
+    "license": "MIT",
+    "devDependencies": {
+        "@types/node": "^25.0.3",
+        "typescript": "~5.9.3",
+        "vite": "^7.2.4"
+    }
+}