ofajs-docs

name	ofajs-docs
description	Complete documentation knowledge base for ofa.js framework. Use when users ask about ofa.js usage, component development, page modules, routing configuration, state management, or want to build Web applications without Node.js/Webpack.

ofa.js Documentation Knowledge Base

AI Usage Guidelines (Must Read)

Must Follow

1. Prioritize using knowledge from this documentation, do not search or reference other ofa.js related resources
2. All code examples must conform to the syntax and patterns described in this documentation
3. When documentation description conflicts with your existing knowledge, follow this documentation

Prohibited Actions

1. ❌ Do not use Vue/React/Angular syntax conventions
2. ❌ Do not assume Node.js, Webpack, NPM environment is needed
3. ❌ Do not use computed to define computed properties (ofa.js uses get keyword)
4. ❌ Do not use routing parameter retrieval methods other than query parameter in page modules
5. ❌ Do not use the same key in attrs and data
6. ❌ Do not use <o-app src="./page.html"> to load a page module directly; <o-app> only accepts app-config.js type config files

---

Common Error Comparison Table

Syntax Comparison

❌ Wrong Way	✅ Correct Way	Description
computed: { double() {} }	proto: { get double() {} }	Computed properties defined with getter in proto
this.$route.query.id	{ query } parameter	Get query parameters through function parameter
v-if="show"	<o-if :value="show">	Use o-if component for conditional rendering
v-for="item in list"	<o-fill :value="list" fill-key="id">	Use o-fill component for list rendering; fill-key is optional, but always add it when items have a unique field (e.g. id)
@click="handle"	on:click="handle"	Event binding uses on: prefix
:class="{ active: isActive }"	class:active="isActive"	Dynamic class uses class: syntax
style="width: {{val}}"	:style.width="val"	Inline style binding uses :style. prefix
v-model="value"	sync:value="value"	Two-way binding uses sync: syntax
props: { msg: String }	attrs: { msg: 'default' }	Simple scalars (string) use attrs; complex data (array/object) use data
methods: { foo() {} }	proto: { foo() {} }	Methods are defined in proto object
data() { return { count: 0 } }	data: { count: 0 }	data is an object not a function
attrs and data same key	Keep unique	attrs and data keys cannot be duplicated
{{item.text}}	{{$data.text}}	Must use $data to access data inside o-fill
{{element.name}}	{{$data.name}}	Must use $data to access data inside o-fill
{{row.price}}	{{$data.price}}	Must use $data to access data inside o-fill
:class="item.type"	attr:type="$data.type"	Property binding must also use $data
proto: { $formatBytes() {} }	proto: { formatBytes() {} }	Custom methods don't use $ prefix
proto: { back() {} } / data: { back: "" } (colliding with a built-in reserved name)	Avoid back / goto / replace / pageAnime / pageIsReady / src and any method on $.fn for custom methods/fields	These names are already taken by ofa.js: back() / goto() / replace() are the page instance's built-in navigation methods (back() is equivalent to this.app.back()), src is the page address property, and the generic $.fn methods (on / emit / $ / text, etc.) are unavailable too. On collision, newer versions throw a registration error like "'back' on 'proto' is already taken" and the whole page fails to register; a data field collision throws directly. See the detailed example below
title="{{name}}" / :title="name"	attr:title="name"	{{...}} in attribute values is NOT parsed; dynamic attributes must use attr:
attr:style="width: {{pct}}%"	:style.width="pct + '%'"	{{...}} is NOT parsed in attribute values; dynamic styles use :style.
:disabled="isLoading" (boolean attributes like disabled/checked/readonly)	attr:disabled="isLoading"	:prop renders false as the attribute string "false"; HTML boolean attributes take effect whenever present, so the button stays disabled forever; attr: cancels the attribute setting entirely when the value is false

API Comparison

❌ Wrong Way	✅ Correct Way	Description
.click(handler)	.on("click", handler)	Event binding uses .on() method
.hide() .show()	.style.display = "none" / ""	No jQuery-style show/hide methods
.html("xxx") .text("xxx")	.html = "xxx" .text = "xxx"	Set properties directly, not call methods
ofaElement.addEventListener()	ofaElement.on()	ofa.js objects use on() method
this.shadow.getElementById("id")	this.shadow.$("#id")	shadow is an ofa.js object, use $() method
this.shadow.querySelector(".class")	this.shadow.$(".class")	Use $() method to select elements
ofaElement.scrollTop etc.	ofaElement.ele.scrollTop	ofa.js objects access native properties via .ele
document.querySelector("#id")	$("#id")	Use $() to get element instances globally; document.querySelector returns native elements lacking ofa.js enhanced methods and reactive features
document.querySelector("o-app").goto(...)	$("o-app").goto(...) or this.app.goto(...)	Navigation methods like goto()/replace() only exist on $() wrapper objects, not on native DOM elements; inside page modules use this.app.goto(...)
$("o-app").current.shadowRoot	$("o-app").current.ele.shadowRoot	$("o-app").current also returns an ofa.js wrapper object; native properties (shadowRoot, querySelector, etc.) must go through .ele, while ofa.js own properties (, , ) can be accessed directly

Structure Comparison

❌ Wrong Way	✅ Correct Way	Description
<script> outside <template>	<script> inside <template>	script must be placed inside template tag
export default async () => ({...})	export default async ({ query }) => ({...})	Page module should use parameter form to receive query
<o-fill><template><div>...</div></template></o-fill>	<o-fill><div>...</div></o-fill>	Direct rendering doesn't need template wrapper
<template> inside o-fill	<template> outside o-fill + name attribute	Template rendering requires template outside with name attribute
<o-app src="./page.html?key=val"> to embed a sub-page inside a page	<o-page src="./page.html?key=val">	Embed a page module with <o-page>; <o-app> is for micro-apps with app-config.js
Use autoInstall in HTML	Use auto-install in HTML	Component attrs use camelCase in definitions, but must be converted to kebab-case (hyphenated) when used in HTML
location.origin + location.pathname + "#./pages/x.html"	location.origin + "/#/pages/x.html"	Hash routing format is #/pages/xxx.html (a / directly after #, no ./ prefix, no extra pathname); use location.origin + "/#/..." when building external share links
Setting src on <o-page> after initialization (including :src="url" dynamic binding, changing query to pass params)	Keep <o-page> resident + host calls a method exposed by the sub-page to pass params	The src of <o-page> is immutable after initialization; assigning it again throws A page that has already been initialized cannot be set with the src attribute; to destroy and recreate, wrap with to toggle

Detailed Example: {{...}} Scope (Important)

{{expr}} only works in element text content. Writing it in HTML attribute values will NOT be parsed - the browser treats the entire curly braces as a static string.

❌ Wrong Way (using {{}} in attribute values):

<span title="{{$data.appId}}">{{$data.appId}}</span>
<a href="{{url}}">Link</a>
<img alt="{{name}}" src="/x.png">
<div data-id="{{id}}"></div>

✅ Correct Way (attributes always use attr: / :prop / class: / :style.):

<span attr:title="$data.appId">{{$data.appId}}</span>
<a attr:href="url">Link</a>
<img attr:alt="name" src="/x.png">
<div attr:data-id="id"></div>

Memory rule: {{}} only goes between >...<; all dynamic values inside the angle brackets use attr: / :prop / class: / :style. directives.

Why can't {{}} work in attribute values?

• The browser first parses HTML into a DOM tree, and attribute values become static strings at this point
• ofa.js template engine can only process DOM nodes, it cannot re-parse {{}} in attribute values
• Only text nodes (content between >...<) are correctly parsed and reactively updated by ofa.js

Detailed Example: Boolean Attributes Must Use attr: (Important)

HTML boolean attributes like disabled / checked / readonly / hidden / open are presence-based — the attribute value doesn't matter; as long as the attribute exists, it takes effect. When binding a boolean state to such attributes, you must use attr:, not :prop.

❌ Wrong Way (:prop renders false as the attribute string "false", the attribute still exists, so the button stays disabled forever):

<p-button color="primary" :disabled="analyzing">Analyze</p-button>
<!-- When analyzing === false, it renders disabled="false" — still disabled! -->

✅ Correct Way (the attr: rendering syntax removes the attribute setting entirely when it sees false):

<p-button color="primary" attr:disabled="analyzing">Analyze</p-button>
<!-- analyzing === false → no disabled attribute; analyzing === true → attribute present, disabled -->

Why does :prop bite?

• A :prop-bound false gets serialized into the string "false" and lands on the attribute
• HTML boolean attributes are judged by presence: both disabled="false" and disabled="true" count as present (disabled)
• The attr: directive treats false specially: it removes the attribute entirely — no attribute means enabled again

Scope: all "present = on, absent = off" native boolean attributes, as well as boolean component properties defined via attrs and forwarded inside the shadow template with attr:xxx="xxx" (e.g. the disabled of punch-ui's p-button).

Detailed Example: Dynamic Class Name vs Attribute Binding

Data inherent properties (like type, status, level) should use attr: + attribute selector; style state switching (like active, disabled) should use class: + class selector.

❌ Wrong Way (using data property as class name):

<div class="message" :class="$data.type">
  {{$data.text}}
</div>

<style>
.message.sent { color: blue; }
.message.received { color: green; }
</style>

✅ Correct Way (using attribute binding):

<div class="message" attr:type="$data.type">
  {{$data.text}}
</div>

<style>
.message[type="sent"] { color: blue; }
.message[type="received"] { color: green; }
</style>

Why is this better?

• Clear semantics - type is a property of message type, not a style class
• Data-driven - Directly bind data property to HTML attribute
• More precise CSS - Attribute selectors are more semantic than class selectors
• Maintainable code - Property names match data field names, easier to understand

Detailed Example: ofa.js Object vs Native DOM Element

Elements obtained via $() are ofa.js wrapper objects with enhanced methods and reactive features; access native DOM elements via the .ele property.

Shadow object selector methods: this.shadow returns an ofa.js instantiated object, not a native ShadowRoot.

❌ Wrong Way (using native API):

const messagesDiv = this.shadow.getElementById("messages");
const element = this.shadow.querySelector(".class");

✅ Correct Way (using ofa.js API):

const messagesDiv = this.shadow.$("#messages");
const element = this.shadow.$(".class");

Native DOM property access: element.$() returns an ofa.js wrapper object; native properties need to be accessed via .ele.

❌ Wrong Way (operating directly on ofa.js object):

const messagesDiv = this.shadow.$("#messages");
messagesDiv.scrollTop = messagesDiv.scrollHeight;  // scrollTop is a native property

✅ Correct Way (accessing native properties via .ele):

const messagesDiv = this.shadow.$("#messages");
messagesDiv.ele.scrollTop = messagesDiv.ele.scrollHeight;

Use cases:

• ofa.js methods: Use ofa.js object methods (e.g., .on(), .text, .html, etc.)
• Native properties: Access native DOM properties via .ele (e.g., .scrollTop, .scrollHeight, .clientWidth, etc.)

Common pitfall in Playwright tests / browser console: $("o-app").current also returns an ofa.js wrapper object, NOT a native DOM element. Accessing shadow DOM is easy to get wrong here.

❌ Wrong Way (accessing native properties directly on wrapper object):

// In Playwright tests or browser console
const cur = $("o-app").current;
cur.shadowRoot                    // → undefined (shadowRoot is a native property)
cur.shadowRoot.querySelector(...) // → throws "not a function"

✅ Correct Way (go through .ele for native properties; ofa.js own properties can be accessed directly):

const cur = $("o-app").current;
cur.ele.shadowRoot                          // ✅ Access native shadowRoot via .ele
cur.ele.shadowRoot.querySelector(".item")   // ✅ Native query
cur.src                                     // ✅ ofa.js wrapper properties can be accessed directly
cur.data                                    // ✅ ofa.js data can be accessed directly

Scenario	❌ Wrong Way	✅ Correct Way
Get current page's shadow DOM in Playwright/browser	$("o-app").current.shadowRoot	$("o-app").current.ele.shadowRoot
Query elements inside current page in tests	$("o-app").current.shadowRoot.querySelector(...)	$("o-app").current.ele.shadowRoot.querySelector(...)

Memory rule: $() returns an ofa.js wrapper object, and .current is also a wrapper object. ofa.js own properties (.src/.data/.app) are used directly; browser-native properties and methods (.shadowRoot/.querySelector/.scrollTop) must always go through .ele.

Detailed Example: Method Naming Convention

$ is a reserved prefix for ofa.js built-in special variables ($data, $index, $host, $event). Custom proto methods must NOT use the $ prefix.

❌ Wrong Way (method name with $ prefix):

export default async () => {
  return {
    tag: "my-component",
    data: { size: 1024 },
    proto: {
      $formatBytes(val) {
        return (val / 1024).toFixed(2) + " KB";
      }
    }
  };
};

<span>{{$formatBytes(size)}}</span>

✅ Correct Way (direct naming without prefix):

export default async () => {
  return {
    tag: "my-component",
    data: { size: 1024 },
    proto: {
      formatBytes(val) {
        return (val / 1024).toFixed(2) + " KB";
      }
    }
  };
};

<span>{{formatBytes(size)}}</span>

Calling via $host in o-fill also without $:

<o-fill :value="files" fill-key="id">
  <span>{{$host.formatBytes($data.size)}}</span>
</o-fill>

Detailed Example: proto / data Must Not Collide with Built-in Reserved Names (Important)

The proto methods and data fields of a page module must not use names already occupied by ofa.js, otherwise module registration fails outright (the whole page cannot render). Newer versions log:

Page http://.../xxx.html has invalid registration parameters: 'back' on 'proto' is already taken, please rename 'back' to something else.

Reserved built-in names (provided by the page instance):

• Page navigation methods: back() (go back; equivalent to this.app.back()), goto(), replace()
• Page properties: src (page address), pageAnime (transition animation), pageIsReady
• Generic $.fn methods (on / off / emit / $ / text / html / css / data, etc.)

A data field colliding with a reserved name throws directly (page_invalid_key); a proto method collision throws a registration error in newer versions, while older versions only console.warn — but the method still gets overwritten by the built-in implementation, so behavior is equally unreliable.

❌ Wrong Way (custom back collides with the built-in back-navigation method):

export default async () => ({
  data: { dialogOpen: false },
  proto: {
    back() {           // ❌ Collides with built-in back() navigation
      this.phase = "input";
    },
  },
});

✅ Correct Way (use a non-colliding, semantic name):

export default async () => ({
  data: { dialogOpen: false },
  proto: {
    backToInput() {    // ✅ Semantic name avoids collision with built-in back()
      this.phase = "input";
    },
  },
});

Debugging mnemonic: when the error says "'xxx' on 'proto' is already taken", that name is a built-in reserved name. First avoid back / goto / replace / src / pageAnime / pageIsReady and the generic methods on $.fn (see the built-in proto definitions in packages/ofa/page.mjs); prefer business-semantic names for custom methods (e.g. openXxx / saveXxx / backToInput).

Detailed Example: Dynamic Style Syntax

{{...}} is NOT parsed in attribute values. For dynamic values:

• Regular attributes → attr:attributeName="expression"
• Component properties → :propertyName="expression" / sync:propertyName="expression"
• Class names → class:className="booleanExpression"
• Styles → :style.propertyName="expression"

❌ Wrong Way (using {{}} in attribute value, will NOT be parsed):

<div attr:style="width: {{pct}}%"></div>

✅ Correct Way (using :style. to bind individual style property):

<div :style.width="pct + '%'"></div>

Why is this better?

• Correct syntax - {{...}} in attribute values is NOT parsed, must use directive binding
• Full expression - :style. value is a JavaScript expression, can freely concatenate strings
• Better performance - Only updates individual style properties, not the entire style string

Detailed Example: Getter Template Pitfall (Important)

When using get xxx() {} to define a computed property for template {{xxx}} in a page module, the getter is evaluated immediately during module initialization, before ready() runs. If the getter accesses an object/array field in this.data that hasn't been initialized yet (especially null/undefined or deep chained access), a TypeError will be thrown and the entire page render will crash.

Typical error:

Error: Error evaluating text expression: 'roleText'

❌ Wrong Way (getter depends on asynchronously fetched data):

export default async ({ query }) => {
  return {
    data: {
      userInfo: {},  // Initially an empty object
    },
    get roleText() {
      // Evaluated immediately at template init, userInfo is still {}
      // Throws TypeError if userInfo is null/undefined or via deep chained access
      return ROLE_TEXT[this.userInfo.role] || "";
    },
    ready() {
      this.loadInfo(); // Asynchronously assigns userInfo, but too late
    },
    proto: {
      async loadInfo() { /* ... */ }
    }
  };
};
// Template: {{roleText}}

✅ Correct Way (predefine a safe default in data, assign in async callback):

export default async ({ query }) => {
  return {
    data: {
      userInfo: {},
      roleText: "",  // Predefine a safe default value
    },
    ready() {
      this.loadInfo();
    },
    proto: {
      async loadInfo() {
        const info = await api.getInfo();
        this.userInfo = info;
        this.roleText = ROLE_TEXT[info.role] || info.role || ""; // Assign in async callback
      },
    },
  };
};
// Template: {{roleText}}

Getter applicability boundaries:

• ✅ Suitable: Simple computations depending only on synchronously available data with initial values, e.g., get double() { return this.count * 2 } (count has initial value 0)
• ❌ Not suitable: Computations whose results depend on asynchronously fetched data (objects/arrays filled only after an API returns). Use a data field and assign it in an async callback instead

Why is the getter evaluated immediately?

• The ofa.js template engine scans all {{xxx}} expressions in the template during module initialization and establishes reactive dependencies
• The getter is read at this point, triggering access to this.xxx inside the getter and establishing dependency tracking
• ready() only runs after initialization completes; async data hasn't arrived yet
• If the field accessed inside the getter body is null/undefined, chained reading throws an error, interrupting the entire template render

Detailed Example: Template Variables Must Be Declared in data/attrs First (Important)

All template expressions ({{xxx}}, :prop, sync:, class:, :style., attr:) are evaluated immediately during module initialization, and every key they reference must already be declared in data / attrs. Referencing an undeclared variable does NOT yield undefined — it throws directly and interrupts the whole page render:

Error: Error evaluating element expression: ':value="flag"', from file: ...
Caused by: ReferenceError: flag is not defined

Typical scenario: adding a new feature to an existing page — the template gets new bindings but you forget to add the field to data. The error appears on first render, and the entire page/component render fails.

❌ Wrong Way (template uses noBg, not declared in data):

<x-if :value="noBg === 'off'">...</x-if>
<p-switch sync:value="noBg">No background</p-switch>

<script>
  export default async () => ({
    data: { dialogOpen: false }, // ❌ noBg declaration missing
  });
</script>

✅ Correct Way (declare it in data with a safe default):

<script>
  export default async () => ({
    data: { dialogOpen: false, noBg: "off" }, // ✅ every template-referenced key is declared
  });
</script>

Debugging mnemonic: Error evaluating element/class/... expression + ReferenceError: xxx is not defined → a template expression references a key that doesn't exist in data / attrs. Grep the template for xxx bindings first, then add the declaration to data.

Difference from the getter pitfall: the getter pitfall is a field declared but its value not arrived yet (throws TypeError); this pitfall is a field never declared at all (throws ReferenceError) — the latter is the easiest to hit when editing templates.

Detailed Example: Hash Routing URL Format

When building external share links (invitation links, email links, etc.) or using URLs to navigate directly in tests, the hash format is easy to get wrong.

ofa.js hash routing format: #/pages/xxx.html (a / directly after #, no ./ prefix).

❌ Wrong Way (extra pathname and ./ prefix):

const link = location.origin + location.pathname + "#./pages/set-password.html?token=xxx";
// Result: http://host/index.html#./pages/set-password.html?token=xxx  ← Wrong

✅ Correct Way (/ directly after #, no pathname):

const link = location.origin + "/#/pages/set-password.html?token=xxx";
// Result: http://host/#/pages/set-password.html?token=xxx  ← Correct

Memory rule: A / immediately follows #, then the path starting from pages. For external share links, use location.origin + "/#/...".

Detailed Example: Splitting a Complex Single Page into Multiple Page Modules (Important)

When a single page module accumulates too much business (main list + dialog forms + multiple sub-flows), split independent business units (especially dialog forms) into separate page modules. The host embeds them with a resident <o-page>, communicating via "method call to pass params down + event bubbling to pass results up":

• Host → sub-page: call a method exposed by the sub-page (e.g., openForm(params)) to pass params
• Sub-page → host: this.emit("xxx-save", { data, bubbles: true, composed: true }); the host listens with on:xxx-save on the <o-page> tag and reads from event.data
• composed: true is mandatory: the sub-page lives inside the host's Shadow DOM; when left as the default false, the event cannot cross the boundary and the host won't hear it

❌ Wrong Way (changing src after initialization to switch params — throws at runtime):

<o-page :src="'./form.html?id=' + editingId"></o-page>

The src of <o-page> is immutable after initialization; the source code throws directly on reassignment: A page that has already been initialized cannot be set with the src attribute.

✅ Correct Way:

<!-- Host page -->
<template page>
  <o-page id="form-page" src="./form.html" on:form-save="onSave"></o-page>
  <script>
    export default async () => ({
      proto: {
        openForm(item) {
          // $() returns an ofa.js wrapper object; call the sub-page method directly
          this.shadow.$("#form-page")?.openForm(item);
        },
        onSave(event) {
          console.log(event.data); // form values emitted by the sub-page
        },
      },
    });
  </script>
</template>

<!-- Sub-page form.html: carries its own p-dialog, exposes openForm for the host -->
<template page>
  <p-dialog sync:open="dialogOpen" auto-close><!-- form controls sync:value="form.xxx" --></p-dialog>
  <script>
    export default async () => ({
      data: { dialogOpen: false, form: {} },
      proto: {
        openForm(params) {
          Object.assign(this.form, params); // fill in params
          this.dialogOpen = true;
        },
        save() {
          if (!this.form.name.trim()) return; // sub-page only validates non-empty
          this.emit("form-save", {
            data: { ...this.form },
            bubbles: true,
            composed: true, // cross Shadow DOM so the host can hear it
          });
          this.dialogOpen = false;
        },
      },
    });
  </script>
</template>

Division of responsibility: the sub-page only handles form completeness and UI state; business normalization, id generation, and persistence belong to the host. Cancel/backdrop close only flips the sub-page's own dialogOpen and does not notify the host.

When a fresh instance is needed each time: if the sub-page is allowed to lose state, wrap <o-page> with o-if — closing destroys it, reopening recreates it (o-if toggling clears and re-renders its children); after reopening, params must be passed again via method call.

When to split:

• The dialog contains an independent form / multi-step flow → split
• The page's data is polluted with lots of temporary state unrelated to the main content (form / dialogOpen / editingId …) → split
• Small purely-presentational fragments with no independent business state → use a component module, don't split into a page

Detailed Example: Directive Values Are JS Expressions — Bare Literals (Especially Reserved Words) Throw Errors (Important)

The values of attr: / :prop / sync: / class: / :style. / on: are always parsed as JavaScript expressions. You cannot write bare identifiers or bare string literals. Strings must be quoted; JS reserved words (in / class / for, etc.) on their own are illegal as expressions and throw a SyntaxError immediately.

Typical error (console keeps logging the error, some page functionality breaks):

SyntaxError: Unexpected token 'in'

❌ Wrong Way (writing attr:data-type="in" as a plain attribute value with a bare literal — in is a JS reserved word parsed as an expression):

<button attr:data-type="in">Stock in</button>
<!-- ofa.js treats the value "in" as an expression → SyntaxError: Unexpected token 'in' -->

✅ Correct Way (method name / string literal inside expression):

<button on:click="$host.stockIn($event)">Stock in</button>
<!-- Bind the event to a method name to avoid writing bare literals in directive values -->

<button attr:data-type="'in'">Stock in</button>
<!-- When you really need to pass a literal, quote it as a string expression -->

Debugging mnemonic: SyntaxError: Unexpected token '<xxx>' (words like in/for/if) → a bare identifier was written in a directive attribute value. Prefer refactoring "type-identifying" scenarios into method dispatch (e.g. on:click="$host.stockIn($event)"), and quote string literals when placing them in attr: values (attr:data-type="'in'").

Detailed Example: Page Module Cache Makes Code Changes Not Take Effect (Easiest to Misdiagnose When Debugging/Testing)

ofa.js has an in-memory module cache for already-loaded page modules (reusing component/page module definitions for the same URL), and pages pull their template files via fetch — if the static server sends HTTP caching headers (e.g. http-server without -c-1), the browser also hits the disk cache. The combined effect of both caches: you change the page file, but hash navigation (without a full page reload) still renders the old version, with no errors in the console — extremely easy to misdiagnose as "my code is wrong" and waste time debugging.

Typical scenario: in Playwright tests or a browser, navigating directly to #/pages/xxx.html for debugging; after repeatedly modifying the page template, the effect never changes. Even corrupting the file into an obviously broken version still renders the old logic normally.

✅ Correct approach:

• The dev server must disable HTTP caching: http-server . -p 5173 -c-1 (-c-1 = disable cache; npm run dev already includes it, npm start does not).
• To force a reload in tests/debugging, do a full-page refresh with a complete URL carrying a query: http://localhost:5173/index.html?t=v1#/pages/xxx.html — when the query changes, fetch treats it as a new URL and bypasses the cache.
• In Playwright, don't rely on "navigate the hash then wait for the module to update"; use page.goto(url) to load the whole page directly.

Debugging mnemonic: code changes not taking effect + no console errors → suspect caching first (module cache / HTTP cache); force-refresh with a query-bearing URL to rule it out. Don't bisect your own code first.

---

Detailed Example: $host / $data Are Only Available in o-fill's item Scope — Use Method Names Directly at Root Level (Important)

$host / $data are injected by ofa.js into the item scope when x-fill (o-fill) renders list items (createItem creates { $data, $host, $index }). The root-level scope (top of the page template, outside o-fill) has no $host / $data — on:click="$host.xxx()" throws Error evaluating element expression: 'on:click="$host.xxx()"'; clicks do nothing and the console logs an error.

✅ Correct Way:

<!-- Root level: write the method name directly (proto methods live on the page instance) -->
<button on:click="openStockHelp()">?</button>
<button on:click="goToPage(currentPage - 1)">Previous</button>

<!-- Inside o-fill: $data / $host / $index are available -->
<o-fill :value="rows" fill-key="id">
  <button on:click="$host.deleteRow($data.id)">{{$data.name}}</button>
</o-fill>

❌ Wrong Way (using $host at root level):

<button on:click="$host.openStockHelp()">?</button>  <!-- throws -->

Debugging mnemonic: an event expression like on:click reports Error evaluating element expression → first check whether the element is inside an o-fill. If it isn't, drop the $host. and write the method name directly (keep $host only for things like numeric page buttons inside an o-fill). For property bindings (:disabled="page <= 1") at root level, use the data field name directly — no $host needed.

Detailed example: don't write && in an o-fill text interpolation (block stops rendering, important)

Symptom: after adding a && expression to a text interpolation inside an o-fill (e.g. {{ $data.x && $data.x !== '裸果' ? ' · 内包装 ' + $data.x : '' }}), the entire o-fill block stops rendering (all list items disappear), while other parts of the page (titles / toolbars / pagination) still work. There is no page-level error — only a console SyntaxError: Unexpected token '&' thrown when compiling with new Function.

Minimal repro comparison (the {{}} text-interpolation channel):

• {{ $data.pack && $data.pack ? ... : '' }} (contains &&) → ❌ the whole o-fill does not render
• {{ $data.pack ? '· ' + $data.pack : '' }} (ternary + concat) → ✅
• {{ $data.pack === '裸果' ? '' : ... }} (===) → ✅
• {{ $data.pack !== '裸果' ? ... }} (!==) → ✅
• {{$host.xxx($data)}} (method call) → ✅

Root cause: the o-fill item template encodes the {{}} expression with encodeURIComponent into the expr attribute and decodes it back before compiling; && gets corrupted in this pipeline (a lone & survives), so new Function fails to parse it. The failure happens inside that o-fill's render loop, which aborts the whole block. !==, ===, ternaries and string concatenation are all unaffected.

Fix: avoid && in text interpolations and extract a $host method instead (regular JS inside methods is not subject to template compilation):

// in proto
innerPackingText(d) {
  const ip = d && d.inner_packing;
  if (!ip || ip === "裸果") return "";
  return " · 内包装 " + ip;
}

<!-- in template -->
<div>{{$host.innerPackingText($data)}}</div>

Debugging mnemonic: o-fill block not rendering + console shows SyntaxError: Unexpected token '&' → grep that o-fill for && inside {{ expressions and convert them all to method calls. (Whether && is safe in the property-binding channel is unverified — when in doubt, methodize rather than gamble.)

---

Core Syntax Points

Module Structure

• Page Module: <template page> contains <style>, template content, and <script>, script must be inside template
• Component Module: <template component> contains <style>, template content, and <script>, script must be inside template, returned object must include tag field

Page Embedding vs Micro-app

Tag	Purpose	src Points To
<o-page>	Embed a page module in an entry HTML or inside another page template	Directly to a page module file (.html)
<o-app>	Create a micro-app that manages multi-page navigation and transitions	An app config file (app-config.js)

Key differences:

• <o-page> is a "page-level component" that loads and renders a page module. It can be used in the entry HTML or inside another page's template to embed a sub-page.
• <o-app> is a "micro-app container" for creating independent application instances. It loads app-config.js to configure the home page and page transition animations. Do not use <o-app> to directly load page module files.

Embedding a sub-page example (embedding a page module inside another page's template):

<template page>
  <p-dialog>
    <o-page src="./user-traffic-page.html?userId=123"></o-page>
  </p-dialog>
  <script>
    export default async () => {
      return {
        data: { ... }
      };
    };
  </script>
</template>

The sub-page receives the userId parameter via export default async ({ query }).

⚠️ The src of <o-page> (including query) only takes effect at initialization; assigning it again after initialization throws an error. For runtime param passing, call a method exposed by the sub-page, and pass results back via event bubbling (bubbles + composed) — see the "Splitting a Complex Single Page into Multiple Page Modules" example above.

Page Module

<template page>
  <style>
    :host { display: block; }
  </style>
  <div>{{message}}</div>
  <script>
    export default async ({ query }) => {
      return {
        data: { message: "Hello" },
        proto: { handleClick() {} }
      };
    };
  </script>
</template>

Component Module

<template component>
  <style>
    :host { display: block; }
  </style>
  <div>{{value}}</div>
  <script>
    export default async () => {
      return {
        tag: "my-component",
        attrs: { value: "default" },
        data: { count: 0 },
        proto: { increment() {} }
      };
    };
  </script>
</template>

attrs vs data note: attrs is for simple scalar values (string). Its values reflect to HTML attributes, suitable for attr:xxx CSS selectors. data is for complex data (arrays, objects). When bound via :prop from outside, attrs values get serialized to strings causing type loss, so complex data like arrays and objects must be placed in data. Keys in attrs and data cannot overlap.

Template Syntax Quick Reference

Syntax	Purpose	Example
{{var}}	Text node rendering (only in element content, NOT in attribute values)	<span>{{name}}</span>
:html	HTML content rendering	<div :html="htmlContent"></div>
:prop="key"	One-way property binding	<input :value="name">
sync:prop="key"	Two-way property binding	<input sync:value="name">
attr:name="key"	HTML attribute binding (title/href/alt/data- etc. always use this*)	<a attr:href="url" attr:title="tip">
class:name="bool"	Conditional class binding	<div class:active="isActive">
:style.prop="value"	Style property binding	<p :style.color="textColor">
on:event="handler"	Event binding	<button on:click="handleClick">
on:event="expr"	Expression event	<button on:click="count++">
$event	Event object	on:click="handle($event)"
$("#id")	Get element instance	const el = $("#myComponent")

Core Features

• Computed Properties: Use get xxx() {} in proto instead of computed
• Reactive Data: Create using $.stanz()
• List Rendering: Use <o-fill> component; fill-key is optional, but always add fill-key="fieldName" when list items have a unique identifier field (e.g. id), so items are correctly reused and updated when the array is added to, removed from, or reordered
• Conditional Rendering: Use <o-if> / <o-else-if> / <o-else> components
• Non-explicit Components: <x-if> / <x-fill> have same functionality but don't render to DOM
• Property Passing: :toKey="fromKey" one-way, sync:toKey="fromKey" two-way
• Watchers: watch: { prop() {} }
• Lifecycle: ready() attached() detached()
• Custom Events: this.emit('event-name', { data: {...} })
• Slots: <slot></slot> receives external content

---

Development Decision Guide

Module Type

Need reusable components?
├─ Yes → Use component module (<template component> + tag field)
└─ No → Use page module (<template page>)

Is the single page too heavy (main list + dialog form + multiple sub-flows mixed in one module)?
├─ Yes → Split into multiple page modules: the host embeds sub-pages with a resident <o-page>
│   ├─ Pass params on first initialization: query in the src URL, e.g. src="./sub-page.html?userId=123"
│   ├─ Pass params at runtime: host calls a method exposed by the sub-page (src is immutable after initialization; never change src/query)
│   └─ Pass results back: sub-page emits a bubbling event (bubbles + composed), host listens with on:eventName
└─ No → Keep a single page module

Data Management

Need to share data?
├─ Yes → Across multiple layers of components?
│   ├─ Yes → Use o-provider/o-consumer
│   └─ No → Use sync: two-way binding or : one-way passing
└─ No → Use data to define local data

attrs vs data Selection

When defining component properties, should the value go in attrs or data?
├─ Simple scalar values (string) → Use attrs
│   └─ Reflects to HTML attribute, usable with attr:xxx in CSS selectors
├─ Complex data (arrays, objects) → Use data
│   └─ When bound via :prop from outside, attrs serializes to string causing type loss
└─ Example: <n-line-chart :points="someArray"> → points is an array, must be in data

Rendering Method

List rendering?
├─ Yes → Use o-fill component
│   ├─ Items have a unique field (e.g. id) → Add fill-key="id" (optional attribute, but always include it when writing code)
│   ├─ Direct rendering (simple structure) → Template content directly inside o-fill, no <template> wrapper needed
│   └─ Template rendering (complex structure/reuse) → <template> defined outside o-fill, use name attribute to bind
└─ No → Write template normally

Conditional rendering?
├─ Yes → Use o-if/o-else-if/o-else components
└─ No → Write template normally

o-fill Direct Rendering (recommended for simple structures):

<o-fill :value="messages" fill-key="id">
  <div class="message" attr:type="$data.type">
    [{{$data.time}}] {{$data.text}}
  </div>
</o-fill>

• Use $data, $index, $host to access data
• Add fill-key when items have a unique field (e.g. id) — optional, but recommended to always include

o-fill Template Rendering (for complex structures or reuse):

<o-fill :value="products" name="product-template" fill-key="id"></o-fill>
<template name="product-template">
  <div class="product-card">{{$data.name}} - ¥{{$data.price}}</div>
</template>

Dynamic Style

Need to set styles based on data?
├─ Data inherent properties (like type, status, level) → Use attr: + attribute selector
└─ Style state switching (like active, disabled) → Use class: + class selector

Routing

Need multi-page application?
├─ Yes → Use o-router + o-app
│   └─ Need nested layout?
│       ├─ Yes → Parent page uses <slot>, child page exports parent
│       └─ No → Independent page
└─ No → Single page application

---

Documentation Index

Core Reference (Priority)

Document	Description
Template Syntax Examples and Syntax Explanation	Complete examples and detailed explanations of all template syntax (Highest priority)
Quick Reference Table	API and syntax quick reference
API Reference Manual	Complete API documentation
Common Patterns and Best Practices	Common code patterns (including single-page business splitting / embedded sub-page pattern)

Getting Started Guide

Document	Description
Introduction	Framework core concepts and advantages
Script Reference	Import methods
Quick Start	Quick start guide
Create First App	Create project using OFA Studio
Production and Deployment	Development environment, production deployment, minification

Template and Rendering

Quick Syntax	Document
{{variable}} :html	Content Rendering
on:click="handler"	Event Binding
:prop="value" sync:prop="value"	Property Binding
class:active="isActive" :style.width="val"	Class/Style Binding
<o-if :value="condition">	Conditional Rendering
<o-fill :value="list" fill-key="id">	List Rendering
get computedProp() {}	Computed Properties
watch: { prop() {} }	Watchers
ready() attached() detached()	Lifecycle

Component Development

Quick Syntax	Document
<template component> tag attrs	Create Component
export default async ({ load, url, query })	Module Return Object Properties
<slot></slot>	Slots
this.emit('event')	Custom Events
attrs: { msg: 'default' }	Inherit Attributes
:toProp="fromProp"	Deep Property Binding
{{obj.nested.prop}}	Property Response
<inject-host>	Inject Host Style
<x-if> <x-fill>	Non-explicit Component
<template is="replace-temp">	Replace Template
<match-var>	Match Var

State and Routing

Quick Syntax	Document
o-provider o-consumer	Context State
$.stanz()	State Management
o-app o-router	Routes
Parent page <slot> child page parent	Nested Routes
app-config.js	App Configuration
o-app micro app	Micro App
SCSR isomorphic rendering	SSR and Isomorphic Rendering

Examples

Example	Feature Points	Entry	Key Files
Counter	Data binding, events, computed properties, styles	demo.html	page.html
Switch Component	Component definition, property passing, events, slots	demo.html	switch.html, page.html
Todo List	Data persistence, list rendering, state management	demo.html	page.html, data.js
File Editor	Nested component communication, o-provider, dependency injection	demo.html	page.html, filelist.html, editor.html
SPA Routing	o-router, o-app, page animation	demo.html	app-config.js, layout.html
SCSR Rendering	Server-side rendering, SEO, isomorphic application	home.html	app-config.js