odac 1.4.6 → 1.4.7

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 ### ⚙️ Engine Tuning
 
+- **test:** remove unused fsPromises and standardize async I/O in View tests
+
+### 📚 Documentation
+
+- add quick start guide and register in documentation index
+
+### 🛠️ Fixes & Improvements
+
+- add raw attribute support to `<odac get>` tag for unescaped HTML output
+- improve title extraction logic and optimize data-odac-navigate attribute injection in View rendering
+- prevent data-odac-navigate injection into closing HTML tags
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### ⚙️ Engine Tuning
+
 - replace global Odac reference with private instance and update dependency overrides for security hardening
 - **test/view:** remove unused CACHE_DIR variable in parseOdacTag tests
 

package/docs/ai/skills/backend/views.md

@@ -18,7 +18,8 @@ Views in ODAC are logic-light but powerful. They support automatic XSS protectio
 3.  **Data Binding — Two Equivalent Syntaxes**:
     -   `<odac var="key" />`: Tag-based output (HTML-escaped, XSS-safe).
     -   `{{ key }}`: Inline/interpolation output (HTML-escaped, XSS-safe). Identical behavior to `<odac var>`.
-    -   `<odac var="key" raw />` or `{!! key !!}`: Raw output (use with extreme caution).
+    -   `<odac get="key" />`: Query Parameter output (HTML-escaped, XSS-safe).
+    -   `<odac var="key" raw />`, `<odac get="key" raw />` or `{!! key !!}`: Raw output (use with extreme caution).
 4.  **Choosing the Right Syntax**:
     -   **Inside HTML attributes** (`src`, `alt`, `href`, `class`, `value`, etc.) → Always prefer `{{ }}`.
     -   **Inline within text or mixed HTML** → Prefer `{{ }}` for short interpolations.
@@ -112,6 +113,10 @@ module.exports = function (Odac) {
 <!-- Inline text interpolation -->
 <p>Welcome, {{ user.name }}. You have {{ notifications }} new messages.</p>
 
+<!-- Query parameter from URL (/page?q=search) -->
+<p>Search Results for: <odac get="q" /></p>
+<div class="raw-content"><odac get="htmlContent" raw /></div>
+
 <!-- Conditional -->
 <odac:if condition="stats.users > 100">
   <span class="badge">Popular!</span>

package/docs/backend/00-getting-started/01-quick-start.md

@@ -0,0 +1,77 @@
+## 🚀 Quick Start
+
+ODAC is built for speed and zero-configuration. You can bootstrap a production-ready, high-performance web application in seconds.
+
+### 1. Requirements
+
+- **Node.js:** 18.0.0 or higher.
+- **npm:** 8.0.0 or higher.
+
+---
+
+### 2. Initialize Your Project
+
+The standard way to start an ODAC project is using the interactive **init** command via `npx`. Run this in your terminal:
+
+```bash
+npx odac init my-app
+```
+
+**What this does:**
+- Creates a new folder named `my-app`.
+- Copies the ODAC enterprise skeleton (controllers, routes, views, etc.).
+- Initializes `package.json` with the latest ODAC framework dependency.
+- Runs `npm install` automatically.
+
+---
+
+### 3. Launch Development Mode
+
+Navigate into your project directory and start the smart development server:
+
+```bash
+cd my-app
+npm run dev
+```
+
+Your app is now live at `http://localhost:1071` (default port).
+
+**Features enabled in Dev Mode:**
+- **Hot-reloading:** The server and cluster workers restart instantly on backend changes.
+- **Zero-Config Tailwind CSS v4:** Automatically watches and compiles your styles.
+- **Detailed Stack Traces:** Helps you debug errors quickly in the browser and console.
+
+---
+
+### 4. Setup AI Agent Skills
+
+ODAC is designed to be **AI-First**. It provides pre-built "skills" (knowledge files) that teach your AI coding assistant (like Antigravity, Claude, Cursor, or Windsurf) exactly how to write ODAC-compatible code.
+
+Run this command inside your project root:
+
+```bash
+npx odac skills
+```
+
+Follow the interactive prompt to sync the documentation and patterns directly into your IDE's agent configuration folder.
+
+---
+
+### 5. Essential Commands
+
+| Command | Description |
+| :--- | :--- |
+| `npm run dev` | Start development server with hot-reload & styles. |
+| `npm run build` | Compile and minify styles for production. |
+| `npm start` | Run the application in high-performance production mode. |
+| `npx odac migrate` | Run pending database migrations. |
+| `npx odac skills` | Sync/Update AI Agent knowledge files. |
+
+---
+
+### 6. Next Steps
+
+- **Define Routes:** Open `route/web.js` to see how URLs are mapped to views.
+- **Project Structure:** Learn how to organize your [file/folder layout](../02-structure/01-typical-project-layout.md).
+- **Build Views:** Check the `view/` directory for your HTML templates.
+- **Manage Database:** Update `odac.json` to connect to PostgreSQL, MySQL, or SQLite.

package/docs/backend/07-views/03-template-syntax.md

@@ -50,6 +50,10 @@ Access URL query parameters directly:
 <!-- URL: /search?q=laptop -->
 <odac get="q" />
 <!-- Output: laptop -->
+
+<!-- Get raw query parameter (unescaped) -->
+<odac get="htmlContent" raw />
+<!-- Output: <b>Trusted HTML</b> -->
 ```
 
 **Note:** `<odac get>` is for URL parameters. For controller data, use `<odac var>`.
@@ -185,6 +189,7 @@ Full access to the Odac object in templates:
 | Raw HTML (inline) | `{!! x !!}` | [Variables](./03-variables.md) |
 | String | `<odac>text</odac>` | [Variables](./03-variables.md) |
 | Query Parameter | `<odac get="key" />` | [Request Data](./04-request-data.md) |
+| Query Parameter Raw | `<odac get="key" raw />` | [Request Data](./04-request-data.md) |
 | Translation | `<odac translate>key</odac>` | [Translations](./07-translations.md) |
 | Translation Raw | `<odac translate raw>key</odac>` | [Translations](./07-translations.md) |
 | If | `<odac:if condition="x">` | [Conditionals](./05-conditionals.md) |

package/docs/backend/07-views/04-request-data.md

@@ -33,6 +33,19 @@ If a parameter doesn't exist, it safely returns an empty string:
 
 This prevents errors when parameters are optional.
 
+### Raw HTML Output
+
+By default, `<odac get>` automatically escapes HTML special characters to prevent XSS attacks. If you need to output raw HTML from a query parameter (only from trusted sources), use the `raw` attribute:
+
+```html
+<!-- URL: /page?content=%3Cb%3EHello%3C/b%3E -->
+
+<odac get="content" raw />
+<!-- Output: <b>Hello</b> -->
+```
+
+**Security Warning:** Never use `raw` with query parameters if they can contain user-generated content. Query parameters are easily manipulated by users. Only use `raw` if you are certain the value is safe (e.g., predefined tokens).
+
 ### Difference: get vs var
 
 **`<odac get>` - Query Parameters (from URL):**

package/docs/index.json

@@ -1,5 +1,15 @@
 {
   "backend": [
+    {
+      "file": "00-getting-started",
+      "title": "Getting Started",
+      "children": [
+        {
+          "file": "01-quick-start.md",
+          "title": "Quick Start"
+        }
+      ]
+    },
     {
       "file": "01-overview",
       "title": "Backend Overview",

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.6",
+  "version": "1.4.7",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/View.js

@@ -177,7 +177,7 @@ class View {
             // Extract title if present inside the part
             const titleMatch = html.match(TITLE_REGEX)
             if (titleMatch && titleMatch[1]) {
-              title = titleMatch[1]
+              title = titleMatch[1].trim()
             }
           }
         }
@@ -187,7 +187,8 @@ class View {
       if (!title) {
         const priorityParts = ['head', 'header', 'meta']
         for (const key of priorityParts) {
-          if (this.#part[key] && !this.#odac.Request.ajaxLoad.includes(key)) {
+          // Only extract if it wasn't already processed in the main loop above
+          if (this.#part[key] && output[key] === undefined) {
             let viewPath = this.#part[key]
             if (viewPath.includes('.')) viewPath = viewPath.replace(/\./g, '/')
             if (await this.#exists(`./view/${key}/${viewPath}.html`)) {
@@ -195,7 +196,7 @@ class View {
                 const partHtml = await this.#render(`./view/${key}/${viewPath}.html`)
                 const titleMatch = partHtml.match(TITLE_REGEX)
                 if (titleMatch && titleMatch[1]) {
-                  title = titleMatch[1]
+                  title = titleMatch[1].trim()
                   break
                 }
               } catch (e) {
@@ -314,7 +315,8 @@ class View {
       }
 
       if (attrs.get) {
-        return `{{ get('${attrs.get.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}') || '' }}`
+        const escaped = attrs.get.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+        return attrs.raw ? `{!! get('${escaped}') || '' !!}` : `{{ get('${escaped}') || '' }}`
       } else if (attrs.var) {
         if (attrs.raw) {
           return `{!! ${attrs.var} !!}`
@@ -343,7 +345,8 @@ class View {
         }
 
         if (attrs.get) {
-          return `{{ get('${attrs.get.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}') || '' }}`
+          const escaped = attrs.get.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+          return attrs.raw ? `{!! get('${escaped}') || '' !!}` : `{{ get('${escaped}') || '' }}`
         } else if (attrs.var) {
           if (attrs.raw) {
             return `{!! ${attrs.var} !!}`
@@ -566,20 +569,32 @@ class View {
   }
 
   #addNavigateAttribute(skeleton) {
-    // Inject data-odac-navigate for placeholders already wrapped in an HTML tag
-    skeleton = skeleton.replace(/(<[^>]+>)(\s*\{\{\s*([A-Z_]+)\s*\}\})/g, (match, openTag, content, partName) => {
-      const attrName = partName.toLowerCase()
-      if (openTag.includes('data-odac-navigate')) return match
-      const tagWithAttr = openTag.slice(0, -1) + ` data-odac-navigate="${attrName}">`
-      return tagWithAttr + content
-    })
+    // Single-pass regex to inject data-odac-navigate into parent tags or auto-wrap unwrapped placeholders.
+    // Group 1: Opening tag (<tag>)
+    // Group 2: Whitespace between tag and placeholder
+    // Group 3: Placeholder ({{ PART_NAME }})
+    // Group 4: Part name inside wrapped placeholder
+    // Group 5: Standalone/Unwrapped placeholder
+    // Group 6: Part name inside unwrapped placeholder
+    skeleton = skeleton.replace(
+      /(<(?!\/)[^>]+>)(\s*)(\{\{\s*([A-Z_]+)\s*\}\})|(\{\{\s*([A-Z_]+)\s*\}\})/g,
+      (match, openTag, spaces, wrappedPlaceholder, wrappedPartName, unwrappedPlaceholder, unwrappedPartName) => {
+        if (openTag) {
+          // Case 1: Placeholder immediately follows an opening tag. Inject attribute into the tag.
+          const attrName = wrappedPartName.toLowerCase()
+          const tagWithAttr = openTag.includes('data-odac-navigate') ? openTag : openTag.slice(0, -1) + ` data-odac-navigate="${attrName}">`
+          return `${tagWithAttr}${spaces}${wrappedPlaceholder}`
+        }
 
-    // Auto-wrap unwrapped placeholders so AJAX navigation can target them
-    // Uses display:contents to avoid breaking flex/grid layouts
-    skeleton = skeleton.replace(/(?<!>)\s*(\{\{\s*([A-Z_]+)\s*\}\})/g, (match, placeholder, partName) => {
-      const attrName = partName.toLowerCase()
-      return `<div style="display:contents" data-odac-navigate="${attrName}">${placeholder}</div>`
-    })
+        if (unwrappedPlaceholder) {
+          // Case 2: Placeholder is unwrapped (e.g. sibling to a closing tag). Wrap in display:contents.
+          const attrName = unwrappedPartName.toLowerCase()
+          return `<div style="display:contents" data-odac-navigate="${attrName}">${unwrappedPlaceholder}</div>`
+        }
+
+        return match
+      }
+    )
 
     const skeletonName = this.#part.skeleton || 'main'
     const pageName = this.#odac.Request.page || ''

package/test/View/addNavigateAttribute.test.js

@@ -0,0 +1,53 @@
+const fs = require('fs').promises
+const path = require('path')
+const View = require('../../src/View')
+
+describe('View.#addNavigateAttribute()', () => {
+  let view
+  let mockOdac
+
+  beforeEach(() => {
+    global.__dir = path.resolve(__dirname, '../../')
+    mockOdac = {
+      Config: {view: {earlyHints: {enabled: false}}},
+      View: {},
+      Request: {
+        req: {url: '/test'},
+        res: {finished: false},
+        isAjaxLoad: false,
+        header: jest.fn(),
+        end: jest.fn(),
+        get: jest.fn(),
+        hasEarlyHints: jest.fn().mockReturnValue(false)
+      },
+      Lang: {get: jest.fn()}
+    }
+    view = new View(mockOdac)
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+    delete global.__dir
+  })
+
+  it('should not wrap placeholder in display:contents if it is the first child of an element', async () => {
+    const skeletonDir = path.join(global.__dir, 'skeleton')
+    const contentDir = path.join(global.__dir, 'view/content/pages')
+    await fs.mkdir(skeletonDir, {recursive: true})
+    await fs.mkdir(contentDir, {recursive: true})
+
+    await fs.writeFile(path.join(skeletonDir, 'main.html'), '<main id="app-main">\n  {{ CONTENT }}\n</main>')
+    await fs.writeFile(path.join(contentDir, 'test.html'), '<h1>Content</h1>')
+
+    view.skeleton('main').set({content: 'pages/test'})
+
+    await view.print()
+
+    expect(mockOdac.Request.end).toHaveBeenCalled()
+    const outputHtml = mockOdac.Request.end.mock.calls[0][0]
+
+    expect(outputHtml).toContain('<main id="app-main" data-odac-navigate="content">')
+    expect(outputHtml).toContain('<h1>Content</h1>')
+    expect(outputHtml).not.toContain('<div style="display:contents"')
+  })
+})

package/test/View/print.test.js

@@ -1,3 +1,5 @@
+const fs = require('fs').promises
+const path = require('path')
 const View = require('../../src/View')
 
 describe('View.print()', () => {
@@ -5,15 +7,57 @@ describe('View.print()', () => {
   let mockOdac
 
   beforeEach(() => {
+    global.__dir = path.resolve(__dirname, '../../')
     mockOdac = {
       Config: {view: {earlyHints: {enabled: false}}},
       View: {},
-      Request: {data: {all: {}}}
+      Request: {
+        req: {url: '/test'},
+        res: {finished: false},
+        isAjaxLoad: false,
+        header: jest.fn(),
+        end: jest.fn(),
+        get: jest.fn(),
+        hasEarlyHints: jest.fn().mockReturnValue(false)
+      },
+      Lang: {get: jest.fn()}
     }
     view = new View(mockOdac)
   })
 
+  afterEach(() => {
+    jest.restoreAllMocks()
+    delete global.__dir
+  })
+
   it('should be a function', () => {
     expect(typeof view.print).toBe('function')
   })
+
+  describe('AJAX Rendering Edge Cases', () => {
+    it("should extract title from priority parts even if their view path hasn't changed", async () => {
+      const headDir = path.join(global.__dir, 'view/head/inc')
+      const contentDir = path.join(global.__dir, 'view/content/pages')
+      await fs.mkdir(headDir, {recursive: true})
+      await fs.mkdir(contentDir, {recursive: true})
+
+      await fs.writeFile(path.join(headDir, 'head.html'), '<title>Dynamic Title</title>')
+      await fs.writeFile(path.join(contentDir, 'test.html'), '<h1>Test</h1>')
+
+      mockOdac.Request.isAjaxLoad = true
+      mockOdac.Request.ajaxLoad = ['head', 'content']
+      mockOdac.Request.clientParts = {head: 'inc/head'}
+      mockOdac.Request.page = 'test_page'
+
+      view.set({head: 'inc/head', content: 'pages/test'})
+
+      await view.print()
+
+      expect(mockOdac.Request.end).toHaveBeenCalled()
+
+      const payload = mockOdac.Request.end.mock.calls[0][0]
+      expect(payload.output.head).toBeUndefined()
+      expect(payload.title).toBe('Dynamic Title')
+    })
+  })
 })

package/test/View/tags.test.js

@@ -0,0 +1,132 @@
+const fs = require('fs')
+const fsPromises = fs.promises
+const path = require('path')
+const View = require('../../src/View')
+
+const FIXTURE_DIR = path.resolve(__dirname, '_fixtures_get')
+
+describe('View odac tags (var, get, translate) raw attribute', () => {
+  let originalDir
+  let originalCwd
+
+  beforeAll(async () => {
+    await fsPromises.mkdir(path.join(FIXTURE_DIR, 'skeleton'), {recursive: true})
+    await fsPromises.mkdir(path.join(FIXTURE_DIR, 'view', 'content'), {recursive: true})
+  })
+
+  afterAll(async () => {
+    await fsPromises.rm(FIXTURE_DIR, {recursive: true, force: true})
+  })
+
+  beforeEach(() => {
+    originalDir = global.__dir
+    originalCwd = process.cwd()
+    global.__dir = FIXTURE_DIR
+    process.chdir(FIXTURE_DIR)
+
+    if (global.Odac?.View?.cache) {
+      global.Odac.View.cache = {}
+    }
+    if (global.Odac?.View?.skeletons) {
+      global.Odac.View.skeletons = {}
+    }
+
+    for (const key of Object.keys(require.cache)) {
+      if (key.includes('.cache')) {
+        delete require.cache[key]
+      }
+    }
+  })
+
+  afterEach(() => {
+    global.__dir = originalDir
+    process.chdir(originalCwd)
+  })
+
+  let testCounter = 0
+
+  async function renderTemplate(templateContent, getValues = {}) {
+    const uniqueId = `test_get_${++testCounter}`
+    const viewFile = path.join(FIXTURE_DIR, 'view', 'content', `${uniqueId}.html`)
+    await fsPromises.writeFile(viewFile, templateContent, 'utf8')
+
+    const skeletonFile = path.join(FIXTURE_DIR, 'skeleton', 'main.html')
+    await fsPromises.writeFile(skeletonFile, '{{ CONTENT }}', 'utf8')
+
+    let capturedOutput = ''
+    const mockOdac = {
+      Config: {debug: true},
+      Var: value => {
+        const str = value === null || value === undefined ? '' : String(value)
+        return {
+          html: () => str.replace(/[&<>"']/g, m => ({'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'})[m])
+        }
+      },
+      Request: {
+        get: key => getValues[key] || '',
+        req: {url: '/test'},
+        res: {finished: false, headersSent: false},
+        isAjaxLoad: false,
+        ajaxLoad: [],
+        variables: {},
+        sharedData: {},
+        page: '',
+        header: () => {},
+        end: output => {
+          capturedOutput = output
+        },
+        hasEarlyHints: () => false,
+        setEarlyHints: () => {}
+      },
+      Lang: {
+        get: (...args) => args[0]
+      },
+      View: {}
+    }
+
+    const view = new View(mockOdac)
+    view.skeleton('main')
+    view.set('content', uniqueId)
+    await view.print()
+
+    return capturedOutput
+  }
+
+  it('should escape <odac get> by default', async () => {
+    const result = await renderTemplate('<odac get="html" />', {html: '<b>bold</b>'})
+    expect(result).toContain('&lt;b&gt;bold&lt;/b&gt;')
+    expect(result).not.toContain('<b>')
+  })
+
+  it('should not escape <odac get> when raw attribute is present (self-closing)', async () => {
+    const result = await renderTemplate('<odac get="html" raw />', {html: '<b>bold</b>'})
+    expect(result).toContain('<b>bold</b>')
+  })
+
+  it('should not escape <odac get> when raw attribute is present (block-level)', async () => {
+    const result = await renderTemplate('<odac get="html" raw></odac>', {html: '<b>bold</b>'})
+    expect(result).toContain('<b>bold</b>')
+  })
+
+  it('should handle missing parameters gracefully with raw', async () => {
+    const result = await renderTemplate('<odac get="missing" raw />', {})
+    expect(result).toContain('data-odac-navigate="content"')
+    expect(result).toContain('id="odac-data"')
+  })
+
+  it('should not escape <odac translate> when raw attribute is present', async () => {
+    const result = await renderTemplate('<odac translate raw><b>bold</b></odac>')
+    expect(result).toContain('<b>bold</b>')
+    expect(result).not.toContain('&lt;b&gt;')
+  })
+
+  it('should escape <odac var> by default', async () => {
+    const result = await renderTemplate('<script:odac>var htmlVar = "<em>test</em>";</script:odac><odac var="htmlVar" />')
+    expect(result).toContain('&lt;em&gt;test&lt;/em&gt;')
+  })
+
+  it('should not escape <odac var> when raw attribute is present', async () => {
+    const result = await renderTemplate('<script:odac>var htmlVar = "<em>test</em>";</script:odac><odac var="htmlVar" raw />')
+    expect(result).toContain('<em>test</em>')
+  })
+})