android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/rules/arkts/language/arkui-structure-rules.md

@@ -0,0 +1,173 @@
+# ArkUI Structure Rules
+
+Structural constraints on `struct` / `@Component` / `build()` that the ArkUI compiler enforces. These have **no `arkts-*` rule tag** — type-level checks do not catch them and they only surface at build time, so getting them right up front saves a full build round-trip.
+
+Each section is keyed to the exact compiler error message it prevents.
+
+## 1. `build()` has exactly one root node
+
+> Error: `In an '@Entry' decorated component, the 'build' method can have only one root node, which must be a container component.`
+> Error: `In an '@Component' decorated component, the 'build' method can have only one root node.`
+
+```ets
+// ❌ two sibling roots
+build() {
+  Text('Title')
+  Column() { ... }
+}
+
+// ✅ one root container wrapping everything
+build() {
+  Column() {
+    Text('Title')
+    ...
+  }
+}
+```
+
+Rules:
+
+- `build()` contains exactly ONE top-level component.
+- For `@Entry` pages the root must be a **container** (`Column`, `Row`, `Stack`, `Flex`, `RelativeContainer`, ...), not a leaf like `Text`.
+- `if/else` at the root counts as multiple possible roots for `@Entry` — wrap it in a container.
+- The same single-root rule applies to each branch of conditional rendering inside `@Builder` functions used as page content.
+
+## 2. Only UI component syntax inside `build()` / `@Builder`
+
+> Error: `Only UI component syntax can be written here.` (code `10905209`)
+> Error: `Assignment does not meet UI component syntax.` (code `10905204`)
+> Error: `UI component 'Column' cannot be used in this place.`
+
+Inside `build()` and `@Builder` bodies, the ONLY allowed constructs are:
+
+- Component calls with their trailing blocks and chained modifiers
+- `if / else if / else`
+- `ForEach` / `LazyForEach` / `Repeat`
+
+Everything else is illegal there: `let`/`const` declarations, assignments, `console.log`, `for`/`while` loops, `try/catch`, early `return`, function calls as statements.
+
+```ets
+// ❌ statements inside build
+build() {
+  Column() {
+    let label = this.count + ''     // illegal
+    console.log('render')           // illegal
+    Text(label)
+  }
+}
+
+// ✅ compute in methods/getters, render in build
+get label(): string {
+  return `${this.count}`
+}
+
+build() {
+  Column() {
+    Text(this.label)
+  }
+}
+```
+
+Rules:
+
+- Precompute values in class methods, getters, or state; `build()` only renders.
+- Conversely, UI component calls (`Column() {...}`, `Text(...)` as UI) may ONLY appear inside `build()` / `@Builder` bodies — never in ordinary methods, event handlers, or at top level. To return UI from a function, decorate it with `@Builder`.
+- Loops other than `ForEach` cannot emit UI. Convert `for` loops to a data array + `ForEach`.
+
+## 3. Struct member area: declarations and methods only
+
+> Error: `'HomeTab({ ... })' does not meet UI component syntax.`
+> Error: `Declaration or statement expected.` / cascading `';' expected.`
+
+The struct body outside `build()` holds ONLY: decorated/plain field declarations, methods, `@Builder`/`@Styles` methods, and lifecycle callbacks (`aboutToAppear` etc.).
+
+A single malformed edit in the member area (an unclosed brace, a statement, a misplaced component call) cascades: every following `@State` line then reports `does not meet UI component syntax` or parser errors. **When these errors appear in a block, fix the FIRST one — the rest are usually fallout.**
+
+```ets
+// ❌ component call in the member area
+@Component
+struct Index {
+  @State medications: MedicationInfo[] = []
+  HomeTab({ medications: $medications })   // illegal here — must be inside build()
+
+  build() { ... }
+}
+
+// ✅
+@Component
+struct Index {
+  @State medications: MedicationInfo[] = []
+
+  build() {
+    Column() {
+      HomeTab({ medications: $medications })
+    }
+  }
+}
+```
+
+## 4. Custom component instantiation and `@Link` passing
+
+> Error: `'CompName({ ... })' does not meet UI component syntax.`
+> Error: `The '@Link' property 'x' cannot be initialized here (forbidden to specify default value for @Link).`
+
+```ets
+// Child (V1)
+@Component
+struct HomeTab {
+  @Link medications: MedicationInfo[]      // no initializer on @Link
+  @Prop title: string = ''                  // @Prop may have a local default
+
+  build() { ... }
+}
+
+// Parent build()
+HomeTab({ medications: $medications, title: this.title })
+```
+
+Rules:
+
+- Instantiate custom components only inside `build()`/`@Builder`, as `CompName({ ... })` with named arguments.
+- V1 `@Link` fields: parent passes `$varName` (two-way binding); the child must NOT give `@Link` an initializer.
+- `@Prop` receives plain values (`this.x`); `@BuilderParam` receives a `@Builder` function reference.
+- Do not pass fields the child does not declare; argument names must match child member names exactly.
+
+## 5. One decorator family per component (V1 xor V2)
+
+> Error: `The '@State' decorator can only be used in a 'struct' decorated with '@Component'.` (and mirror-image V2 errors)
+
+- Never mix families inside one struct: `@ComponentV2` + `@State` is a build error; so is `@Component` + `@Local`.
+- This section pins only the **build error**; which family to use and the full V1↔V2 decorator correspondences are `../ui/state-management.md`'s.
+- State decorators go on struct member declarations only — never on top-level variables, local variables, or plain class fields (use `@Observed`/`@Trace` for classes).
+
+## 6. `@Builder` / `@Styles` / `@Extend` placement
+
+- `@Builder` methods: inside a struct (access `this`) or global. Called from `build()` either directly (`this.myBuilder()`) or passed to `@BuilderParam` / `.tabBar(...)` etc.
+- Component syntax does NOT parse inside ordinary closures. Factoring a repeated form section as a regular method taking a content callback fails at parse time:
+
+  ```ets
+  // ❌ content is a plain () => void — Row(){...} inside it is a syntax-error cascade
+  //    (';' expected / Declaration or statement expected / Cannot find name 'width')
+  buildSection(title: string, content: () => void) { ... }
+  this.buildSection('Reminder time', () => { Row() { TextInput() } })
+
+  // ✅ each section is a @Builder method; shared chrome via another @Builder or a child
+  //    component with @BuilderParam
+  @Builder timeSection() { Row() { TextInput() } }
+  // child component receiving layout:
+  @Component struct FormSection {
+    title: string = '';
+    @BuilderParam content: () => void;   // receives a @Builder reference
+    build() { Column() { Text(this.title); this.content() } }
+  }
+  // parent build(): FormSection({ title: 'Reminder time', content: this.timeSection })
+  ```
+- `@Styles` can only contain universal attribute settings; component-specific modifiers (e.g. `.fontSize`) belong in `@Extend(Text)`.
+- `@Extend` is global-only (outside the struct).
+- Pass builder functions by reference (`this.myBuilder`) where a builder param is expected — do not invoke with `()` when passing.
+
+## 7. Page-level requirements
+
+- Exactly one `@Entry` struct per page `.ets` file; the file must be registered in `main_pages.json` (or routed via Navigation) to be reachable.
+- `@Entry` struct name and file naming should follow the project's existing pages.
+- Lifecycle methods (`aboutToAppear`, `onPageShow`, ...) are ordinary methods in the member area — they may contain arbitrary statements (rules in § 2 apply only to `build()`/`@Builder`).

package/skills/a2h-spec-implement/rules/arkts/language/ts-to-arkts-rewrites.md

@@ -0,0 +1,58 @@
+# TypeScript → ArkTS Rewrite Table
+
+Use this when porting plain TypeScript into ArkTS or diagnosing "runs in TS, errors in ArkTS" issues. For rule-tag details, see `arkts-rules.md`.
+
+## First, remember: many TS constructs need NO change in ArkTS
+
+Template literals, `value as T`, `Record<K,V>` with indexed access, arrow functions, async/await — all legal. Do **not** rewrite them. Full whitelist: [`arkts-rules.md` § Explicitly allowed constructs](arkts-rules.md#explicitly-allowed-constructs).
+
+## Quick rewrite table
+
+The Rule tag column matches linter error messages one-to-one — search the tag in `arkts-rules.md` for details and examples.
+
+| TypeScript construct | ArkTS rewrite | Rule tag |
+|---------------------|---------------|----------|
+| `var x = 1` | `let x = 1` / `const x = 1` | `arkts-no-var` |
+| `let x: any` / `unknown` | Explicit type; when undetermined use `Object` or a union type | `arkts-no-any-unknown` |
+| `const { a, b } = obj` | `const a = obj.a; const b = obj.b` | `arkts-no-destruct-decls` |
+| `function f({ a }: P)` | `function f(p: P)` then use `p.a` | `arkts-no-destruct-params` |
+| `[x, y] = [y, x]` | Introduce a temp variable, assign one by one | `arkts-no-destruct-assignment` |
+| `const fn = function() {}` | `const fn = () => {}` | `arkts-no-func-expressions` |
+| `const id = <T>(v: T): T => v` | `function id<T>(v: T): T { return v }` | `arkts-no-generic-lambdas` |
+| `function inner() {}` inside a function body | `const inner = (): void => {}` or promote to a class method | `arkts-no-nested-funcs` |
+| `<string>value` | `value as string` | `arkts-as-casts` |
+| `obj as const` | Declare the constant type explicitly | `arkts-no-as-const` |
+| `type T = { x: number }` | `interface T { x: number }` | `arkts-no-obj-literals-as-types` |
+| `f(p: { x: number })` | Define a named interface as the parameter type | `arkts-no-obj-literals-as-types` |
+| `interface I { [key: string]: T }` | `Record<string, T>` | `arkts-no-indexed-signatures` |
+| `type C = A & B` | `interface C extends A, B {}` | `arkts-no-intersection-types` |
+| `type N = T['prop']` | Use the target type directly | `arkts-no-aliases-by-index` |
+| `obj['key']` (non-Record) | `obj.key`; for dynamic keys declare the type as `Record` | `arkts-no-props-by-index` |
+| `const o = { a: 1 }` (untyped) | `const o: MyIface = { a: 1 }` or `Record` | `arkts-no-untyped-obj-literals` |
+| `Pick` / `Omit` / `ReturnType` etc. | Hand-write a named interface | `arkts-no-utility-types` |
+| `delete obj.x` | Add `\| undefined` to the field type, set `obj.x = undefined` | `arkts-no-delete` |
+| `'key' in obj` | `obj.key !== undefined` or `instanceof` | `arkts-no-in` |
+| `for (const k in obj)` | `for...of` / `Map` / a known key list | `arkts-no-for-in` |
+| `v is Cat` (type guard) | `instanceof` check + `as` narrowing | `arkts-no-is` |
+| `{ ...obj1, ...obj2 }` | Construct a new object, assign fields explicitly | `arkts-no-spread` |
+| `throw 'msg'` | `throw new Error('msg')` | `arkts-limited-throw` |
+| `catch (e: Error)` | `catch (e)` then `const err = e as Error` | `arkts-no-types-in-catch` |
+| `class C { constructor(public x: number) {} }` | Declare fields in the class body, assign in the constructor | `arkts-no-ctor-prop-decls` |
+| `#privateField` | `private privateField` | `arkts-no-private-identifiers` |
+| `class D implements Base` (Base is a class) | `extends Base`, or extract an interface | `arkts-implements-only-iface` |
+| `function* gen() { yield }` | Return an array/iterator class, or refactor to a plain function | `arkts-no-generators` |
+| `fn.bind(this)` | Arrow function capturing this | `arkts-no-func-bind` |
+| `/pattern/g` | `new RegExp("pattern", "g")` | `arkts-no-regexp-literals` |
+| `Object.assign(t, s)` | Assign fields explicitly or use a constructor | `arkts-limited-stdlib` |
+| `obj.hasOwnProperty('k')` | `obj.k !== undefined` | `arkts-limited-stdlib` |
+| `globalThis.x` | An explicitly exported singleton / AppStorage | `arkts-no-globalthis` |
+| `// @ts-ignore` | Fix the underlying type error; suppression is banned | `arkts-strict-typing-required` |
+| `import type { T }` | `import { T }` | `arkts-no-special-imports` |
+| `import './polyfill'` | Remove; import the needed symbols explicitly | `arkts-no-side-effects-imports` |
+| `import x = require('m')` | `import x from 'm'` | `arkts-no-require` |
+| `export = X` | `export default X` | `arkts-no-export-assignment` |
+| `const api = SomeNamespace` (namespace as value) | Call `SomeNamespace.member()` directly, or define an explicit object | `arkts-no-ns-as-obj` |
+
+## Worked good/bad examples
+
+Composite rewrites (dynamic object → Record/named type, structural → nominal typing, nested function + `this` → class method, etc.) live once in [`arkts-rules.md` § Rule Details by Category](arkts-rules.md#rule-details-by-category) — search the rule tag from the table above.