@astrale-os/shell-react 0.2.8 → 0.2.10-beta.2

package/src/components/boundaries.tsx

@@ -0,0 +1,113 @@
+import type { CredentialSnapshot } from '@astrale-os/shell'
+import type { ReactElement, ReactNode } from 'react'
+
+import { Component, Fragment } from 'react'
+
+import type { GraphResource } from '../graph/resource.js'
+
+import { useConnection } from '../session/connection/connection.hook.js'
+
+export function ViewBoundary<T>(props: {
+  readonly resource: GraphResource<T>
+  readonly children: (value: T) => ReactNode
+  readonly loading?: ReactNode
+  readonly empty?: ReactNode
+  readonly error?: (error: unknown) => ReactNode
+}): ReactElement {
+  const { resource } = props
+  if (resource.state === 'failed') {
+    if (props.error !== undefined) return <>{props.error(resource.error)}</>
+    throw resource.error
+  }
+  if (resource.data === undefined) return <>{props.loading ?? null}</>
+  if (resource.data === null) return <>{props.empty ?? null}</>
+  return <>{props.children(resource.data)}</>
+}
+
+export const GraphBoundary = ViewBoundary
+
+export interface ViewErrorBoundaryProps {
+  /** A render function receives the retry generation and can recreate rejected lazy resources. */
+  readonly children: ReactNode | ((generation: number) => ReactNode)
+  readonly fallback?: (error: unknown, retry: () => void) => ReactNode
+  readonly onError?: (error: unknown) => void
+}
+
+/** Catch Shell View render/lazy failures and remount the failed subtree on explicit retry. */
+export class ViewErrorBoundary extends Component<
+  ViewErrorBoundaryProps,
+  { readonly error: unknown; readonly generation: number }
+> {
+  override state = { error: undefined as unknown, generation: 0 }
+
+  static getDerivedStateFromError(error: unknown) {
+    return { error }
+  }
+
+  override componentDidCatch(error: unknown): void {
+    this.props.onError?.(error)
+  }
+
+  private readonly retry = (): void => {
+    this.setState((state) => ({ error: undefined, generation: state.generation + 1 }))
+  }
+
+  override render(): ReactNode {
+    if (this.state.error !== undefined) {
+      return (
+        this.props.fallback?.(this.state.error, this.retry) ??
+        defaultViewError(this.state.error, this.retry)
+      )
+    }
+    const content =
+      typeof this.props.children === 'function'
+        ? this.props.children(this.state.generation)
+        : this.props.children
+    return <Fragment key={this.state.generation}>{content}</Fragment>
+  }
+}
+
+export function defaultViewLoading(): ReactElement {
+  return (
+    <div role="status" aria-live="polite">
+      Loading view…
+    </div>
+  )
+}
+
+export function defaultViewError(_error: unknown, retry: () => void): ReactElement {
+  return (
+    <section role="alert">
+      <p>View could not load.</p>
+      <button type="button" onClick={retry}>
+        Retry
+      </button>
+    </section>
+  )
+}
+
+export function ConnectionBoundary(props: {
+  readonly children: ReactNode
+  readonly fallback?: (status: ReturnType<typeof useConnection>) => ReactNode
+}): ReactElement {
+  const connection = useConnection()
+  return connection.status === 'ready' ? (
+    <>{props.children}</>
+  ) : (
+    <>{props.fallback?.(connection) ?? null}</>
+  )
+}
+
+export function CredentialBoundary(props: {
+  readonly credential: CredentialSnapshot
+  readonly children: ReactNode
+  readonly fallback?: (credential: CredentialSnapshot) => ReactNode
+}): ReactElement {
+  return props.credential.state === 'valid' ||
+    props.credential.state === 'refreshing' ||
+    props.credential.state === 'degraded' ? (
+    <>{props.children}</>
+  ) : (
+    <>{props.fallback?.(props.credential) ?? null}</>
+  )
+}

package/src/components/can.tsx

@@ -0,0 +1,16 @@
+import type { PathLike } from '@astrale-os/sdk/graph/path'
+import type { schema } from '@astrale-os/sdk/schema'
+import type { ReactElement, ReactNode } from 'react'
+
+import type { PolicyObject } from '../auth/can.hook.js'
+
+import { useCan } from '../auth/can.hook.js'
+
+export function Can(props: {
+  readonly policy: PathLike | schema.PolicyRef
+  readonly object: PolicyObject
+  readonly children: ReactNode
+  readonly fallback?: ReactNode
+}): ReactElement {
+  return <>{useCan(props.policy, props.object) === true ? props.children : props.fallback}</>
+}

package/src/components/index.ts

@@ -0,0 +1,14 @@
+export { Can } from './can.js'
+export {
+  ConnectionBoundary,
+  CredentialBoundary,
+  defaultViewError,
+  defaultViewLoading,
+  GraphBoundary,
+  ViewErrorBoundary,
+  ViewBoundary,
+} from './boundaries.js'
+export type { ViewErrorBoundaryProps } from './boundaries.js'
+export { ViewApp } from './view-app.js'
+export { mountDomainFrontend } from './mount-domain-frontend.js'
+export type { MountedDomainFrontend, MountDomainFrontendOptions } from './mount-domain-frontend.js'

package/src/components/mount-domain-frontend.tsx

@@ -0,0 +1,158 @@
+import type { Domain, Definition } from '@astrale-os/sdk/domain'
+import type { ReactRouteModule, ReactViewModule, ReactViewProps } from '@astrale-os/sdk/react'
+import type { schema } from '@astrale-os/sdk/schema'
+import type { Shell, ShellConfig } from '@astrale-os/shell'
+import type { ComponentType, LazyExoticComponent, ReactElement, ReactNode } from 'react'
+
+import { createElement, lazy, Suspense } from 'react'
+import { createRoot } from 'react-dom/client'
+
+import { useHistoryVersion, useOptionalNavCtx } from '../navigation/scope.context.js'
+import { useDomain } from '../schema/domain.hook.js'
+import { useTargetPath } from '../window/hooks/target-node.hook.js'
+import { defaultViewError, defaultViewLoading, ViewErrorBoundary } from './boundaries.js'
+import { ViewApp } from './view-app.js'
+
+type ViewName<S extends schema.DomainSchema> = Extract<keyof ReactRouteModule<S>['routes'], string>
+type ViewOf<S extends schema.DomainSchema, Name extends ViewName<S>> = Extract<
+  Domain<S>[Name],
+  Definition<'view'>
+>
+
+export interface MountDomainFrontendOptions<
+  S extends schema.DomainSchema,
+  Name extends ViewName<S>,
+> {
+  readonly root: Element | string
+  readonly module: ReactRouteModule<S>
+  readonly view: Name
+  /** Defaults to the child-side sandbox handshake. A prebuilt Shell is the full-app escape hatch. */
+  readonly config?: ShellConfig | Shell
+  readonly fallback?: ReactNode
+  readonly errorFallback?: (error: unknown, retry: () => void) => ReactNode
+  readonly onError?: (error: unknown) => void
+}
+
+export interface MountedDomainFrontend {
+  unmount(): void
+}
+
+/** Browser bootstrap used by SDK-generated route entries and custom full React apps alike. */
+export function mountDomainFrontend<
+  const S extends schema.DomainSchema,
+  const Name extends ViewName<S>,
+>(options: MountDomainFrontendOptions<S, Name>): MountedDomainFrontend {
+  const rootElement =
+    typeof options.root === 'string' ? document.querySelector(options.root) : options.root
+  if (rootElement === null) throw new Error(`React frontend root '${options.root}' was not found.`)
+  const route = options.module.routes[options.view]
+  if (route === undefined) throw new Error(`React View '${options.view}' is not implemented.`)
+  const loading = options.fallback ?? defaultViewLoading()
+  const errorFallback = options.errorFallback ?? defaultViewError
+  const routeRuntime = createRouteRuntime()
+  const root = createRoot(rootElement)
+  root.render(
+    <ViewApp
+      config={options.config ?? { mode: 'sandboxed' }}
+      fallback={loading}
+      errorFallback={errorFallback}
+      onError={({ error }) => options.onError?.(error)}
+    >
+      <ViewErrorBoundary fallback={errorFallback} onError={options.onError}>
+        {(generation) => (
+          <Suspense fallback={loading}>
+            <DomainRoute
+              module={options.module}
+              name={options.view}
+              generation={generation}
+              runtime={routeRuntime}
+            />
+          </Suspense>
+        )}
+      </ViewErrorBoundary>
+    </ViewApp>,
+  )
+  return Object.freeze({ unmount: () => root.unmount() })
+}
+
+function DomainRoute<S extends schema.DomainSchema, Name extends ViewName<S>>(props: {
+  readonly module: ReactRouteModule<S>
+  readonly name: Name
+  readonly generation: number
+  readonly runtime: RouteRuntime
+}): ReactElement {
+  const domain = useDomain(props.module.schema)
+  const navigation = useOptionalNavCtx()
+  useHistoryVersion(navigation?.history ?? null)
+  const view = domain[props.name] as ViewOf<S, Name>
+  // Domain's schema-indexed conditional retains the exact authored View type,
+  // while the runtime member has Core's common rich Definition shape.
+  const runtimeView = view as unknown as Definition<'view'>
+  const targetPath = useTargetPath()
+  const implementation = props.module.routes[props.name]!
+  const Component = props.runtime.component<ViewOf<S, Name>>(props.generation, implementation)
+  const declaration = runtimeView.definition as { readonly target: { readonly kind: string } }
+  const target =
+    declaration.target.kind === 'domain'
+      ? Object.freeze({ kind: 'domain' as const, origin: runtimeView.origin })
+      : targetPath === null
+        ? missingTarget(runtimeView.name)
+        : targetPath
+  const current = new URL(window.location.href)
+  const routeParams = navigation?.history.current?.params ?? directRouteParams(current)
+  const route = Object.freeze({
+    name: props.name,
+    href: current.href,
+    params: Object.freeze({ ...routeParams }),
+  })
+  return createElement(Component, { view, target, route } as unknown as ReactViewProps<
+    ViewOf<S, Name>
+  >)
+}
+
+function directRouteParams(url: URL): Readonly<Record<string, string>> {
+  const params: Record<string, string> = {}
+  const prefix = 'astrale.param.'
+  for (const key of new Set(url.searchParams.keys())) {
+    if (!key.startsWith(prefix)) continue
+    const name = key.slice(prefix.length)
+    if (name.length === 0 || /token|credential|authorization|secret/i.test(name)) {
+      throw new TypeError(`React View route param '${name}' is invalid.`)
+    }
+    const values = url.searchParams.getAll(key)
+    if (values.length !== 1) throw new TypeError(`React View route param '${name}' is duplicated.`)
+    params[name] = values[0]!
+  }
+  return Object.freeze(params)
+}
+
+interface RouteRuntime {
+  component<View extends Definition<'view'>>(
+    generation: number,
+    implementation: { readonly component: () => Promise<ReactViewModule<View>> },
+  ): ComponentType<ReactViewProps<View>>
+}
+
+function createRouteRuntime(): RouteRuntime {
+  const generations = new Map<number, LazyExoticComponent<ComponentType<ReactViewProps<never>>>>()
+  return {
+    component<View extends Definition<'view'>>(
+      generation: number,
+      implementation: { readonly component: () => Promise<ReactViewModule<View>> },
+    ): ComponentType<ReactViewProps<View>> {
+      let Component = generations.get(generation)
+      if (Component === undefined) {
+        Component = lazy(async () => {
+          const loaded = await implementation.component()
+          return { default: loaded.default as ComponentType<ReactViewProps<never>> }
+        })
+        generations.set(generation, Component)
+      }
+      return Component as unknown as ComponentType<ReactViewProps<View>>
+    },
+  }
+}
+
+function missingTarget(name: string): never {
+  throw new Error(`React View '${name}' requires a resource target from the Shell handshake.`)
+}

package/src/components/view-app.tsx

@@ -0,0 +1,49 @@
+import type { Shell, ShellConfig } from '@astrale-os/shell'
+import type { ReactElement, ReactNode } from 'react'
+
+import type { NavAdapter } from '../navigation/adapters/adapter.js'
+import type { NavTarget } from '../navigation/snapshot.js'
+import type { ShellProviderProps } from '../session/provider.js'
+
+import { memoryAdapter } from '../navigation/adapters/memory.adapter.js'
+import { urlAdapter } from '../navigation/adapters/url.adapter.js'
+import { NavScope } from '../navigation/scope.context.js'
+import { ShellProvider } from '../session/provider.js'
+import { useShell } from '../session/shell.hook.js'
+import { ViewStage } from '../window/stage.js'
+
+/** One generated/default root; custom React apps may compose the lower-level providers directly. */
+export function ViewApp(props: {
+  readonly config: ShellConfig | Shell
+  readonly navigation?: NavAdapter
+  readonly initial?: NavTarget
+  readonly fallback?: ReactNode
+  readonly errorFallback?: ShellProviderProps['errorFallback']
+  readonly onError?: ShellProviderProps['onError']
+  readonly children: ReactNode
+}): ReactElement {
+  return (
+    <ShellProvider
+      config={props.config}
+      fallback={props.fallback}
+      errorFallback={props.errorFallback}
+      onError={props.onError}
+    >
+      <ViewAppRuntime {...props} />
+    </ShellProvider>
+  )
+}
+
+function ViewAppRuntime(
+  props: Omit<Parameters<typeof ViewApp>[0], 'config' | 'fallback'>,
+): ReactElement {
+  const shell = useShell()
+  const defaultAdapter =
+    shell.hostCapabilities.navigation.history === 'browser' ? urlAdapter() : memoryAdapter()
+  return (
+    <NavScope adapter={props.navigation ?? defaultAdapter} initial={props.initial}>
+      {props.children}
+      <ViewStage />
+    </NavScope>
+  )
+}

package/src/graph/call/call.hook.ts

@@ -1,41 +1,36 @@
-/**
- * useCall (API §7) — unary domain-function dispatch over `kernel.call`, in the
- * Action envelope. No result caching, no liveness — domain function reads are not
- * structurally invalidatable (FRONTEND §5.7); a consumer that needs freshness
- * owns its own refetch policy. Dispatch is a graph operation (rule 2).
- */
-import type { CallFns, FnMap } from '@astrale-os/kernel-client'
+import type { Call } from '@astrale-os/kernel-client'
+import type { SessionRequestOptions } from '@astrale-os/kernel-client/session'
+import type { Value } from '@astrale-os/sdk/value'
 
 import type { Action } from '../action.js'
 
 import { useSessionKernel } from '../../auth/session-kernel.js'
 import { useAction } from '../action.js'
 
-export interface CallOptions {
-  /** Per-call timeout (ms), forwarded to the kernel dispatch. */
-  timeout?: number
-  /** Side-channel notified on rejection (the Action also records `.error`). */
-  onError?(error: unknown): void
+export interface CallOptions extends SessionRequestOptions {
+  readonly onError?: (error: unknown) => void
 }
 
-/**
- * Unary domain-function dispatch as an {@link Action}. `method` is a typed FnMap
- * `call` path or any string (the untyped floor); `null` yields an idle action
- * that rejects if invoked. Params/result are typed from the FnMap entry.
- */
-export function useCall<K extends CallFns<FnMap>>(
-  method: K | null,
-  opts?: CallOptions,
-): Action<[FnMap[K]['params']], FnMap[K]['result']> {
+export type CallResult = Value
+type CallAuthor<A extends unknown[]> = Call | ((...args: A) => Call)
+
+export function useCall(call: Call | null, options?: CallOptions): Action<[], CallResult>
+export function useCall<A extends unknown[]>(
+  author: ((...args: A) => Call) | null,
+  options?: CallOptions,
+): Action<A, CallResult>
+export function useCall<A extends unknown[]>(
+  author: CallAuthor<A> | null,
+  options?: CallOptions,
+): Action<A, CallResult> {
   const kernel = useSessionKernel()
-  // A fresh closure per render captures the current method/opts; `useAction`
-  // keeps ONE stable callable and always dispatches this latest closure.
-  return useAction(async (params: FnMap[K]['params']): Promise<FnMap[K]['result']> => {
-    if (method === null) throw new Error('useCall: method is null (idle action invoked)')
+  return useAction(async (...args: A) => {
+    if (author === null) throw new Error('useCall: idle action invoked')
+    const call = typeof author === 'function' ? author(...args) : author
     try {
-      return await kernel.call(method, params, { timeout: opts?.timeout })
+      return await kernel.call(call, options)
     } catch (error) {
-      opts?.onError?.(error)
+      options?.onError?.(error)
       throw error
     }
   })