@webjsdev/core 0.7.21 → 0.7.23

package/index-browser.js

@@ -24,7 +24,7 @@
 
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
-export { WebComponent } from './src/component.js';
+export { WebComponent, prop } from './src/component.js';
 export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
@@ -38,6 +38,15 @@ export {
   stringify, parse,
   serialize, deserialize,
 } from './src/serialize.js';
+// The client router auto-enables on bundle load: `router-client.js` calls
+// `enableClientRouter()` at module end (idempotent). This is INTENTIONAL, so
+// any page that loads `@webjsdev/core` (i.e. ships any component) gets client
+// navigation with no per-app opt-in. A layout no longer needs to
+// `import '@webjsdev/core/client-router'`. The bare side-effect import below
+// pins that contract even if the named re-export is later refactored away;
+// the re-export still also evaluates the module, so the two are belt-and-
+// suspenders, not a double-enable (ESM evaluates once, enable is idempotent).
+import './src/router-client.js';
 export { enableClientRouter, disableClientRouter, navigate, revalidate } from './src/router-client.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';

package/index.js

@@ -8,7 +8,7 @@
 
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
-export { WebComponent } from './src/component.js';
+export { WebComponent, prop } from './src/component.js';
 export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.21",
+  "version": "0.7.23",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.d.ts

@@ -22,7 +22,7 @@ export type PropertyConstructor<T = unknown> =
   | (new (...args: any[]) => T)
   | ((v: any) => T);
 
-/** Runtime-level property declaration: matches `static properties = { … }`. */
+/** Runtime-level property declaration: one entry in `WebComponent({ … })`. */
 export interface PropertyDeclaration<T = unknown> {
   /** Constructor used for string → value coercion when the attribute changes. */
   type?: PropertyConstructor<T>;
@@ -52,27 +52,30 @@ export interface ReactiveController {
 /**
  * Base class for interactive web components.
  *
- * Declare runtime behaviour via `static properties = { … }` and type
- * each field with a sibling `declare foo: Foo`:
+ * Declare reactive properties via the `extends WebComponent({ … })`
+ * factory. It installs the reactive accessor AND types each field for
+ * you (no `declare`, no `static properties`):
  *
- *     class StudentCard extends WebComponent {
- *       static properties = { student: { type: Object } };
- *       declare student: Student;
+ *     class StudentCard extends WebComponent({ student: prop<Student>(Object) }) {
  *       render() { return html`<p>${this.student.name}</p>`; }
  *     }
  *     StudentCard.register('student-card');
  *
- * The `declare` field has no runtime cost: it tells TypeScript the
- * field's type without emitting a class-field initializer that would
- * clobber the reactive accessor the framework installs via
- * `Object.defineProperty` in the constructor.
+ * A bare constructor type covers the common case (`WebComponent({ count:
+ * Number })` gives `this.count: number`); use the `prop()` helper for
+ * options (`prop(Number, { reflect: true })`) or to narrow the type
+ * (`prop<Student>(Object)`). Set defaults via the `default` option or in
+ * the constructor, never a class-field initializer (it runs after super()
+ * and clobbers the reactive accessor). A hand-written `static properties`
+ * in a class body is no longer supported and throws at construction.
  *
  * See the Editor Setup doc for tooling that gives attribute/tag
  * intelligence inside `html\`…\`` templates.
  */
-export abstract class WebComponent extends HTMLElement {
+abstract class WebComponentBase extends HTMLElement {
   static shadow: boolean;
   static hydrate: 'visible' | undefined;
+  /** @internal Populated by the `WebComponent({ … })` factory, not by hand. */
   static properties: Record<string, PropertyDeclaration>;
   static styles: CSSResult | CSSResult[] | null;
   static lazy?: boolean;
@@ -84,8 +87,8 @@ export abstract class WebComponent extends HTMLElement {
    * Schedule a re-render. Optionally record a property change so lifecycle
    * hooks can branch on what changed via `changedProperties`.
    *
-   * For instance-local state, prefer a reactive property (`static
-   * properties = { foo: { state: true } }`) or a signal from
+   * For instance-local state, prefer a reactive property (`WebComponent({
+   * foo: prop({ state: true }) })`) or a signal from
    * `@webjsdev/core`'s `signal()`. The framework's built-in
    * SignalWatcher wires every signal read in `render()` to a re-render
    * automatically; explicit `requestUpdate()` is rarely needed.
@@ -129,3 +132,59 @@ export abstract class WebComponent extends HTMLElement {
   disconnectedCallback(): void;
   attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
+
+export type WebComponent = WebComponentBase;
+
+export type Infer<C> =
+  C extends BooleanConstructor ? boolean :
+  C extends NumberConstructor ? number :
+  C extends StringConstructor ? string :
+  C extends new (...a: any[]) => infer T ? T :
+  C extends (v: any) => infer T ? T : unknown;
+
+export type InferProps<S> = {
+  [K in keyof S]: S[K] extends PropertyDeclaration<infer T> ? T : Infer<S[K]>
+};
+
+/**
+ * The static surface every `WebComponent` constructor carries (the bare base,
+ * a factory-produced base, and a registered subclass alike). Declared ONCE
+ * here and referenced from both `WebComponentConstructor` and the factory-call
+ * return type below, so adding or changing a static can never let the two
+ * positions drift. Mirrors the `static` members on `WebComponentBase`.
+ */
+interface WebComponentStatics {
+  shadow: boolean;
+  hydrate: 'visible' | undefined;
+  properties: Record<string, PropertyDeclaration>;
+  styles: CSSResult | CSSResult[] | null;
+  lazy?: boolean;
+  register(tag: string): void;
+  readonly observedAttributes: string[];
+}
+
+export interface WebComponentConstructor extends WebComponentStatics {
+  new (): WebComponentBase;
+  prototype: WebComponentBase;
+
+  <S extends Record<string, any>>(shape: S): WebComponentStatics & {
+    new (): WebComponentBase & InferProps<S>;
+    prototype: WebComponentBase & InferProps<S>;
+  };
+}
+
+export declare const WebComponent: WebComponentConstructor;
+
+export declare function prop<C extends PropertyConstructor<any>>(
+  type: C,
+  opts?: Omit<PropertyDeclaration<Infer<C>>, 'type'>
+): PropertyDeclaration<Infer<C>>;
+
+export declare function prop<T>(
+  type: PropertyConstructor<any>,
+  opts?: Omit<PropertyDeclaration<T>, 'type'>
+): PropertyDeclaration<T>;
+
+export declare function prop<T = string>(
+  opts?: PropertyDeclaration<T>
+): PropertyDeclaration<T>;

package/src/component.js

@@ -400,7 +400,18 @@ for (const idl of ARIA_IDL_PROPS) {
 // Base class choice: real HTMLElement on the browser, the shim on the server.
 const Base = isBrowser ? HTMLElement : /** @type {any} */ (ServerElement);
 
-export class WebComponent extends Base {
+/**
+ * Marker stamped on the anonymous subclass the `WebComponent({...})` factory
+ * produces. It lets `_assertFactoryProperties` tell the framework's own
+ * factory-generated `static properties` (allowed) apart from a `static
+ * properties` a user wrote by hand in a class body (no longer allowed).
+ */
+const FACTORY_PROPS = Symbol('webjs.factoryProps');
+
+// Per-class memo so the constructor-time enforcement walk runs once per class.
+const _propsChecked = new WeakSet();
+
+class WebComponentBase extends Base {
   /** Whether to use shadow DOM. Default: false (light DOM). @type {boolean} */
   static shadow = false;
 
@@ -531,10 +542,45 @@ export class WebComponent extends Base {
      */
     this._isUpdating = false;
 
+    // Enforce the declare-free factory DX: a hand-written `static properties`
+    // in a class body is a hard error (use `extends WebComponent({ … })`).
+    this._assertFactoryProperties();
+
     // Install reactive property accessors for `static properties` declarations.
     this._initializeProperties();
   }
 
+  /**
+   * Throw if a class in this instance's constructor chain declares its own
+   * `static properties`. Reactive properties must be declared via the
+   * `extends WebComponent({ … })` factory, which stamps {@link FACTORY_PROPS}
+   * on the subclass it generates; a `static properties` written by hand in a
+   * class body carries no such marker and is rejected here (issue #598).
+   *
+   * The walk stops at {@link WebComponentBase} (whose `static properties = {}`
+   * default is internal) and is memoized per class so it runs once.
+   * @private
+   */
+  _assertFactoryProperties() {
+    const Ctor = /** @type {any} */ (this.constructor);
+    if (_propsChecked.has(Ctor)) return;
+    let C = Ctor;
+    while (C && C !== WebComponentBase) {
+      if (Object.hasOwn(C, 'properties') && !Object.hasOwn(C, FACTORY_PROPS)) {
+        const name = C.name || 'a component';
+        throw new Error(
+          `${name}: \`static properties\` is no longer supported. Declare reactive ` +
+            `properties via the factory instead: \`class ${name} extends WebComponent({ ` +
+            `count: Number })\`. Use the \`prop()\` helper for options ` +
+            `(\`prop(Number, { reflect: true })\`) and set defaults via the \`default\` ` +
+            `option or in the constructor. See https://docs.webjs.com/docs/components.`,
+        );
+      }
+      C = Object.getPrototypeOf(C);
+    }
+    _propsChecked.add(Ctor);
+  }
+
   /**
    * For every key in `static properties`, create a getter/setter pair on
    * the instance that coerces values, runs `hasChanged`, schedules updates,
@@ -893,8 +939,13 @@ export class WebComponent extends Base {
 
     const Ctor = /** @type any */ (this.constructor);
     const propName = camelCase(name);
-    const def = Ctor.properties && (Ctor.properties[propName] || Ctor.properties[name]);
-    if (!def) return;
+    const raw = Ctor.properties && (Ctor.properties[propName] || Ctor.properties[name]);
+    if (!raw) return;
+    // A declaration is either a full descriptor (`{ type: Number, … }`) or the
+    // bare-constructor shorthand the factory accepts (`count: Number`), in which
+    // case the value IS the type. Normalise so type-based coercion fires either
+    // way (matches `_initializeProperties`).
+    const def = typeof raw === 'object' ? raw : { type: raw };
 
     let v;
     if (def.converter && def.converter.fromAttribute) {
@@ -1553,3 +1604,41 @@ function hyphenate(s) {
 function camelCase(s) {
   return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
+
+/**
+ * Dual-role WebComponent class and factory.
+ * Can be extended directly: `class X extends WebComponent`
+ * Or called as a class factory: `class X extends WebComponent({ count: Number })`
+ *
+ * @param {Record<string, any>} [properties]
+ * @returns {any}
+ */
+export function WebComponent(properties) {
+  if (new.target) {
+    return Reflect.construct(WebComponentBase, arguments, new.target);
+  } else {
+    return class extends WebComponentBase {
+      static properties = properties;
+      static [FACTORY_PROPS] = true;
+    };
+  }
+}
+
+// Ensure static inheritance and instanceof checks work
+Object.setPrototypeOf(WebComponent, WebComponentBase);
+WebComponent.prototype = WebComponentBase.prototype;
+
+/**
+ * Helper to define properties with custom options.
+ *
+ * @param {any} [type]
+ * @param {any} [opts]
+ * @returns {any}
+ */
+export function prop(type, opts = {}) {
+  if (type && typeof type === 'object' && !('call' in type)) {
+    opts = type;
+    type = undefined;
+  }
+  return { ...(type ? { type } : {}), ...opts };
+}

package/src/render-server.js

@@ -1052,12 +1052,16 @@ function appendReflectedAttrs(opening, instance, presentAttrNames) {
 function applyAttrsToInstance(instance, attrs, Cls) {
   const props = Cls.properties || {};
   for (const [key, raw] of Object.entries(attrs)) {
-    const def = props[key] || props[camelCase(key)];
+    const rawDef = props[key] || props[camelCase(key)];
     const propName = props[key] ? key : camelCase(key);
-    if (!def) {
+    if (!rawDef) {
       instance[propName] = raw;
       continue;
     }
+    // The factory accepts a bare constructor shorthand (`{ expanded: Boolean }`)
+    // alongside the long form (`{ expanded: { type: Boolean } }`); normalize so
+    // the type-based coercion below sees a `{ type }` object either way.
+    const def = typeof rawDef === 'object' ? rawDef : { type: rawDef };
     if (def.type === Number) instance[propName] = Number(raw);
     else if (def.type === Boolean) instance[propName] = raw !== 'false';
     else if (def.type === Object || def.type === Array) {