Skip to content

RFC 17: renders and renders(root, ctx…): JS fns that render the components they are given #18

Open

Description

@yumemi-thomas

One of a series of small proposals, in order; the tracking issue lists them. Depends on: RFC 5 (#6).

Summary

Add two declaration words to a JS fn that takes components but is not a factory. renders means the components are rendered where the call's result is bound. renders(root, ctx…) means the library mounts them under a root of its own, carrying in only the named JS contexts. Each word tells the checker where to check the components, instead of refusing them.

Motivation

On upstream (PR solidjs#69), a component may be a value only on a Component prop of a JS component or inside a factory's arguments (a factory is a JS fn declared to return a Component). Two common library shapes are neither:

  • A headless table. TanStack Table's column definitions carry cell components, and the app renders each cell through flexRender(cell.column.cell, …) in its own view. createTable({ columns: [{ cell: NameCell }] }) returns a table, not a component, so on upstream NameCell is COMPONENT_AS_VALUE.
  • A toaster, modal manager or widget host. It mounts the components it is given with a render() or createRoot of its own. Solid's useContext and boundaries walk the owner chain, and that root has none of the app's owners. A provide or errored above the call does not reach the toast at run time. Even if the component were allowed, checking it under the call would accept programs that fail.

Proposal

MO-11l (renders). renders on a declared fn that returns no component says it renders the components in its argument literals through something the app calls later. They are found as a factory's are (MO-11c, MO-11g) and checked as applied, with no arguments, where the result is bound: among the children of that region. Their failures, contexts and first loads are checked above the binding. renders implies instantiates.

// table.d.rx
export pure fn createTable(ref options: { data: any[]; columns: { key: string; cell: Component }[] }): any renders
export pure fn flexRender(comp: any, props: any): any
export default component App() {
  provide accent = "hot"
  errored fallback(e) { <p>failed</p> } {
    loading fallback { <p>loading…</p> } {
      table = createTable({ data: people, columns: [{ key: "name", cell: NameCell }, { key: "name", cell: NoteCell }] })
      <table><tbody>{for row in table.rows {
        <tr>{for cell in row.cells { <td>{flexRender(cell.column.cell, { value: cell.value })}</td> }}</tr>
      }}</tbody></table>
    }
  }
}

MO-11n (renders(root, ctx…)). renders(root) is renders for a library that mounts the components under a root of its own. They are checked under a fresh root at the binding, the way a program's top-level view is. No provide, errored or loading above the binding reaches them, so a component that needs one is refused (CONTEXT_NOT_FOUND, UNHANDLED_FAILURE, or ASYNC_OUTSIDE_LOADING_BOUNDARY in a client-only build). A library that reads some of its own JS contexts where it is called and provides them inside its root names them: renders(root, toastTheme). Each named context is read at the call, as a hook's uses(…) is (MO-12b), so it must be provided above the binding. Only contexts declared in the same declaration file can be named (MO-12a): a library cannot carry the program's own contexts. Inside renders(…) the first word must be root (RFC 18 adds later), so renders(owner) is PARSE.

// toast.d.rx
export context toastTheme
export component ToastTheme(props: { children?: View }) provides(toastTheme)
export pure fn createToaster(options: { template: Component }): any renders(root)
export pure fn createThemedToaster(options: { template: Component }): any renders(root, toastTheme)

A toast template that provides and catches what it needs itself is accepted. One that relies on the app's provide accent above createToaster(…) is CONTEXT_NOT_FOUND, as it would fail at run time.

Drawbacks and alternatives

  • renders assumes the app renders the result inside the binding's region, which is DV-24's assumption moved to the binding. So bare renders is only for an API whose result the app renders there itself, as a headless table's cells are; a library that may mount elsewhere (a portal, a toaster) declares renders(root…), and one that says nothing gets the cautious placement (RFC 19). rx-verify checks a declaration's placement by running a small probe app (MO-11r).
  • Alternative: refuse components passed to such fns. That was upstream's answer, and it rules out headless tables and toasters entirely.
  • Alternative: trust the call (no check). That would let failures and missing contexts through unchecked (CN-5).
  • RFC 19 later makes "a root of its own, nothing carried" the default for a fn that says nothing, so renders(root) with no contexts matters mostly as documentation. renders and renders(root, ctx…) give back precision.

Prototype

Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript:

All three are in both parsers and checkers. Spec: MO-11l and MO-11n, both in the MO-11r table. Scenarios:

  • S-module-16: renders, with CONTEXT_NOT_FOUND and UNHANDLED_FAILURE at the binding.
  • S-module-18: renders(root) and carried contexts, including PARSE for renders(owner).

Both implementations (ref/ and the Rust crate) agree.

Revised after the second review (2026-11-21, cdc00d4)

RFC 17, after the second review. Bare renders is held to its claim: the bound result (or an equation that only names it) may be read through and rendered in the binding's view, but passing it to a component's prop, providing it, exporting it, writing it to a source or passing it to a call is RENDERS_ESCAPES, since its components would render under other boundaries than the binding's. A library whose result travels declares renders(later) and a consuming renders prop, or renders(root, …) (S-module-16).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions