feat(render): layout position and style string parsing 👑

- Add applyStyleString to parse inline CSS and set properties via setProperty
- Add tests for applyLayout position, applyStyle, and applyStyleString
- Document layout position and style scope (HTML vs SVG) in USAGE
- Set position to relative when x or y is set and position is static
- Wrap arrow function parameters in parens in Create

Author: NeaByteLab

USAGE.md

@@ -52,24 +52,25 @@ Named exports: `create`, `render`, and all types from `Types` (re-exported). Def
 
 Each node is an object with:
 
-| Key        | Type     | Required | Description                                                 |
-| :--------- | :------- | :------- | :---------------------------------------------------------- |
-| `type`     | `string` | yes      | HTML tag name (lowercase), e.g. `div`, `a`, `table`, `svg`. |
-| `id`       | `string` | no       | Element `id` attribute.                                     |
-| `layout`   | `Layout` | no       | Width, height, position, flex, gap → CSS.                   |
-| `style`    | `Style`  | no       | Fill, stroke, font, border → CSS.                           |
-| `attrs`    | `Attrs`  | no       | Arbitrary HTML attributes (href, class, etc.).              |
-| `content`  | `string` | no       | Text content for the node.                                  |
-| `src`      | `string` | no       | Image (or similar) source URL; use with `type: 'img'`.      |
-| `alt`      | `string` | no       | Alt text for img.                                           |
-| `children` | `Node[]` | no       | Child nodes. Not allowed on void tags.                      |
+| Key        | Type     | Required | Description                                                                                                                                 |
+| :--------- | :------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`     | `string` | yes      | HTML or SVG tag name, or custom element (e.g. `div`, `a`, `svg`, `circle`). Lowercased on create. Unknown names yield `HTMLUnknownElement`. |
+| `id`       | `string` | no       | Element `id` attribute.                                                                                                                     |
+| `layout`   | `Layout` | no       | Width, height, position, flex, gap → CSS.                                                                                                   |
+| `style`    | `Style`  | no       | Fill, stroke, font, border → CSS.                                                                                                           |
+| `attrs`    | `Attrs`  | no       | Arbitrary HTML attributes (href, class, etc.).                                                                                              |
+| `content`  | `string` | no       | Text content for the node.                                                                                                                  |
+| `src`      | `string` | no       | Image (or similar) source URL; use with `type: 'img'`.                                                                                      |
+| `alt`      | `string` | no       | Alt text for img.                                                                                                                           |
+| `children` | `Node[]` | no       | Child nodes. Not allowed on void tags.                                                                                                      |
 
 Allowed keys are exactly the above. Extra keys cause validation to throw.
 
 ## Layout and Style
 
-- **Layout** — `width`, `height`, `x`, `y`, `flex`, `gap`. Number values are converted to `Npx`; strings (e.g. `'100%'`, `'auto'`) are used as-is. Applied to the element’s `style` (width, height, left, top, flex, gap). Setting `flex` or `gap` may set `display` to `block` or `flex` when needed.
+- **Layout** — `width`, `height`, `x`, `y`, `flex`, `gap`. Number values are converted to `Npx`; strings (e.g. `'100%'`, `'auto'`) are used as-is. Applied to the element’s `style` (width, height, left, top, flex, gap). When `x` or `y` is set, `position` is set to `relative` if currently static so `left`/`top` take effect. Setting `flex` or `gap` may set `display` to `block` or `flex` when needed.
 - **Style** — All string values, mapped to `element.style` (CSSStyleProperties). Semantic: `fill` → `backgroundColor`, `stroke` → `border`. Direct: `font`, `border`, `color`, `padding`, `margin`, `borderRadius`, `boxShadow`, `opacity`, `transition`.
+- **Scope** — Layout and style are applied only to **HTML elements**. For SVG nodes (e.g. `circle`, `rect` under `svg`), use `attrs` (e.g. `attrs.style` as CSS string, or SVG attributes like `fill`, `stroke`).
 
 ## Void Tags and Special Elements
 

src/Create.ts

@@ -14,7 +14,7 @@ export default class Create {
    */
   static create(definition: Types.Definition | unknown): Types.Schema {
     const validated = Validator.validateDefinition(definition)
-    const frozenRoot = validated.root.map(schemaNode => Create.freezeNode(schemaNode))
+    const frozenRoot = validated.root.map((schemaNode) => Create.freezeNode(schemaNode))
     Object.freeze(frozenRoot)
     return Object.freeze({ root: frozenRoot })
   }
@@ -36,7 +36,7 @@ export default class Create {
       Object.freeze(node.attrs)
     }
     if (node.children) {
-      const frozenChildren = node.children.map(childNode => Create.freezeNode(childNode))
+      const frozenChildren = node.children.map((childNode) => Create.freezeNode(childNode))
       Object.freeze(frozenChildren)
       return Object.freeze({ ...node, children: frozenChildren }) as Readonly<Types.Node>
     }

src/Render.ts

@@ -28,7 +28,7 @@ export default class Render {
         continue
       }
       if (key === 'style' && typeof value === 'string') {
-        ;(element as HTMLElement).style.cssText += value
+        Render.applyStyleString((element as HTMLElement).style, value)
         continue
       }
       if (
@@ -62,6 +62,32 @@ export default class Render {
     }
   }
 
+  /**
+   * Append inline CSS string to style.
+   * @description Parses prop: value pairs and sets each via setProperty.
+   * @param targetStyle - Target CSS style declaration
+   * @param inlineCssString - Inline CSS declarations (e.g. color: red; margin: 8px)
+   */
+  static applyStyleString(targetStyle: CSSStyleDeclaration, inlineCssString: string): void {
+    const declarations = inlineCssString.split(';')
+    for (const declarationPart of declarations) {
+      const colonIndex = declarationPart.indexOf(':')
+      if (colonIndex < 0) {
+        continue
+      }
+      const propertyName = declarationPart.slice(0, colonIndex).trim()
+      const propertyValue = declarationPart.slice(colonIndex + 1).trim()
+      if (propertyName === '') {
+        continue
+      }
+      try {
+        targetStyle.setProperty(propertyName, propertyValue)
+      } catch {
+        // ignore invalid property names
+      }
+    }
+  }
+
   /**
    * Apply layout to element style.
    * @description Sets width, height, left, top, flex, gap.
@@ -76,6 +102,11 @@ export default class Render {
     if (layout.height !== undefined) {
       elementStyle.height = Render.toCssValue(layout.height)
     }
+    if (layout.x !== undefined || layout.y !== undefined) {
+      if (!elementStyle.position || elementStyle.position === 'static') {
+        elementStyle.position = 'relative'
+      }
+    }
     if (layout.x !== undefined) {
       elementStyle.left = Render.toCssValue(layout.x)
     }

tests/Render.test.ts

@@ -1,6 +1,93 @@
 import { assertEquals } from '@std/assert'
 import Render from '@app/Render.ts'
 
+Deno.test('Render.applyLayout does not override existing non-static position', () => {
+  const style: Record<string, string> = { position: 'absolute' }
+  const element = { style } as unknown as HTMLElement
+  Render.applyLayout(element, { x: 0, y: 0 })
+  assertEquals(style['position'], 'absolute')
+  assertEquals(style['left'], '0px')
+  assertEquals(style['top'], '0px')
+})
+
+Deno.test('Render.applyLayout sets only left when only x present', () => {
+  const style: Record<string, string> = {}
+  const element = { style } as unknown as HTMLElement
+  Render.applyLayout(element, { x: 5 })
+  assertEquals(style['position'], 'relative')
+  assertEquals(style['left'], '5px')
+  assertEquals(style['top'], undefined)
+})
+
+Deno.test('Render.applyLayout sets position relative when x or y present', () => {
+  const style: Record<string, string> = {}
+  const element = { style } as unknown as HTMLElement
+  Render.applyLayout(element, { x: 10, y: 20 })
+  assertEquals(style['position'], 'relative')
+  assertEquals(style['left'], '10px')
+  assertEquals(style['top'], '20px')
+})
+
+Deno.test('Render.applyStyle applies expanded style properties', () => {
+  const style: Record<string, string> = {}
+  const element = { style } as unknown as HTMLElement
+  Render.applyStyle(element, {
+    color: '#333',
+    padding: '8px',
+    margin: '1rem',
+    borderRadius: '4px',
+    boxShadow: '0 1px 3px rgba(0,0,0,0.2)',
+    opacity: '0.95',
+    transition: 'opacity 0.2s ease'
+  })
+  assertEquals(style['color'], '#333')
+  assertEquals(style['padding'], '8px')
+  assertEquals(style['margin'], '1rem')
+  assertEquals(style['borderRadius'], '4px')
+  assertEquals(style['boxShadow'], '0 1px 3px rgba(0,0,0,0.2)')
+  assertEquals(style['opacity'], '0.95')
+  assertEquals(style['transition'], 'opacity 0.2s ease')
+})
+
+Deno.test('Render.applyStyle applies fill stroke font border', () => {
+  const style: Record<string, string> = {}
+  const element = { style } as unknown as HTMLElement
+  Render.applyStyle(element, {
+    fill: '#f00',
+    stroke: '1px solid blue',
+    font: '16px sans-serif',
+    border: '2px solid black'
+  })
+  assertEquals(style['backgroundColor'], '#f00')
+  assertEquals(style['border'], '2px solid black')
+  assertEquals(style['font'], '16px sans-serif')
+})
+
+Deno.test('Render.applyStyleString parses declarations and calls setProperty', () => {
+  const recorded: [string, string][] = []
+  const targetStyle = {
+    setProperty(name: string, value: string) {
+      recorded.push([name, value])
+    }
+  } as unknown as CSSStyleDeclaration
+  Render.applyStyleString(targetStyle, 'color: red; margin: 8px;')
+  assertEquals(recorded.length, 2)
+  assertEquals(recorded[0], ['color', 'red'])
+  assertEquals(recorded[1], ['margin', '8px'])
+})
+
+Deno.test('Render.applyStyleString skips empty or invalid parts', () => {
+  const recorded: [string, string][] = []
+  const targetStyle = {
+    setProperty(name: string, value: string) {
+      recorded.push([name, value])
+    }
+  } as unknown as CSSStyleDeclaration
+  Render.applyStyleString(targetStyle, ';  opacity: 0.9  ;  ')
+  assertEquals(recorded.length, 1)
+  assertEquals(recorded[0], ['opacity', '0.9'])
+})
+
 Deno.test('Render.toCssValue converts number to px string', () => {
   assertEquals(Render.toCssValue(0), '0px')
   assertEquals(Render.toCssValue(16), '16px')