Declare-free reactive-prop DX via a typed base-class factory

[vivek7405]

Problem

Reactive props need three pieces today: static properties = { count: { type: Number } }, a declare count: number, and a default. The declare is pure boilerplate that exists only because TypeScript cannot type a class's instance members from a value in that class's own static field. The feasibility research in #531 proved a declare-free DX IS achievable while holding every webjs invariant (no build, source-is-runtime, erasable-TS, no decorators).

Design / approach

Ship a typed base-class factory. The user writes the prop shape once, inside a Component({ ... }) call the class extends, and the types flow into this:

class Counter extends Component({
  count:   prop(Number, { reflect: true, default: 0 }),
  student: prop(Student),
  tags:    prop<Tag[]>(Array, { default: () => [] }),   // explicit type for richer shapes
  mode:    prop<'light' | 'dark'>(String, { default: 'light' }),
}) {
  render() { return html`${this.count} ${this.student.name} ${this.mode}`; }  // all typed, NO declare
}
Counter.register('counter-x');

• prop(Number) infers number, prop(Student) infers Student; a richer type than the constructor implies is given once as prop<T>(Ctor).
• Component(shape) returns class extends WebComponent { static properties = shape }; a mapped type { [K in keyof S]: TypeOf<S[K]> } intersected with the base gives this its typed members.
• All three were verified in Research a simpler reactive-prop DX than the static-properties + declare pattern #531: tsc strict + erasableSyntaxOnly PASS, module.stripTypeScriptTypes leaves valid runtime (type args erase in place, the factory call ships), and an end-to-end run against the real WebComponent works with no change to _initializeProperties.

Design decision to settle first (do not skip): REPLACE the static properties + declare model with the factory, or ship the factory ALONGSIDE it. Replacing is a single clean model and is viable because webjs has no users yet (no backward-compat burden), but it is a full migration of tooling/docs/apps. Coexisting is safer but doubles the prop-declaration API surface. Confirm the direction with the owner before building.

Implementation notes (for the implementing agent)

• Read Research a simpler reactive-prop DX than the static-properties + declare pattern #531 (body + the deep-dive comment) first; it carries the exact type/runtime prototypes that type-check and run.
• New exports in packages/core/index.js (and the browser bundle): prop() and Component(). Runtime is thin: Component(shape) returns an anonymous WebComponent subclass with static properties = normalize(shape); prop(type?, opts?) returns a PropertyDeclaration (handle the prop(opts) no-constructor overload at runtime by sniffing whether arg1 is callable).
• Types: add the Infer<C> constructor-to-type map, the prop overloads, and the Component factory signature to packages/core/src/component.d.ts (next to PropertyDeclaration and the WebComponent class type). The default option already exists there (PR feat: declarative default option for reactive props #575).
• The runtime accessor in packages/core/src/component.js _initializeProperties (~L548-589) needs NO change; it already reads Ctor.properties. The default handling landed in PR feat: declarative default option for reactive props #575.
• webjs check: the reactive-props-use-declare rule (packages/server/src/check.js ~L77 and ~L443-462) only scans static properties. In the factory model there is no static-field initializer to clobber, so decide whether the rule still applies (it should still fire for the OLD model if coexisting). Add a rule/lint for misuse of the factory if warranted.
• Broad surfaces that assume the static-field model and must be synced: @webjsdev/intellisense (packages/editors/intellisense/src, re-vendor for nvim after edits), MCP list_components (packages/mcp/src), scaffold templates (packages/cli/templates/), docs site (docs/app/docs/components/page.ts), AGENTS.md, agent-docs/components.md, agent-docs/lit-muscle-memory-gotchas.md, and the four dogfood apps if migrated.

Landmines

• Decorators and the TC39 accessor keyword are both out (verified in Research a simpler reactive-prop DX than the static-properties + declare pattern #531: accessor is a runtime syntax error on V8 and is not erasable). Do not reach for them.
• A prop() used as a class FIELD is clobbered by class-field semantics; it MUST be a factory argument, not an instance field.
• Keep prop(Object) honest: a plain Object infers a loose type, so rich object shapes need the explicit prop<Shape>(Object) phantom.

Invariants to respect

• AGENTS.md invariant 1 (server-only boundary), 10 (erasable TS, no decorators), and the no-build / source-is-runtime promise. The factory call must ship and run as written.

Acceptance criteria

• Design decision (replace vs coexist) recorded on this issue before implementation.
• Component() + prop() exported and working: a component declares props with NO declare line and this.<prop> is fully typed.
• tsc strict + erasableSyntaxOnly passes on a real example; a wrong-type assignment is a type error (counterfactual via @ts-expect-error).
• Source strips to valid runtime (assert against module.stripTypeScriptTypes).
• Reactivity, reflect, default (literal + function), and state all work at runtime and SSR (unit + SSR + browser layers).
• All tooling/docs surfaces above synced (or "N/A because" in the PR).

[vivek7405]

Finalized DX (decision: adopt the factory)

The owner adopted the bare-constructor factory. Build THIS shape (no prop() needed for the common case, no declare, values from the constructor):

class Counter extends Component({ count: Number, name: String, student: Student }) {
  constructor() {
    super();
    this.count = 0;
    this.name = 'xyz';
    this.student = new Student('ada');
  }
  render() { return html`${this.count} ${this.student.name}`; }
}
Counter.register('counter');

Number (value) vs number (type), the core mechanic

The shape object SHIPS to the browser and runs (source-is-runtime), so each entry is a runtime value, i.e. the capitalized constructor Number / String / Boolean / a class like Student. The lowercase number is a TYPE and cannot appear in value position. The factory's Infer<C> mapped type converts the constructor back to its type (NumberConstructor -> number, StringConstructor -> string, BooleanConstructor -> boolean, new () => T -> T), so the author writes Number and this.count is typed number. The constructor is ALSO what the runtime uses for attribute coercion, so it has to be the real value regardless.

prop(...) stays as the OPTIONS form: prop(Number, { reflect: true, default: 0 }), prop<Tag[]>(Array) for a richer type than the constructor implies. So a prop is either a bare constructor or a prop(...) call, both accepted by Component(shape).

[vivek7405]

Finalized API: dual-role WebComponent (no separate Component name)

Supersedes the Component({...}) naming above. The factory and the base class are the SAME identifier, WebComponent. Verified on both runtime and types.

// with props: types flow into `this`, values from the constructor, NO declare
class Counter extends WebComponent({ count: Number, name: String, student: Student }) {
  constructor() { super(); this.count = 0; this.name = 'xyz'; this.student = new Student('ada'); }
  render() { return html`${this.count} ${this.student.name}`; }
}
Counter.register('counter');

// plain form unchanged
class Plain extends WebComponent {
  render() { return html`<p>plain</p>`; }
}

Runtime mechanism (verified against the real base, linkedom)

WebComponent is a function that is BOTH callable and constructable:

function WebComponent(shape) {
  if (!new.target) return class extends Base { static properties = normalize(shape); }; // WebComponent({...})
  return Reflect.construct(Base, [], new.target);                                        // extends WebComponent
}
WebComponent.prototype = Base.prototype;          // methods + instanceof resolve to Base
Object.setPrototypeOf(WebComponent, Base);        // inherit statics (register, observedAttributes, ...)

Base is the current WebComponent class (extends HTMLElement). extends WebComponent({...}) extends a normal subclass (SSR new Cls() is ordinary construction). extends WebComponent routes super() through Reflect.construct(Base, [], new.target). Verified: reactivity, attribute reflect, defaults, instanceof Base, and the plain no-props form all work.

Type mechanism

One WebComponent const typed with both a construct signature and a call signature:

interface WebComponentCtor {
  new (): WebComponentInstance;                                                            // extends WebComponent
  <S extends Record<string, Ctor>>(shape: S): new () => WebComponentInstance & PropsOf<S>; // extends WebComponent({...})
  register(tag: string): void;
}

PropsOf<S> maps each constructor to its type via Infer<C> (Number -> number, Student -> Student). Passes strict + erasableSyntaxOnly; a wrong-type assign is a real error; the source strips to valid runtime.

Implementation caveats to verify

• The SSR path (render-server.js does new Cls()): the factory subclass constructs normally; the plain extends WebComponent form must construct correctly via the new.target bridge at SSR too (test it).
• Custom-element upgrade and register() must work through the reassigned prototype / statics.
• Keep the prop(...) options form (prop(Number, { reflect, default }), prop<Tag[]>(Array)) accepted inside the shape alongside bare constructors.

[vivek7405]

Authoring rule: primitives capitalized, classes as-is

The shape passed to WebComponent({...}) is a runtime VALUE that ships (source-is-runtime) and feeds attribute coercion, so each entry must be a runtime value:

• Classes: written exactly as the TS type, since a class is also a value. { student: Student }, { at: Date }.
• Primitives: the capitalized CONSTRUCTOR, not the lowercase type keyword. { count: Number, name: String, on: Boolean }. Lowercase number is a compile error in value position (TS2693) and is undefined at runtime, so it cannot ship and carries no coercion. This matches Lit's { type: Number } convention.
• Richer than the constructor implies (unions, Tag[]): the prop<T>(Ctor, opts?) options form, e.g. prop<'light'|'dark'>(String), prop<Tag[]>(Array).

The Infer<C> map turns the constructor back into the type for this (Number -> number, Student -> Student), so the author writes the value and gets the type, no declare. A type-only generic (WebComponent<{count:number}>()) would allow lowercase but leaves the runtime with no prop names / no coercion, so it is not viable without a build step. The delta from idiomatic TS is only capitalizing the three primitive keywords.

[vivek7405]

Current Implementation Progress and Continuation Guide

To support a seamless transition, here is the complete state of the implementation and explicit instructions for any developer or AI agent picking up this task on the branch feat/declare-free-prop-factory (tracked on Draft PR #597).

---

1. What Has Been Done (100% Complete and Green)

• Prerequisite Merged: Merged the declarative default option branch (feat/simpler-reactive-prop-dx) into this branch to enable default-value seeding outside constructors.
• Isomorphic Runtime (packages/core/src/component.js): Converted the WebComponent class to a dual-role function/class constructor (WebComponentBase wrapped in WebComponent). It handles new construction and factory calls independently:

  export function WebComponent(properties) {
    if (new.target) {
      return Reflect.construct(WebComponentBase, arguments, new.target);
    } else {
      return class extends WebComponentBase {
        static properties = properties;
      };
    }
  }
  Object.setPrototypeOf(WebComponent, WebComponentBase);
  WebComponent.prototype = WebComponentBase.prototype;

• Custom Options (prop helper): Implemented the standard prop(type, opts) helper. It intelligently intercepts no-constructor object-only arguments.
• Type Definitions (packages/core/src/component.d.ts): Defined the static constructor signatures, Infer<C> constructor-to-type map, and InferProps<S> mapped types. Extending Omit<typeof WebComponentBase, "new"> ensures static methods like .register() are correctly inherited:

  export interface WebComponentConstructor extends Omit<typeof WebComponentBase, 'new'> {
    new (): WebComponentBase;
    prototype: WebComponentBase;
    <S extends Record<string, any>>(shape: S): Omit<typeof WebComponentBase, 'new'> & {
      new (): WebComponentBase & InferProps<S>;
      prototype: WebComponentBase & InferProps<S>;
    };
  }

• Type Parity & Compilation: Updated barrel exports (index.js, index-browser.js, index.d.ts) to re-export prop and resolve siblings without TS2846 errors.
• Unit & Type Testing (100% Passed):
  • Added robust runtime assertions inside packages/core/test/lifecycle/component-lifecycle.test.js.
  • Added compile-time static checks inside test/types/component-types.test-d.ts (using @ts-expect-error to verify strict assignment constraints).
  • All 37 runtime tests and compile-time type-checks pass successfully.

---

2. What Remains to Be Done (Next Steps)

Any agent continuing this work should focus on syncing the wider tooling, templates, and documentation surfaces that assume properties only live inside static properties = { ... }:

1. webjs check rule validation: Double-check if the reactive-props-use-declare rule inside packages/server/src/check.js needs any adjustment. At present, it skips factory-created classes because extractStaticPropertyNames returns an empty set when no static properties field exists in the class body. This is safe, but verify if we need to add a lint check preventing the misuse of class fields for factory-created properties.
2. @webjsdev/intellisense (packages/editors/intellisense/src): Update the language service plugin so it parses and autocompletes properties declared in WebComponent({ ... }) factory calls.
   • Crucial: After making edits to the intellidense src, run node packages/editors/nvim/scripts/vendor-intellisense.mjs and stage the vendored files in Neovim to prevent CI failures.
3. MCP list_components (packages/mcp/src): Sync the MCP components list generator so it recognizes components defined via the base class factory.
4. Scaffold Templates (packages/cli/templates/): Update the example component files generated by webjs create to utilize the clean, declare-free factory pattern.
5. Documentation Surfaces: Sync the following files to teach, document, and recommend the declare-free DX:
   • docs/app/docs/components/page.ts (the docs site components page)
   • AGENTS.md (the framework's developer agreement)
   • agent-docs/components.md (the deep-dive components guide)
   • agent-docs/lit-muscle-memory-gotchas.md (the Lit-to-webjs gotchas guide)
6. Dogfood Apps Verification: Boot and test the four dogfood apps (examples/blog, website, docs, and packages/ui/packages/website) in prod/dist mode to guarantee zero regressions.