@webjsdev/core 0.7.1

package/README.md

@@ -0,0 +1,55 @@
+# @webjsdev/core
+
+Isomorphic core runtime for [webjs](https://github.com/vivek7405/webjs), the
+AI-first, web-components-first, no-build web framework.
+
+This package ships the tagged-template `html` / `css` helpers, the
+`WebComponent` base class, the client and server renderers (with Declarative
+Shadow DOM support), directives, context protocol, the `Task` controller, and
+the client-side navigation router.
+
+Not intended for direct install. You'll usually get it as a transitive dep
+when you scaffold an app with [`@webjsdev/cli`](https://www.npmjs.com/package/@webjsdev/cli).
+
+## Install
+
+```sh
+npm install @webjsdev/core
+```
+
+## Use
+
+```js
+import { html, css, WebComponent } from '@webjsdev/core';
+
+class Counter extends WebComponent {
+  static properties = { count: { type: Number } };
+  static styles = css`button { padding: 8px 12px; }`;
+
+  render() {
+    return html`<button @click=${() => this.count++}>${this.count}</button>`;
+  }
+}
+Counter.register('x-counter');
+```
+
+`Class.register('tag-name')` is the webjs idiom. It calls
+`customElements.define()` under the hood and adds tag validation,
+registry bookkeeping (needed for lazy-loading), and a dev-time
+double-register warning. Plain `customElements.define('x-counter',
+Counter)` works identically.
+
+Side-channel imports for optional features:
+
+```js
+import '@webjsdev/core/client-router';            // SPA-style link interception
+import { unsafeHTML } from '@webjsdev/core/directives';
+import { createContext } from '@webjsdev/core/context';
+import { Task } from '@webjsdev/core/task';
+```
+
+See the full framework docs at https://github.com/vivek7405/webjs.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Public type surface for `webjs`.
+ *
+ * The runtime is packages/core/index.js (JSDoc-annotated JavaScript); this
+ * overlay exists so TypeScript-based editors (tsserver under VS Code,
+ * Neovim, Zed, WebStorm) resolve richer types than JSDoc alone can express
+ * - specifically the generic component factory and property-descriptor
+ * inference helpers. Zero runtime cost.
+ */
+
+export * from './src/component.d.ts';
+
+export { html, isTemplate, MARKER } from './src/html.js';
+export { css, isCSS, adoptStyles, stylesToString } from './src/css.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';
+export { escapeText, escapeAttr } from './src/escape.js';
+export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
+export { expose, getExposed } from './src/expose.js';
+export { repeat, isRepeat } from './src/repeat.js';
+export { Suspense, isSuspense } from './src/suspense.js';
+export { connectWS } from './src/websocket-client.js';
+export { richFetch } from './src/rich-fetch.js';
+export { enableClientRouter, disableClientRouter, navigate } from './src/router-client.js';
+export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
+export { Task, TaskStatus } from './src/task.js';

package/index.js

@@ -0,0 +1,39 @@
+/**
+ * webjs/core public surface.
+ *
+ * Isomorphic: this module is safe to import on both server and client.
+ * The client renderer is lazy-loaded by the WebComponent base. The server
+ * renderer is only reached on the server.
+ */
+
+export { html, isTemplate, MARKER } from './src/html.js';
+export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
+export { WebComponent } 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';
+export { escapeText, escapeAttr } from './src/escape.js';
+export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
+export { expose, getExposed } from './src/expose.js';
+export { repeat, isRepeat } from './src/repeat.js';
+export { Suspense, isSuspense } from './src/suspense.js';
+export { connectWS } from './src/websocket-client.js';
+export { richFetch } from './src/rich-fetch.js';
+export {
+  stringify, parse,
+  serialize, deserialize,
+} from './src/serialize.js';
+export { enableClientRouter, disableClientRouter, navigate, revalidate } from './src/router-client.js';
+export { WebjsFrame } from './src/webjs-frame.js';
+
+// Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
+export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
+
+// Directives, also available via '@webjsdev/core/directives'
+export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+
+// Context Protocol, also available via '@webjsdev/core/context'
+export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
+
+// Task controller, also available via '@webjsdev/core/task'
+export { Task, TaskStatus } from './src/task.js';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@webjsdev/core",
+  "version": "0.7.1",
+  "type": "module",
+  "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./client": "./src/render-client.js",
+    "./server": "./src/render-server.js",
+    "./component": {
+      "types": "./src/component.d.ts",
+      "default": "./src/component.js"
+    },
+    "./registry": "./src/registry.js",
+    "./client-router": "./src/router-client.js",
+    "./signals": "./src/signal.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vivek7405/webjs.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/vivek7405/webjs#readme",
+  "bugs": "https://github.com/vivek7405/webjs/issues",
+  "license": "MIT",
+  "keywords": [
+    "webjs",
+    "web-components",
+    "ssr",
+    "framework",
+    "no-build"
+  ]
+}

package/src/component.d.ts

@@ -0,0 +1,120 @@
+/**
+ * TypeScript overlay for packages/core/src/component.js.
+ *
+ * The runtime is JSDoc-authored JavaScript; this file exists so editors
+ * (tsserver: used by VS Code, Neovim, Zed, WebStorm) resolve imports
+ * with full type information. Without this overlay, `declare foo: Foo`
+ * would type the field but the surrounding class (`this.requestUpdate`,
+ * lifecycle hooks, controllers) would be weakly typed. Zero runtime
+ * cost: nothing in this file ships to the browser.
+ */
+
+import type { CSSResult } from './css.js';
+import type { TemplateResult } from './html.js';
+
+/** Any constructor the framework accepts as the `type:` field of a property. */
+export type PropertyConstructor<T = unknown> =
+  | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor
+  | ObjectConstructor
+  | ArrayConstructor
+  | (new (...args: any[]) => T)
+  | ((v: any) => T);
+
+/** Runtime-level property declaration: matches `static properties = { … }`. */
+export interface PropertyDeclaration<T = unknown> {
+  /** Constructor used for string → value coercion when the attribute changes. */
+  type?: PropertyConstructor<T>;
+  /** Write property changes back to the HTML attribute (kebab-cased). */
+  reflect?: boolean;
+  /** Internal-only: no attribute, no reflection, but still reactive. */
+  state?: boolean;
+  /** Rename the attribute, or pass `false` to suppress it entirely. */
+  attribute?: string | false;
+  /** Custom attribute ⇄ property serialisation. Takes precedence over `type`. */
+  converter?: {
+    fromAttribute?: (value: string | null, type?: PropertyConstructor<T>) => T;
+    toAttribute?: (value: T, type?: PropertyConstructor<T>) => string | null;
+  };
+  /** Custom dirty check. Return `true` to schedule an update. */
+  hasChanged?: (newValue: T, oldValue: T) => boolean;
+}
+
+/** Reactive controller protocol (Lit-compatible). */
+export interface ReactiveController {
+  hostConnected?(): void;
+  hostDisconnected?(): void;
+  hostUpdate?(): void;
+  hostUpdated?(): void;
+}
+
+/**
+ * Base class for interactive web components.
+ *
+ * Declare runtime behaviour via `static properties = { … }` and type
+ * each field with a sibling `declare foo: Foo`:
+ *
+ *     class StudentCard extends WebComponent {
+ *       static properties = { student: { type: Object } };
+ *       declare student: Student;
+ *       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.
+ *
+ * See the Editor Setup doc for tooling that gives attribute/tag
+ * intelligence inside `html\`…\`` templates.
+ */
+export abstract class WebComponent extends HTMLElement {
+  static shadow: boolean;
+  static hydrate: 'visible' | undefined;
+  static properties: Record<string, PropertyDeclaration>;
+  static styles: CSSResult | CSSResult[] | null;
+  static lazy?: boolean;
+  /** Register this class as a custom element under `tag`. Tag must contain a hyphen. */
+  static register(tag: string): void;
+  static readonly observedAttributes: string[];
+
+  /**
+   * 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
+   * `@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.
+   */
+  requestUpdate(name?: string, oldValue?: unknown): void;
+  /** A Promise that resolves after the next render commit. */
+  readonly updateComplete: Promise<boolean>;
+  /** Override point for `updateComplete`. Default returns the internal promise. */
+  getUpdateComplete(): Promise<boolean>;
+  /** Attach a reactive controller. */
+  addController(controller: ReactiveController): void;
+  /** Detach a reactive controller. */
+  removeController(controller: ReactiveController): void;
+  /** Returns the template for this render. May be async. */
+  render(): TemplateResult | Promise<TemplateResult> | void;
+  /** Decide whether to update. Default returns `true`. */
+  shouldUpdate(changedProperties: Map<string, unknown>): boolean;
+  /** Pre-render hook. Safe to set properties; folds into current cycle. */
+  willUpdate(changedProperties: Map<string, unknown>): void;
+  /** Render-and-commit step. Default calls `render()` and commits. */
+  update(changedProperties: Map<string, unknown>): void;
+  /** Post-render hook. Runs after every commit. */
+  updated(changedProperties: Map<string, unknown>): void;
+  /** One-shot hook after the first render lands in the DOM. */
+  firstUpdated?(changedProperties: Map<string, unknown>): void;
+  /** Optional render-error boundary inside the component. */
+  renderError?(error: Error): TemplateResult | void;
+
+  connectedCallback?(): void;
+  disconnectedCallback?(): void;
+  attributeChangedCallback?(name: string, oldValue: string | null, newValue: string | null): void;
+}