Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/check-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ jobs:
- run: deno task test
- run: deno task test:static
- run: deno task test:router
- run: deno task test:webcomponent
- run: deno run -A build.npm.ts
env:
RELEASE_VERSION: 0.0.0-release-check
Expand Down
142 changes: 142 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,148 @@ For documentation and other static sites with interactive islands, see
For SPA navigation, lazy route modules, loaders, and actions, see
[client routing and route data](docs/routing.md).

## Web Components

Import `webcomponent` from `radi/webcomponent` to turn a Radi component into
a native custom-element class:

```tsx
import { update } from 'radi';
import { webcomponent } from 'radi/webcomponent';

function Counter(this: HTMLElement, props: () => {
label?: string;
initialCount?: number;
onChange?: (value: number) => void;
}) {
let count = props().initialCount ?? 0;
return (
<button onclick={() => { count++; props().onChange?.(count); update(this); }}>
{() => `${props().label ?? 'Count'}: ${count}`}
</button>
);
}

const RadiCounter = webcomponent(Counter, {
attributes: { label: String, initialCount: Number },
events: { onChange: 'count-change' },
});
customElements.define('radi-counter', RadiCounter);
```

Use `<radi-counter label="Clicks" initial-count="5"></radi-counter>` in HTML, or create an
instance with `new RadiCounter()` and append it to the document. Listed
prop names map to kebab-case HTML attributes (`initialCount` → `initial-count`).
The adapter converts strings before passing them to the component. Converters
run once per attribute change, preserving object identity between changes.
The map accepts `String`, `Number`, `Boolean`, `JSON.parse`, or custom functions:

```ts
attributes: {
label: String,
initialCount: Number,
disabled: Boolean,
someConfiguration: JSON.parse,
someStructure: (value: string) => value.split('.'),
}
```

Missing or removed attributes yield `undefined` without invoking the converter,
so component defaults still work. `Boolean` is special: presence means `true`
(even `disabled="false"`), absence means `false`. `Number` uses JavaScript's
conversion rules, including empty string → `0` and invalid text → `NaN`.
Use a custom converter for validation or different semantics. If a converter
throws, the browser reports the callback error and the last successfully
converted prop is retained (or `undefined` before any success). The DOM attribute
still contains the invalid text; a subsequent valid change recovers normally.
Omitted `attributes` means no attribute props are observed. Conversion is one-way;
JavaScript props are not serialized back to attributes.

Assign `element.props = { label: 'Total' }` for JavaScript values, including
objects and callbacks. These props override attributes. Assign a new object
to update them; mutating the existing object does not trigger an update.
Use `element.props = {}` to return to attribute values. Props assigned before
registration are preserved when the browser upgrades the element. Supply
required props before connecting the element, or provide component defaults.

Every name declared in `attributes` or `events` also gets a typed DOM property:

```ts
const element = new RadiCounter();
element.initialCount = 5;
element.label = 'Total';
element.onChange = (count) => console.log(count);
document.body.append(element);
```

Property assignments preserve JavaScript values and update the shared `props`
object. Getters return a JavaScript override when present, otherwise the converted
attribute value. Replacing `element.props` also replaces overrides made through
individual properties. Assigning `undefined` is an explicit override; omit that
key from a new `props` object to restore the attribute fallback. Neither property
assignments nor `props` assignments reflect into HTML attributes. Properties set
before registration survive upgrade, including explicit `customElements.upgrade()`
on detached elements. If both an individual property and `props` were assigned
before upgrade, the individual property wins. Names that conflict with native
element APIs or adapter lifecycle methods are rejected; pass such component props
through the `props` object instead of declaring them as attributes or events.

Map component callback props to DOM event names with `events`. For example,
calling `props().onChange?.(count)` above emits `count-change` on the custom element:

```js
element.addEventListener('count-change', (event) => console.log(event.detail));
```

These are bubbling, composed, non-cancelable `CustomEvent`s. One callback argument
becomes `detail`; multiple arguments become an array; no arguments produce `null`
(the platform default). Event names are used exactly as supplied. A JavaScript
callback supplied through `element.props` is also called with the original
arguments, after event dispatch, and its return value is returned to the component.
Without a JavaScript callback, the bridge returns `undefined`. No callback names
are guessed, and native DOM events continue bubbling normally. To cancel an
operation, use the component's existing callback contract through JavaScript props;
`preventDefault()` on a bridged event does not cancel the callback.

The component runs once per connection. Read props inside reactive functions,
as with ordinary Radi components. Attribute and prop updates preserve local
component state. Removal runs Radi disconnect cleanup; reconnection creates a
fresh component instance while retaining the element's props and attributes.

Rendering uses light DOM and replaces the element's existing children. Page
styles apply normally; this adapter does not create a shadow root or slots.
The component's `this` remains its ordinary Radi host. Native bubbling events
reach the custom element. Register each name once, in a browser; importing the
module itself does not require a DOM and does not register any elements.

### Framework interoperability

Register the element before the framework renders it so property detection can
preserve objects and other non-string values. Use an empty custom-element host;
do not give it children owned by the surrounding framework.

| Framework | Property and event binding |
| --- | --- |
| React 19 | `<radi-counter initialCount={5} oncount-change={e => console.log(e.detail)} />` |
| Vue 3 | `<radi-counter :initial-count="5" @count-change="handleChange" />` |
| Angular | `<radi-counter [initialCount]="5" (count-change)="handleChange($event)" />` |

Vue requires the tag to match `compilerOptions.isCustomElement`. Angular requires
`CUSTOM_ELEMENTS_SCHEMA` on the consuming component or module. TypeScript JSX or
template checking may additionally require application-side element/event types.
Event handlers receive a `CustomEvent`; read its `detail` for the callback payload.

`deno task test:webcomponent` exercises real React 19.2.0, Vue 3.5.45, and Angular
22.2.5 in Chromium: number, boolean, and object bindings; custom events; reactive
updates preserving component state; and unmount cleanup. The tests also cover
direct browser usage and pre-registration property upgrades.

This is client-rendered integration, not a general standards certification.
Framework list moves that disconnect/reconnect the element reset local state.
SSR/hydration, cross-document adoption, Firefox, and WebKit are not verified.
There is no shadow-root/slot or form-association API. The underlying Radi renderer
still uses its existing `<host>` wrapper; this adapter does not change that markup.

## What Makes Radi Different

Radi takes a unique approach compared to React, Preact, or even Solid:
Expand Down
4 changes: 4 additions & 0 deletions build.npm.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ async function start() {
skipSourceOutput: true,
entryPoints: [
"./src/client.ts",
{
name: "./webcomponent",
path: "./src/webcomponent.ts",
},
{
name: "./router",
path: "./src/router.ts",
Expand Down
2 changes: 2 additions & 0 deletions deno.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
"name": "radi",
"version": "0.5.0",
"tasks": {
"test:webcomponent": "deno test -A --unstable-bundle --config deno.server.json tests/webcomponent_test.ts",
"test:starters": "deno test -A --config deno.server.json tests/starters_test.ts",
"docs:build": "deno run -A site/build.ts",
"docs:preview": "deno run -A site/build.ts --serve",
Expand All @@ -19,6 +20,7 @@
"exports": {
".": "./src/client.ts",
"./client": "./src/client.ts",
"./webcomponent": "./src/webcomponent.ts",
"./resume": "./src/resume.ts",
"./router": "./src/router.ts",
"./server": "./src/server.ts",
Expand Down
185 changes: 185 additions & 0 deletions deno.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion site/llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ These docs describe the current repository API. Components run once; dynamic exp

## Documentation

- [Guide](https://radi.js.org/index.md): Installation, JSX configuration, components, reactivity, lifecycle, rendering, and the full client, server, resumption, static generation, signal, channel, renderer, and JSX API reference with code examples. Generated from the same content as the human-readable guide.
- [Guide](https://radi.js.org/index.md): Installation, JSX configuration, components, reactivity, lifecycle, rendering, Web Components with typed attributes/properties and custom events, React/Vue/Angular integration, and the full client, server, resumption, static generation, signal, channel, renderer, and JSX API reference with code examples. Generated from the same content as the human-readable guide.
- [Server rendering](https://radi.js.org/docs/server-rendering.md): Rendering APIs, async behavior, streaming, and limitations.
- [Go and embedded V8](https://radi.js.org/docs/go-server.md): TSX bundling, the Go HTTP handler, async Flop operations, configuration, streaming, cancellation, deployment limits, and release checks. No Node/Deno serving process or persisted code cache.
- [Resumption](https://radi.js.org/docs/resumption.md): Boundaries, state, handler registration, event support, and limitations.
Expand Down
Loading
Loading