fix(hub): restore json-render pre-0.7 exports as deprecated aliases (#122)

Author: antfubot

docs/guide/migration-0.7.md

@@ -4,7 +4,7 @@ outline: deep
 
 # Migrating to 0.7
 
-0.7's one breaking change moves the `cac` CLI framework out of `devframe`'s bundled dependencies and renames the adapter that wraps it. This page covers the change between 0.6.x and 0.7.
+0.7 moves the `cac` CLI framework out of `devframe`'s bundled dependencies (renaming the adapter that wraps it) and moves json-render out of `@devframes/hub` into its own opt-in integration. This page covers the changes between 0.6.x and 0.7.
 
 ## `cac` is now an optional peer dependency
 
@@ -43,3 +43,35 @@ await createCac(devframe).parse()
 `devframe/adapters/cli` still exports `createCli` as a deprecated alias of `createCac` (same for `CreateCliOptions` and `CliHandle`), so existing imports keep compiling — but the underlying `cac` peer dependency still needs installing per above, and the alias will be removed in a future major release. Move call sites over now rather than waiting for that removal.
 
 See [CLI (cac)](/adapters/cac) for the full adapter reference.
+
+## json-render moves out of `@devframes/hub`
+
+The hub is now json-render-agnostic — `defineJsonRenderSpec`, `ctx.createJsonRenderer`, and the `JsonRenderSpec` / `JsonRenderElement` / `JsonRenderer` types move to the opt-in [`@devframes/json-render`](./json-render) integration, which contributes its own `json-render` dock type to the hub's open dock union instead of the hub shipping one.
+
+| 0.6.x (`@devframes/hub`) | 0.7 (`@devframes/json-render`) |
+|---|---|
+| `defineJsonRenderSpec(spec)` | Pass the spec directly to `createJsonRenderView(ctx, { id, spec })` |
+| `JsonRenderSpec` | `DevframeJsonRenderSpec` |
+| `ctx.createJsonRenderer(spec)` | `createJsonRenderView(ctx, { id, spec })` (from `@devframes/json-render/node`) |
+
+```ts
+// 0.6.x
+import { defineJsonRenderSpec } from '@devframes/hub'
+
+const spec = defineJsonRenderSpec({ root: 'panel', elements: { /* ... */ } })
+const renderer = ctx.createJsonRenderer(spec)
+```
+
+```ts
+// 0.7
+import { createJsonRenderView } from '@devframes/json-render/node'
+
+const view = createJsonRenderView(ctx, {
+  id: 'panel',
+  spec: { root: 'panel', elements: { /* ... */ } },
+})
+```
+
+`@devframes/hub` still exports `defineJsonRenderSpec` as a deprecated identity function (same for the `JsonRenderSpec` / `JsonRenderElement` / `JsonRenderer` types), so existing imports keep compiling — but it no longer registers anything with the hub on its own. Move call sites over to `createJsonRenderView` now rather than waiting for the alias's removal in a future major release.
+
+See [JSON-Render](./json-render) for the full integration reference.

packages/hub/src/define.ts

@@ -2,6 +2,7 @@ import type { WhenContext, WhenExpression } from 'devframe/utils/when'
 import type { DevframeHubContext } from './node/context'
 import type { DevframeServerCommandInput } from './types/commands'
 import type { DevframeDockUserEntry } from './types/docks'
+import type { JsonRenderSpec } from './types/json-render'
 import { createDefineWrapperWithContext } from 'devframe/rpc'
 
 export const defineHubRpcFunction = createDefineWrapperWithContext<DevframeHubContext>()
@@ -20,3 +21,14 @@ export function defineDockEntry<
 ): T {
   return entry as unknown as T
 }
+
+/**
+ * @deprecated json-render moved out of the hub into the opt-in
+ * `@devframes/json-render` integration in 0.7. This identity helper is kept
+ * so existing imports keep compiling — pass your spec directly to
+ * `createJsonRenderView` (from `@devframes/json-render/node`) instead. Will
+ * be removed in a future major release.
+ */
+export function defineJsonRenderSpec(spec: JsonRenderSpec): JsonRenderSpec {
+  return spec
+}

packages/hub/src/types/docks.ts

@@ -1,4 +1,5 @@
 import type { ConnectionMeta, EventEmitter } from 'devframe/types'
+import type { JsonRenderer } from './json-render'
 
 export interface DevframeDocksHost {
   readonly views: Map<string, DevframeDockUserEntry>
@@ -251,6 +252,20 @@ export interface DevframeViewBuiltin extends DevframeDockEntryBase {
   id: string
 }
 
+/**
+ * @deprecated json-render moved out of the hub into the opt-in
+ * `@devframes/json-render` integration in 0.7, which contributes its own
+ * `'json-render'` entry (carrying a serializable view ref, not a live
+ * `JsonRenderer` handle) to {@link DevframeDockEntryRegistry} via declaration
+ * merging. This type is kept for compatibility but is no longer a member of
+ * {@link DevframeDockUserEntry} — use `@devframes/json-render/hub` instead.
+ */
+export interface DevframeViewJsonRender extends DevframeDockEntryBase {
+  type: 'json-render'
+  /** JsonRenderer handle created by ctx.createJsonRenderer() */
+  ui: JsonRenderer
+}
+
 /**
  * A dock group: a single dock-bar button that collapses every entry whose
  * {@link DevframeDockEntryBase.groupId} matches this group's `id`.

packages/hub/src/types/index.ts

@@ -4,6 +4,9 @@ export type { CreateHubContextOptions, DevframeHubContext } from '../node/contex
 
 export * from './commands'
 export * from './docks'
+// Deprecated pre-0.7 json-render types, kept for compatibility — see
+// `./json-render` for details on the `@devframes/json-render` replacement.
+export * from './json-render'
 export * from './messages'
 export * from './settings'
 export * from './terminals'

packages/hub/src/types/json-render.ts

@@ -0,0 +1,40 @@
+// Deprecated compatibility shim for the pre-0.7 hub-local json-render types.
+//
+// 0.7 moved json-render out of the hub into the opt-in `@devframes/json-render`
+// integration — use its `DevframeJsonRenderSpec` (from `@devframes/json-render`)
+// and `createJsonRenderView` (from `@devframes/json-render/node`) instead. These
+// types are kept so existing imports keep compiling; they will be removed in a
+// future major release.
+
+/** @deprecated Use `DevframeJsonRenderSpec`'s element shape from `@devframes/json-render` instead. */
+export interface JsonRenderElement {
+  type: string
+  props?: Record<string, unknown>
+  children?: string[]
+  /** json-render event bindings (e.g. `{ press: { action: "my:action" } }`) */
+  on?: Record<string, unknown>
+  /** json-render visibility condition */
+  visible?: unknown
+  /** json-render repeat binding */
+  repeat?: unknown
+  /** Allow additional json-render element fields */
+  [key: string]: unknown
+}
+
+/** @deprecated Use `DevframeJsonRenderSpec` from `@devframes/json-render` instead. */
+export interface JsonRenderSpec {
+  root: string
+  elements: Record<string, JsonRenderElement>
+  /** Initial client-side state model for $state/$bindState expressions */
+  state?: Record<string, unknown>
+}
+
+/** @deprecated Use `JsonRenderView` from `@devframes/json-render` instead. */
+export interface JsonRenderer {
+  /** Replace the entire spec */
+  updateSpec: (spec: JsonRenderSpec) => void | Promise<void>
+  /** Update json-render state values (shallow merge into spec.state) */
+  updateState: (state: Record<string, unknown>) => void | Promise<void>
+  /** Internal: shared state key used by the client to subscribe */
+  readonly _stateKey: string
+}

tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts

@@ -8,6 +8,8 @@ export declare function defineCommand<const W extends string = ''>(_: Omit<Devfr
 export declare function defineDockEntry<const T extends DevframeDockUserEntry, const W extends string = ''>(_: Omit<T, 'when'> & {
   when?: WhenExpression<WhenContext, W>;
 }): T;
+/** @deprecated */
+export declare function defineJsonRenderSpec(_: JsonRenderSpec): JsonRenderSpec;
 // #endregion
 
 // #region Variables
@@ -77,12 +79,16 @@ export { DevframeViewCustomRender }
 export { DevframeViewGroup }
 export { DevframeViewHost }
 export { DevframeViewIframe }
+export { DevframeViewJsonRender }
 export { DevframeViewLauncher }
 export { DevframeViewLauncherStatus }
 export { EntriesToObject }
 export { EventEmitter }
 export { EventsMap }
 export { EventUnsubscribe }
+export { JsonRenderElement }
+export { JsonRenderer }
+export { JsonRenderSpec }
 export { PartialWithoutId }
 export { RemoteConnectionInfo }
 export { RemoteDockOptions }

tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.js

@@ -5,4 +5,5 @@
 export { defineCommand }
 export { defineDockEntry }
 export { defineHubRpcFunction }
+export { defineJsonRenderSpec }
 // #endregion

tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts

@@ -64,12 +64,16 @@ export { DevframeViewCustomRender }
 export { DevframeViewGroup }
 export { DevframeViewHost }
 export { DevframeViewIframe }
+export { DevframeViewJsonRender }
 export { DevframeViewLauncher }
 export { DevframeViewLauncherStatus }
 export { EntriesToObject }
 export { EventEmitter }
 export { EventsMap }
 export { EventUnsubscribe }
+export { JsonRenderElement }
+export { JsonRenderer }
+export { JsonRenderSpec }
 export { PartialWithoutId }
 export { RemoteConnectionInfo }
 export { RemoteDockOptions }