@weaverse/react 5.17.1 → 5.18.0

package/src/hooks.ts

@@ -0,0 +1,69 @@
+import { Weaverse, type WeaverseItemStore } from '@weaverse/core'
+import { useContext } from 'react'
+import { WeaverseContext, WeaverseItemContext } from './context'
+
+export type { DataContext } from './utils/data-connector'
+// Re-export the data connector utilities
+export {
+  replaceContentDataConnectors,
+  replaceContentDataConnectorsDeep,
+} from './utils/data-connector'
+
+/**
+ * Returns the active Weaverse runtime from React context.
+ *
+ * @typeParam T - Runtime subtype expected by the integration.
+ */
+export function useWeaverse<T = Weaverse>() {
+  let weaverse = useContext(WeaverseContext)
+  return weaverse as T
+}
+
+/**
+ * Returns a Weaverse item instance by ID, or the current rendered item when no
+ * ID is provided.
+ *
+ * @param id - Optional item ID to look up.
+ * @returns The matching item instance, or `null` when it is unavailable.
+ */
+export let useItemInstance = (id?: string) => {
+  let { id: currentId } = useContext(WeaverseItemContext)
+  let instance = Weaverse.itemInstances.get(id || currentId)
+  if (!instance) {
+    console.log(`Item instance ${id} not found`)
+    return null
+  }
+  return instance as WeaverseItemStore
+}
+
+/**
+ * Returns the parent instance of the current rendered item.
+ *
+ * @returns The parent item instance. At the root, the empty parent ID falls
+ * back to the current item instance; returns `null` only when that lookup is
+ * unavailable.
+ */
+export let useParentInstance = () => {
+  let { parentId } = useContext(WeaverseItemContext)
+  return useItemInstance(parentId || '')
+}
+
+/**
+ * Returns the direct child instances of an item.
+ *
+ * @param id - Optional parent item ID; defaults to the current rendered item.
+ */
+export let useChildInstances = (id?: string) => {
+  let currentInstance = useItemInstance(id)
+  if (!currentInstance) {
+    return []
+  }
+  let { itemInstances } = Weaverse
+
+  let {
+    data: { children },
+  } = currentInstance
+  return children
+    .map(({ id }: { id: string }) => itemInstances.get(id))
+    .filter(Boolean) as WeaverseItemStore[]
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * React bindings, rendering primitives, and hooks for Weaverse applications.
+ *
+ * @packageDocumentation
+ */
+export * from '@weaverse/core'
+export * from './context'
+export * from './hooks'
+export * from './renderer'
+export * from './types'

package/src/renderer.tsx

@@ -0,0 +1,204 @@
+import type { Weaverse } from '@weaverse/core'
+import clsx from 'clsx'
+import React, { memo, useEffect, useMemo, useRef } from 'react'
+import { WeaverseContextProvider, WeaverseItemContext } from './context'
+import { useItemInstance, useWeaverse } from './hooks'
+import type { ItemComponentProps, WeaverseRootPropsType } from './types'
+import { replaceContentDataConnectorsDeep } from './utils/data-connector'
+
+const REACT_VERSION_THRESHOLD = 18
+const reactVersion = Number(React.version?.split('.')[0]) || 0
+
+/**
+ * Reads an external store in React while remaining safe during server rendering
+ * and on React versions without `useSyncExternalStore`.
+ *
+ * @param subscribe - Registers a callback for store changes.
+ * @param getSnapshot - Returns the current client snapshot.
+ * @param getServerSnapshot - Returns the server snapshot; defaults to `getSnapshot`.
+ * @returns The current external-store snapshot.
+ */
+export const useSafeExternalStore = (
+  subscribe: any,
+  getSnapshot: any,
+  getServerSnapshot: any = getSnapshot
+) => {
+  // In server environment or during SSR, just return the snapshot directly
+  if (typeof window === 'undefined') {
+    return getServerSnapshot()
+  }
+
+  // In client environment, use React.useSyncExternalStore if available (React 18+)
+  if (React.useSyncExternalStore) {
+    // biome-ignore lint/correctness/useHookAtTopLevel: <$>
+    return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+  }
+
+  // Fallback for older React versions - just return the current snapshot
+  return getSnapshot()
+}
+
+/**
+ * Determines the root element ID for the Weaverse component tree.
+ * Falls back through multiple strategies to ensure a valid root is always found:
+ * 1. Use explicit rootId from context.data if available
+ * 2. Find the first element with type 'main' in items array
+ * 3. Use projectId as final fallback
+ */
+const getRootId = (context: Weaverse): string => {
+  // Strategy 1: Explicit rootId
+  if (context.data.rootId) {
+    return context.data.rootId
+  }
+
+  // Strategy 2: Find main element
+  let mainItem = context.data?.items?.find((item) => item.type === 'main')
+  if (mainItem?.id) {
+    return mainItem.id
+  }
+
+  // Strategy 3: Fallback to projectId
+  return context.projectId
+}
+/**
+ * Renders a Weaverse content tree and provides its runtime to descendant
+ * components.
+ */
+export const WeaverseRoot = memo(({ context }: WeaverseRootPropsType) => {
+  const data = useSafeExternalStore(
+    context.subscribe,
+    context.getSnapShot,
+    context.getSnapShot
+  )
+  const rootRef = useRef<HTMLElement>(null)
+
+  useEffect(() => {
+    context.contentRootElement = rootRef.current
+  }, [context])
+
+  const eventHandlers = context?.studioBridge?.eventHandlers || {}
+
+  if (context.projectId) {
+    return (
+      <div
+        className="weaverse-content-root"
+        {...eventHandlers}
+        data-weaverse-project-id={context.projectId}
+        data-weaverse-template-id={data.id}
+        ref={rootRef}
+      >
+        <WeaverseContextProvider value={context}>
+          <ItemInstance id={getRootId(context)} parentId={''} />
+        </WeaverseContextProvider>
+      </div>
+    )
+  }
+  return null
+})
+WeaverseRoot.displayName = 'WeaverseRoot'
+const ItemComponent = memo(({ instance }: ItemComponentProps) => {
+  const context = useWeaverse()
+  const { elementRegistry } = context
+  const data = useSafeExternalStore(
+    instance.subscribe,
+    instance.getSnapShot,
+    instance.getSnapShot
+  )
+  const {
+    id,
+    type,
+    childIds = [],
+    children = [],
+
+    createdAt,
+    updatedAt,
+    deletedAt,
+    css,
+    __hidden,
+    // Need to get rid of this `data` property
+    data: _,
+    ...rest
+  } = data
+
+  // Replace data connectors in all component data (handles strings, objects, and arrays recursively)
+  // IMMUTABLE: Process the entire rest object to avoid mutating original content
+  // Memoized per snapshot: `data` identity changes exactly when the item's
+  // store or translation entry changes (see WeaverseHydrogenItem.getSnapShot),
+  // and context-only updates swap the store reference via `setData({})` in
+  // syncReusedInstance — so re-renders with an unchanged snapshot skip the
+  // deep placeholder scan + clone entirely.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `rest` is a pure projection of `data`
+  const processedRest = useMemo(
+    () => replaceContentDataConnectorsDeep(rest, context.dataContext),
+    [data, context.dataContext]
+  )
+
+  useEffect(() => {
+    if (!instance.ref.current) {
+      // Fallback `ref` if the element isn't created by `React.forwardRef`
+      Object.assign(instance.ref, {
+        current: document.querySelector(`[data-wv-id="${id}"]`),
+      })
+    }
+  }, [instance, id])
+
+  if (__hidden) {
+    return null
+  }
+
+  const Element = elementRegistry.get(type)
+
+  if (Element?.Component) {
+    const Component = Element.Component
+    if (Component.displayName !== type) {
+      // Devtools nicety — assign once, not on every render.
+      Component.displayName = type
+    }
+    if (
+      Component.$$typeof === Symbol.for('react.forward_ref') ||
+      reactVersion > REACT_VERSION_THRESHOLD
+    ) {
+      processedRest.ref = instance.ref
+    }
+    const childItems = children?.length
+      ? children
+      : childIds?.length
+        ? childIds.map((cid: string) => ({ id: cid }))
+        : []
+
+    const renderChildren = childItems.map(
+      (item: { id: string }, index: number) => (
+        <ItemInstance id={item.id} key={`${item.id}-${index}`} parentId={id} />
+      )
+    )
+
+    return (
+      <Component
+        {...processedRest}
+        children={renderChildren.length ? renderChildren : undefined}
+        className={clsx(processedRest.data?.className)}
+        data-wv-id={id}
+        data-wv-type={type}
+        key={id}
+      />
+    )
+  }
+  instance._store.deleted = true
+  return null
+})
+ItemComponent.displayName = 'WeaverseComponent'
+
+const ItemInstance = memo(
+  ({ id, parentId }: { id: string; parentId: string }) => {
+    const instance = useItemInstance(id)
+    if (!instance) {
+      return <div style={{ display: 'none' }}>Item instance {id} not found</div>
+    }
+    return (
+      <WeaverseItemContext.Provider value={{ parentId, id }}>
+        <ItemComponent instance={instance} key={id} />
+      </WeaverseItemContext.Provider>
+    )
+  }
+)
+ItemInstance.displayName = 'WeaverseInstanceProvider'

package/src/types/index.ts

@@ -0,0 +1,26 @@
+import type { ElementCSS, Weaverse, WeaverseItemStore } from '@weaverse/core'
+import type { ReactElement, ReactNode } from 'react'
+
+/** Common props accepted by React components rendered by Weaverse. */
+export interface WeaverseElementProps extends Partial<ReactElement> {
+  /** React content rendered inside the element. */
+  children?: ReactElement | ReactElement[] | ReactNode | ReactNode[]
+  /** CSS class names applied to the element. */
+  className?: string
+  /** Responsive CSS values configured for the element. */
+  css?: ElementCSS
+  /** Weaverse item ID associated with the rendered element. */
+  'data-wv-id'?: string
+}
+
+/** Props for the root Weaverse React renderer. */
+export type WeaverseRootPropsType = {
+  /** Weaverse runtime that owns the rendered content tree. */
+  context: Weaverse
+}
+
+/** Props used to render a registered component from its item store. */
+export type ItemComponentProps = {
+  /** Store instance containing the item's data and subscriptions. */
+  instance: InstanceType<typeof WeaverseItemStore>
+}