@damarkuncoro/layout-engine 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# layout-engine
+
+Headless layout engine berfokus pada primitives (Box, Flex, Stack, Grid) dan structures (SidebarLayout) dengan sistem responsive sederhana.
+
+## Instalasi
+
+```bash
+npm install @damarkuncoro/layout-engine
+```
+
+## Fitur
+- Headless nodes → mudah dirender ke HTML string atau adaptor UI.
+- Primitives: Box, Flex, Stack, Grid.
+- Structures: SidebarLayout.
+- Sistem responsive berbasis breakpoints (sm, md, lg, xl, 2xl).
+
+## Penggunaan Dasar
+
+Render headless ke HTML:
+
+```js
+import { Box, Flex, Stack, Grid, SidebarLayout, renderToString } from "layout-engine"
+
+const page = SidebarLayout({
+  sidebar: Box({ children: "Sidebar" }),
+  children: Stack({ gap: 16, children: [Box({ children: "Card 1" }), Box({ children: "Card 2" })] }),
+  sidebarWidth: { base: 120, md: 200, xl: 280 },
+  viewportWidth: 1024
+})
+
+console.log(renderToString(page))
+```
+
+Responsive utility:
+
+```js
+import { resolveResponsive } from "layout-engine"
+const gap = resolveResponsive({ base: 8, md: 16, xl: 24 }, 768) // 16
+```
+
+## TypeScript
+- ESM-only, deklarasi tipe tersedia pada `dist/index.d.ts`.
+
+## Lisensi
+MIT

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./styleResolver.js";
+export * from "./spacingSystem.js";
+export * from "./responsiveSystem.js";

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export * from "./styleResolver.js";
+export * from "./spacingSystem.js";
+export * from "./responsiveSystem.js";

package/dist/core/render.d.ts

@@ -0,0 +1,5 @@
+import type { HeadlessNode } from "../system/types.js";
+/**
+ * Merender HeadlessNode menjadi string HTML dengan inline style.
+ */
+export declare const renderToString: (node: HeadlessNode) => string;

package/dist/core/render.js

@@ -0,0 +1,41 @@
+const styleToString = (style) => {
+    if (!style)
+        return "";
+    const entries = Object.entries(style)
+        .filter(([_, v]) => v !== undefined && v !== null && v !== "")
+        .map(([k, v]) => {
+        const prop = k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+        return `${prop}:${String(v)}`;
+    });
+    return entries.join(";");
+};
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const renderChild = (child) => {
+    if (child === null || child === undefined || child === false)
+        return "";
+    if (Array.isArray(child))
+        return child.map(renderChild).join("");
+    if (typeof child === "object" && child.type && child.props) {
+        return renderToString(child);
+    }
+    return escapeHtml(String(child));
+};
+/**
+ * Merender HeadlessNode menjadi string HTML dengan inline style.
+ */
+export const renderToString = (node) => {
+    const { type, props } = node;
+    const { children, style, className, ...rest } = props || {};
+    const styleStr = styleToString(style);
+    const attr = (className ? ` class="${className}"` : "") +
+        (styleStr ? ` style="${styleStr}"` : "") +
+        Object.entries(rest)
+            .map(([k, v]) => {
+            if (v === undefined || v === null || typeof v === "object")
+                return "";
+            return ` ${k}="${String(v)}"`;
+        })
+            .join("");
+    const inner = renderChild(children);
+    return `<${type}${attr}>${inner}</${type}>`;
+};

package/dist/core/responsiveSystem.d.ts

@@ -0,0 +1,11 @@
+export type BreakpointKey = "sm" | "md" | "lg" | "xl" | "2xl";
+export declare const breakpoints: Record<BreakpointKey, number>;
+export type ResponsiveValue<T> = T | {
+    base?: T;
+    sm?: T;
+    md?: T;
+    lg?: T;
+    xl?: T;
+    "2xl"?: T;
+} | T[];
+export declare const resolveResponsive: <T>(value: ResponsiveValue<T> | undefined, width: number) => T | undefined;

package/dist/core/responsiveSystem.js

@@ -0,0 +1,41 @@
+export const breakpoints = {
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    "2xl": 1536
+};
+export const resolveResponsive = (value, width) => {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) && typeof value !== "object")
+        return value;
+    const order = [
+        { min: 0 },
+        { key: "sm", min: breakpoints.sm },
+        { key: "md", min: breakpoints.md },
+        { key: "lg", min: breakpoints.lg },
+        { key: "xl", min: breakpoints.xl },
+        { key: "2xl", min: breakpoints["2xl"] }
+    ];
+    let resolved = undefined;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < order.length; i++) {
+            if (width >= order[i].min && i < value.length) {
+                resolved = value[i];
+            }
+        }
+        return resolved;
+    }
+    const obj = value;
+    if (obj.base !== undefined)
+        resolved = obj.base;
+    for (const it of order) {
+        if (!it.key)
+            continue;
+        if (width >= it.min && obj[it.key] !== undefined) {
+            resolved = obj[it.key];
+        }
+    }
+    return resolved;
+};

package/dist/core/spacingSystem.d.ts

@@ -0,0 +1,2 @@
+export declare const spacingScale: Record<number, number>;
+export declare const space: (i: number) => string;

package/dist/core/spacingSystem.js

@@ -0,0 +1,17 @@
+export const spacingScale = {
+    0: 0,
+    1: 4,
+    2: 8,
+    3: 12,
+    4: 16,
+    5: 24,
+    6: 32,
+    7: 40,
+    8: 48,
+    9: 64
+};
+export const space = (i) => {
+    const v = spacingScale[i];
+    const n = typeof v === "number" ? v : i;
+    return `${n}px`;
+};

package/dist/core/styleResolver.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Mengubah nilai panjang CSS: angka → px, string tetap.
+ * Contoh: 16 -> "16px", "2rem" -> "2rem", undefined -> undefined
+ */
+export declare const normalizeUnit: (value?: number | string) => string | undefined;

package/dist/core/styleResolver.js

@@ -0,0 +1,10 @@
+/**
+ * Mengubah nilai panjang CSS: angka → px, string tetap.
+ * Contoh: 16 -> "16px", "2rem" -> "2rem", undefined -> undefined
+ */
+export const normalizeUnit = (value) => {
+    if (typeof value === "number") {
+        return `${value}px`;
+    }
+    return value;
+};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./core/styleResolver.js";
+export * from "./core/spacingSystem.js";
+export { resolveResponsive, breakpoints, type BreakpointKey } from "./core/responsiveSystem.js";
+export * from "./core/render.js";
+export * from "./system/types.js";
+export * from "./system/contracts.js";
+export { Box, type LayoutProps } from "./primitives/Box.js";
+export { Flex, type FlexProps } from "./primitives/Flex.js";
+export { Stack, type StackProps } from "./primitives/Stack.js";
+export { Grid, type GridProps } from "./primitives/Grid.js";
+export { SidebarLayout, type ResponsiveSidebarLayoutProps } from "./structures/SidebarLayout.js";
+export * from "./patterns/DashboardLayout.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./core/styleResolver.js";
+export * from "./core/spacingSystem.js";
+export { resolveResponsive, breakpoints } from "./core/responsiveSystem.js";
+export * from "./core/render.js";
+export * from "./system/types.js";
+export * from "./system/contracts.js";
+export { Box } from "./primitives/Box.js";
+export { Flex } from "./primitives/Flex.js";
+export { Stack } from "./primitives/Stack.js";
+export { Grid } from "./primitives/Grid.js";
+export { SidebarLayout } from "./structures/SidebarLayout.js";
+export * from "./patterns/DashboardLayout.js";

package/dist/patterns/DashboardLayout.d.ts

@@ -0,0 +1,8 @@
+import type { DashboardLayoutContract } from "../system/contracts.js";
+export declare function DashboardLayout({ header, sidebar, children }: DashboardLayoutContract): {
+    type: string;
+    props: {
+        children: any;
+        style: Record<string, any>;
+    };
+};

package/dist/patterns/DashboardLayout.js

@@ -0,0 +1,11 @@
+import { Flex } from "../primitives/Flex.js";
+import { SidebarLayout } from "../structures/SidebarLayout.js";
+export function DashboardLayout({ header, sidebar, children }) {
+    return Flex({
+        direction: "column",
+        children: [
+            header,
+            SidebarLayout({ sidebar, children })
+        ]
+    });
+}

package/dist/primitives/Box.d.ts

@@ -0,0 +1,15 @@
+import type { LayoutProps } from "../system/types.js";
+export { type LayoutProps };
+/**
+ * Komponen blok dasar yang memetakan LayoutProps → inline style.
+ * Gunakan untuk membangun primitive lainnya.
+ */
+export declare function Box({ children, padding, margin, width, height, display, style, ...rest }: LayoutProps & {
+    children?: any;
+}): {
+    type: string;
+    props: {
+        children: any;
+        style: Record<string, any>;
+    };
+};

package/dist/primitives/Box.js

@@ -0,0 +1,23 @@
+import { normalizeUnit } from "../core/styleResolver.js";
+/**
+ * Komponen blok dasar yang memetakan LayoutProps → inline style.
+ * Gunakan untuk membangun primitive lainnya.
+ */
+export function Box({ children, padding, margin, width, height, display, style, ...rest }) {
+    const resolved = {
+        padding: normalizeUnit(padding),
+        margin: normalizeUnit(margin),
+        width: normalizeUnit(width),
+        height: normalizeUnit(height),
+        display,
+        ...style
+    };
+    return {
+        type: "div",
+        props: {
+            style: resolved,
+            ...rest,
+            children
+        }
+    };
+}

package/dist/primitives/Flex.d.ts

@@ -0,0 +1,20 @@
+import type { LayoutProps, CSSLength } from "../system/types.js";
+export interface FlexProps extends LayoutProps {
+    justify?: string;
+    align?: string;
+    gap?: CSSLength;
+    direction?: "row" | "row-reverse" | "column" | "column-reverse";
+}
+/**
+ * Kontainer fleksibel berbasis style inline (tanpa dependency React).
+ * Menghasilkan struktur objek yang merepresentasikan node 'div' dengan style flex.
+ */
+export declare function Flex({ children, justify, align, gap, direction, padding, margin, width, height, display, style, ...rest }: FlexProps & {
+    children?: any;
+}): {
+    type: string;
+    props: {
+        children: any;
+        style: Record<string, any>;
+    };
+};

package/dist/primitives/Flex.js

@@ -0,0 +1,27 @@
+import { normalizeUnit } from "../core/styleResolver.js";
+/**
+ * Kontainer fleksibel berbasis style inline (tanpa dependency React).
+ * Menghasilkan struktur objek yang merepresentasikan node 'div' dengan style flex.
+ */
+export function Flex({ children, justify, align, gap, direction = "row", padding, margin, width, height, display, style, ...rest }) {
+    const resolved = {
+        padding: normalizeUnit(padding),
+        margin: normalizeUnit(margin),
+        width: normalizeUnit(width),
+        height: normalizeUnit(height),
+        display: display !== null && display !== void 0 ? display : "flex",
+        justifyContent: justify,
+        alignItems: align,
+        gap: normalizeUnit(gap),
+        flexDirection: direction,
+        ...style
+    };
+    return {
+        type: "div",
+        props: {
+            style: resolved,
+            ...rest,
+            children
+        }
+    };
+}

package/dist/primitives/Grid.d.ts

@@ -0,0 +1,15 @@
+import type { CSSLength, LayoutProps } from "../system/types.js";
+export interface GridProps extends LayoutProps {
+    columns?: number | string;
+    rows?: number | string;
+    gap?: CSSLength;
+}
+export declare function Grid({ children, columns, rows, gap, padding, margin, width, height, display, style, ...rest }: GridProps & {
+    children?: any;
+}): {
+    type: string;
+    props: {
+        children: any;
+        style: Record<string, any>;
+    };
+};

package/dist/primitives/Grid.js

@@ -0,0 +1,27 @@
+import { normalizeUnit } from "../core/styleResolver.js";
+const toTemplate = (v) => {
+    if (typeof v === "number")
+        return `repeat(${v}, minmax(0, 1fr))`;
+    return v;
+};
+export function Grid({ children, columns, rows, gap, padding, margin, width, height, display, style, ...rest }) {
+    const resolved = {
+        padding: normalizeUnit(padding),
+        margin: normalizeUnit(margin),
+        width: normalizeUnit(width),
+        height: normalizeUnit(height),
+        display: display !== null && display !== void 0 ? display : "grid",
+        gridTemplateColumns: toTemplate(columns),
+        gridTemplateRows: toTemplate(rows),
+        gap: normalizeUnit(gap),
+        ...style
+    };
+    return {
+        type: "div",
+        props: {
+            style: resolved,
+            ...rest,
+            children
+        }
+    };
+}

package/dist/primitives/Stack.d.ts

@@ -0,0 +1,13 @@
+import type { CSSLength, LayoutProps } from "../system/types.js";
+export interface StackProps extends LayoutProps {
+    gap?: CSSLength;
+}
+export declare function Stack({ children, gap, padding, margin, width, height, display, style, ...rest }: StackProps & {
+    children?: any;
+}): {
+    type: string;
+    props: {
+        children: any;
+        style: Record<string, any>;
+    };
+};

package/dist/primitives/Stack.js

@@ -0,0 +1,21 @@
+import { normalizeUnit } from "../core/styleResolver.js";
+export function Stack({ children, gap = 8, padding, margin, width, height, display, style, ...rest }) {
+    const resolved = {
+        padding: normalizeUnit(padding),
+        margin: normalizeUnit(margin),
+        width: normalizeUnit(width),
+        height: normalizeUnit(height),
+        display: display !== null && display !== void 0 ? display : "flex",
+        flexDirection: "column",
+        gap: normalizeUnit(gap),
+        ...style
+    };
+    return {
+        type: "div",
+        props: {
+            style: resolved,
+            ...rest,
+            children
+        }
+    };
+}

package/dist/primitives/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./Box";
+export * from "./Flex";
+export * from "./Grid";
+export * from "./Stack";

package/dist/primitives/index.js

@@ -0,0 +1,4 @@
+export * from "./Box";
+export * from "./Flex";
+export * from "./Grid";
+export * from "./Stack";

package/dist/structures/SidebarLayout.d.ts

@@ -0,0 +1,13 @@
+import type { SidebarLayoutContract } from "../system/contracts.js";
+import type { CSSLength, ResponsiveValue } from "../system/types.js";
+export interface ResponsiveSidebarLayoutProps extends Omit<SidebarLayoutContract, "sidebarWidth"> {
+    sidebarWidth?: ResponsiveValue<CSSLength>;
+    viewportWidth?: number;
+}
+export declare function SidebarLayout({ sidebar, children, sidebarWidth, viewportWidth }: ResponsiveSidebarLayoutProps): {
+    type: string;
+    props: {
+        children: any;
+        style: Record<string, any>;
+    };
+};

package/dist/structures/SidebarLayout.js

@@ -0,0 +1,16 @@
+import { Flex } from "../primitives/Flex.js";
+import { Box } from "../primitives/Box.js";
+import { resolveResponsive } from "../core/responsiveSystem.js";
+import { normalizeUnit } from "../core/styleResolver.js";
+export function SidebarLayout({ sidebar, children, sidebarWidth = 240, viewportWidth = 1024 }) {
+    var _a;
+    // Resolve responsive sidebarWidth based on viewport
+    const resolvedWidth = normalizeUnit((_a = resolveResponsive(sidebarWidth, viewportWidth)) !== null && _a !== void 0 ? _a : 240);
+    return Flex({
+        gap: 16,
+        children: [
+            Box({ width: resolvedWidth, children: sidebar }),
+            Box({ style: { flex: 1 }, children })
+        ]
+    });
+}

package/dist/system/contracts.d.ts

@@ -0,0 +1,17 @@
+import type { CSSLength, HeadlessNode, ResponsiveValue } from "./types.js";
+export type NodeLike = HeadlessNode | string | number | boolean | null | undefined;
+export interface SidebarLayoutContract {
+    sidebar: NodeLike;
+    children: NodeLike;
+    sidebarWidth?: CSSLength | ResponsiveValue<CSSLength>;
+    viewportWidth?: number;
+}
+export interface HeaderLayoutContract {
+    header: NodeLike;
+    children: NodeLike;
+}
+export interface DashboardLayoutContract {
+    header: NodeLike;
+    sidebar: NodeLike;
+    children: NodeLike;
+}

package/dist/system/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/system/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./contracts.js";

package/dist/system/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./contracts.js";

package/dist/system/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tipe panjang CSS. Angka akan dinormalisasi ke 'px' oleh resolver.
+ */
+export type CSSLength = number | string;
+/**
+ * Responsive value that adapts based on viewport width.
+ */
+export type ResponsiveValue<T> = T | {
+    base?: T;
+    sm?: T;
+    md?: T;
+    lg?: T;
+    xl?: T;
+    "2xl"?: T;
+} | T[];
+/**
+ * Props dasar untuk layout primitives.
+ * Hanya properti yang dipetakan ke style inline.
+ */
+export interface LayoutProps {
+    padding?: CSSLength;
+    margin?: CSSLength;
+    width?: CSSLength;
+    height?: CSSLength;
+    display?: string;
+    style?: Record<string, any>;
+}
+/**
+ * Representasi node headless untuk renderer.
+ */
+export interface HeadlessNode {
+    type: string;
+    props: {
+        style?: Record<string, any>;
+        children?: any;
+        [key: string]: any;
+    };
+}

package/dist/system/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tests/basic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/basic.test.js

@@ -0,0 +1,38 @@
+const assert = (cond, msg) => {
+    if (!cond) {
+        throw new Error(`Test failed: ${msg}`);
+    }
+};
+const run = async () => {
+    const api = await import(new URL("../index.js", import.meta.url).href);
+    const { normalizeUnit, space, resolveResponsive, Flex, Box, renderToString } = api;
+    // normalizeUnit
+    assert(normalizeUnit(16) === "16px", "normalizeUnit number to px");
+    assert(normalizeUnit("2rem") === "2rem", "normalizeUnit keeps string");
+    // spacing tokens
+    assert(space(2) === "8px", "spacing index 2 is 8px");
+    // responsive resolver (object form)
+    assert(resolveResponsive({ base: 8, md: 16, xl: 24 }, 800) === 16, "resolveResponsive picks md at width 800");
+    assert(resolveResponsive({ base: 8, md: 16, xl: 24 }, 1300) === 24, "resolveResponsive picks xl at width 1300");
+    // primitives mapping + render
+    const node = Flex({
+        direction: "row",
+        gap: 16,
+        children: [
+            Box({ width: 240, children: "Sidebar" }),
+            Box({ style: { flex: 1 }, children: "Content" })
+        ]
+    });
+    const html = renderToString(node);
+    assert(html.includes("display:flex"), "Flex renders display flex");
+    assert(html.includes("flex-direction:row"), "Flex renders direction");
+    assert(html.includes("gap:16px"), "Flex renders gap 16px");
+    assert(html.includes("width:240px"), "Box width 240px");
+    assert(html.includes("flex:1"), "Box flex:1 in style");
+    console.log("All tests passed");
+};
+run().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
+export {};

package/dist/tests/structures.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/structures.test.js

@@ -0,0 +1,25 @@
+const assert = (cond, msg) => {
+    if (!cond) {
+        throw new Error(`Test failed: ${msg}`);
+    }
+};
+const run = async () => {
+    const api = await import(new URL("../index.js", import.meta.url).href);
+    const { SidebarLayout, DashboardLayout, renderToString, Box } = api;
+    const sidebar = Box({ children: "SIDE" });
+    const content = Box({ children: "MAIN" });
+    const header = Box({ children: "HEAD" });
+    const node1 = SidebarLayout({ sidebar, children: content, sidebarWidth: 200 });
+    const html1 = renderToString(node1);
+    assert(html1.includes("width:200px"), "Sidebar width applied");
+    assert(html1.indexOf("SIDE") < html1.indexOf("MAIN"), "Sidebar before content");
+    const node2 = DashboardLayout({ header, sidebar, children: content });
+    const html2 = renderToString(node2);
+    assert(html2.indexOf("HEAD") < html2.indexOf("SIDE"), "Header before sidebar/content");
+    console.log("Structures tests passed");
+};
+run().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@damarkuncoro/layout-engine",
+  "version": "0.1.0",
+  "description": "Minimal layout engine primitives and resolvers",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "layout",
+    "ui",
+    "headless",
+    "responsive",
+    "primitives"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node dist/tests/basic.test.js && node dist/tests/structures.test.js"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}