@astrale-os/shell-react 0.2.9 → 0.2.10-beta.3

package/src/graph/resource.ts

@@ -0,0 +1,358 @@
+import type { GraphStore, StoreQueryResponse, StoreSnapshot } from '@astrale-os/kernel-client/store'
+import type { QueryAST } from '@astrale-os/sdk/query'
+
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+
+import { useGraphStore } from './store.js'
+
+export type GraphResourceState =
+  | 'idle'
+  | 'loading'
+  | 'ready'
+  | 'stale'
+  | 'refreshing'
+  | 'optimistic'
+  | 'failed'
+
+export interface GraphResource<T> {
+  readonly state: GraphResourceState
+  /** Current-scope data only. Previous-scope data is never substituted here. */
+  readonly data: T | undefined
+  readonly error: unknown
+  readonly previous?: { readonly identity: string; readonly data: T }
+  readonly transitioning: boolean
+  readonly live: false
+  readonly sequence: 0
+  refresh(): Promise<void>
+  readonly more: {
+    readonly has: boolean
+    readonly pending: boolean
+    load(): Promise<void>
+  }
+}
+
+export interface StoreResourceOptions<Output> {
+  readonly identity?: string
+  readonly keepPrevious?: boolean
+  readonly window?: 'page' | 'append'
+  readonly merge?: (pages: readonly Output[]) => Output
+  readonly refreshInterval?: number
+  readonly refreshWhen?: 'always' | 'visible'
+}
+
+interface PageRef {
+  readonly after?: string
+}
+
+interface ObserverSnapshot<Query extends QueryAST> {
+  readonly snapshots: readonly StoreSnapshot<Query>[]
+  readonly pendingMore: boolean
+}
+
+class StoreObserver<Query extends QueryAST> {
+  private readonly listeners = new Set<() => void>()
+  private pages: readonly PageRef[] = Object.freeze([Object.freeze({})])
+  private unsubs: readonly (() => void)[] = Object.freeze([])
+  private current: ObserverSnapshot<Query> | undefined
+  private morePromise: Promise<void> | null = null
+  private started = false
+
+  constructor(
+    private readonly store: GraphStore,
+    private readonly query: Query,
+    private readonly size: number,
+  ) {}
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  getSnapshot = (): ObserverSnapshot<Query> => {
+    if (this.current !== undefined) return this.current
+    this.current = Object.freeze({
+      snapshots: Object.freeze(
+        this.pages.map((page) => this.store.getSnapshot(this.query, this.pageOptions(page))),
+      ),
+      pendingMore: this.morePromise !== null,
+    })
+    return this.current
+  }
+
+  start(): () => void {
+    if (!this.started) {
+      this.started = true
+      this.bindPages()
+      void this.store
+        .read(this.query, {
+          ...this.pageOptions(this.pages[0]!),
+          freshness: 'cached',
+        })
+        .catch(() => {})
+    }
+    return () => {
+      this.started = false
+      this.unsubs.forEach((unsubscribe) => unsubscribe())
+      this.unsubs = Object.freeze([])
+    }
+  }
+
+  async refresh(): Promise<void> {
+    await Promise.all(
+      this.pages.map((page) =>
+        this.store.read(this.query, { ...this.pageOptions(page), freshness: 'refresh' }),
+      ),
+    )
+  }
+
+  hasMore(): boolean {
+    const snapshots = this.getSnapshot().snapshots
+    const last = snapshots[snapshots.length - 1]
+    const response = last === undefined ? undefined : responseOf(last)
+    return response?.page.next !== undefined
+  }
+
+  loadMore(): Promise<void> {
+    if (this.morePromise !== null) return this.morePromise
+    const snapshots = this.getSnapshot().snapshots
+    const last = snapshots[snapshots.length - 1]
+    const after = last === undefined ? undefined : responseOf(last)?.page.next
+    if (after === undefined) return Promise.resolve()
+    if (this.pages.some((page) => page.after === after)) return Promise.resolve()
+
+    this.pages = Object.freeze([...this.pages, Object.freeze({ after })])
+    this.bindPages()
+    this.morePromise = this.store
+      .read(this.query, { ...this.pageOptions({ after }), freshness: 'cached' })
+      .then(() => {})
+      .finally(() => {
+        this.morePromise = null
+        this.publish()
+      })
+    this.publish()
+    return this.morePromise
+  }
+
+  private pageOptions(page: PageRef) {
+    return Object.freeze({
+      page: Object.freeze({
+        size: this.size,
+        ...(page.after === undefined ? {} : { after: page.after }),
+      }),
+    })
+  }
+
+  private bindPages(): void {
+    this.unsubs.forEach((unsubscribe) => unsubscribe())
+    this.unsubs = Object.freeze(
+      this.pages.map((page) =>
+        this.store.subscribe(this.query, this.publish, this.pageOptions(page)),
+      ),
+    )
+    this.publish()
+  }
+
+  private publish = (): void => {
+    this.current = undefined
+    this.listeners.forEach((listener) => listener())
+  }
+}
+
+interface PollSubscriber {
+  readonly interval: number
+  readonly when: 'always' | 'visible'
+  readonly refresh: () => Promise<void>
+}
+
+interface PollScheduler {
+  readonly subscribers: Map<symbol, PollSubscriber>
+  timer: ReturnType<typeof setTimeout> | undefined
+  onVisibility?: () => void
+}
+
+const pollers = new WeakMap<GraphStore, Map<string, PollScheduler>>()
+
+/** Adapt exact Store pages into a tear-free React resource without a parallel entity cache. */
+export function useStoreResource<Query extends QueryAST, Output>(
+  query: Query | null,
+  pageSize: number,
+  project: (response: StoreQueryResponse<Query>) => Output,
+  options: StoreResourceOptions<Output> = {},
+): GraphResource<Output> {
+  const store = useGraphStore()
+  const observer = useMemo(
+    () => (query === null ? null : new StoreObserver(store, query, positivePage(pageSize))),
+    [store, query, pageSize],
+  )
+  const subscribe = useCallback(
+    (listener: () => void) => (observer === null ? () => {} : observer.subscribe(listener)),
+    [observer],
+  )
+  const idle = useMemo<ObserverSnapshot<Query>>(
+    () => Object.freeze({ snapshots: Object.freeze([]), pendingMore: false }),
+    [],
+  )
+  const getSnapshot = useCallback(() => observer?.getSnapshot() ?? idle, [observer, idle])
+  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  useEffect(() => observer?.start(), [observer])
+
+  const pollIdentity =
+    query === null ? null : `${options.identity ?? JSON.stringify(query)}\u0000${pageSize}`
+  useEffect(() => {
+    if (query === null || observer === null || options.refreshInterval === undefined) return
+    return retainRefreshScheduler(
+      store,
+      pollIdentity!,
+      () => observer.refresh(),
+      options.refreshInterval,
+      options.refreshWhen ?? 'visible',
+    )
+  }, [store, query, observer, pollIdentity, options.refreshInterval, options.refreshWhen])
+
+  const refresh = useCallback(async (): Promise<void> => observer?.refresh(), [observer])
+  const loadMore = useCallback(async (): Promise<void> => observer?.loadMore(), [observer])
+  const identity = options.identity ?? pollIdentity ?? 'idle'
+  const projected = useMemo(() => {
+    const responses: StoreQueryResponse<Query>[] = current.snapshots.flatMap((snapshot) => {
+      const response = responseOf(snapshot)
+      return response === undefined ? [] : [response]
+    })
+    if (responses.length === 0) return undefined
+    const pages = responses.map(project)
+    if ((options.window ?? 'page') === 'page') return pages[0]
+    return options.merge?.(pages) ?? mergeAppendPages(pages)
+  }, [current, project, options.window, options.merge])
+  const previousRef = useRef<{ readonly identity: string; readonly data: Output } | undefined>(
+    undefined,
+  )
+  const prior = previousRef.current
+  const previous =
+    options.keepPrevious && prior !== undefined && prior.identity !== identity ? prior : undefined
+  useEffect(() => {
+    if (projected !== undefined) previousRef.current = Object.freeze({ identity, data: projected })
+  }, [identity, projected])
+
+  return useMemo(() => {
+    const snapshots = current.snapshots
+    const state = query === null ? 'idle' : combinedState(snapshots)
+    const failed = snapshots.find((snapshot) => snapshot.state === 'failed')
+    return Object.freeze({
+      state,
+      data: projected,
+      ...(failed?.state === 'failed' ? { error: failed.error } : { error: undefined }),
+      ...(previous === undefined ? {} : { previous }),
+      transitioning: state === 'loading' || state === 'refreshing',
+      live: false as const,
+      sequence: 0 as const,
+      refresh,
+      more: Object.freeze({
+        has: observer?.hasMore() ?? false,
+        pending: current.pendingMore,
+        load: loadMore,
+      }),
+    })
+  }, [current, query, projected, previous, refresh, observer, loadMore])
+}
+
+function combinedState(snapshots: readonly StoreSnapshot[]): GraphResourceState {
+  if (snapshots.length === 0 || snapshots.some((snapshot) => snapshot.state === 'cold'))
+    return 'loading'
+  for (const state of ['failed', 'loading', 'refreshing', 'optimistic', 'stale'] as const) {
+    if (snapshots.some((snapshot) => snapshot.state === state)) return state
+  }
+  return 'ready'
+}
+
+function responseOf<Query extends QueryAST>(
+  snapshot: StoreSnapshot<Query>,
+): StoreQueryResponse<Query> | undefined {
+  return 'response' in snapshot ? snapshot.response : undefined
+}
+
+function mergeAppendPages<Output>(pages: readonly Output[]): Output {
+  const first = pages[0]
+  if (!Array.isArray(first)) return pages[pages.length - 1] as Output
+  const seen = new Set<unknown>()
+  const merged: unknown[] = []
+  for (const page of pages as readonly (readonly unknown[])[]) {
+    for (const value of page) {
+      const identity =
+        value !== null && typeof value === 'object' && 'id' in value
+          ? (value as { readonly id: unknown }).id
+          : value
+      if (seen.has(identity)) continue
+      seen.add(identity)
+      merged.push(value)
+    }
+  }
+  return Object.freeze(merged) as Output
+}
+
+export function retainRefreshScheduler(
+  store: GraphStore,
+  identity: string,
+  refresh: () => Promise<void>,
+  interval: number,
+  when: 'always' | 'visible',
+): () => void {
+  if (!Number.isSafeInteger(interval) || interval < 250) {
+    throw new TypeError('refreshInterval must be an integer of at least 250ms.')
+  }
+  let byIdentity = pollers.get(store)
+  if (byIdentity === undefined) {
+    byIdentity = new Map()
+    pollers.set(store, byIdentity)
+  }
+  let scheduler = byIdentity.get(identity)
+  if (scheduler === undefined) {
+    scheduler = { subscribers: new Map(), timer: undefined }
+    byIdentity.set(identity, scheduler)
+  }
+  const token = Symbol(identity)
+  scheduler.subscribers.set(token, { interval, when, refresh })
+  schedulePoll(scheduler)
+  if (typeof document !== 'undefined' && scheduler.onVisibility === undefined) {
+    scheduler.onVisibility = () => schedulePoll(scheduler!, true)
+    document.addEventListener('visibilitychange', scheduler.onVisibility)
+  }
+  return () => {
+    scheduler!.subscribers.delete(token)
+    if (scheduler!.subscribers.size !== 0) {
+      schedulePoll(scheduler!)
+      return
+    }
+    if (scheduler!.timer !== undefined) clearTimeout(scheduler!.timer)
+    if (typeof document !== 'undefined' && scheduler!.onVisibility !== undefined) {
+      document.removeEventListener('visibilitychange', scheduler!.onVisibility)
+    }
+    byIdentity!.delete(identity)
+    if (byIdentity!.size === 0) pollers.delete(store)
+  }
+}
+
+function schedulePoll(scheduler: PollScheduler, immediate = false): void {
+  if (scheduler.timer !== undefined) clearTimeout(scheduler.timer)
+  const subscribers = [...scheduler.subscribers.values()]
+  if (subscribers.length === 0) return
+  const interval = Math.min(...subscribers.map((subscriber) => subscriber.interval))
+  scheduler.timer = setTimeout(
+    () => {
+      scheduler.timer = undefined
+      const visible = typeof document === 'undefined' || document.visibilityState !== 'hidden'
+      const eligible = [...scheduler.subscribers.values()].filter(
+        (subscriber) => subscriber.when === 'always' || visible,
+      )
+      eligible.forEach((subscriber) => void subscriber.refresh().catch(() => {}))
+      schedulePoll(scheduler)
+    },
+    immediate ? 0 : interval,
+  )
+}
+
+function positivePage(input: number): number {
+  if (!Number.isSafeInteger(input) || input < 1) {
+    throw new TypeError('Graph resource page size must be a positive safe integer.')
+  }
+  return input
+}

package/src/graph/store.ts

@@ -0,0 +1,97 @@
+import type { GraphApi } from '@astrale-os/kernel-client/graph'
+import type { GraphStore as GraphStoreValue } from '@astrale-os/kernel-client/store'
+import type { Shell } from '@astrale-os/shell'
+
+import { GraphStore } from '@astrale-os/kernel-client/store'
+import { useContext } from 'react'
+
+import { GraphContext } from './graph.context.js'
+
+interface StoreEntry {
+  readonly shell: Shell
+  readonly graph: GraphApi
+  readonly scope: string
+  readonly store: GraphStoreValue
+  readonly owned: boolean
+  retained: number
+  generation: number
+}
+
+const entries = new WeakMap<Shell, StoreEntry>()
+
+/** Authority/schema identity. Session ids and Publication ETags are deliberately absent. */
+export interface GraphStoreScope {
+  readonly authority: string
+  readonly schemaRevision: string
+}
+
+type StoreIdentity = Awaited<ReturnType<Shell['kernel']['auth']['whoami']>>
+
+export async function resolveGraphStoreScope(
+  shell: Shell,
+  knownIdentity?: StoreIdentity | null,
+): Promise<GraphStoreScope> {
+  const [identity, snapshot] = await Promise.all([
+    knownIdentity === undefined
+      ? shell.kernel.auth.whoami().catch(() => null)
+      : Promise.resolve(knownIdentity),
+    shell.kernel.snapshot(),
+  ])
+  return Object.freeze({
+    authority:
+      identity === null
+        ? 'anonymous'
+        : `${identity.issuer}\u0000${identity.subject}\u0000${identity.id}`,
+    schemaRevision: snapshot.publication.schema.revision,
+  })
+}
+
+export function storeFor(shell: Shell, scope: GraphStoreScope): StoreEntry {
+  const current = entries.get(shell)
+  const scopeKey = `${scope.authority}\u0000${scope.schemaRevision}`
+  if (current !== undefined && current.graph === shell.kernel.graph && current.scope === scopeKey) {
+    return current
+  }
+  const supplied = shell.kernel.store
+  const created: StoreEntry = {
+    shell,
+    graph: shell.kernel.graph,
+    scope: scopeKey,
+    // A supplied Store is trusted only for the KernelClient's first declared scope. A later
+    // authority/revision/GraphApi replacement gets a new Store and cannot inherit old memory.
+    store:
+      current === undefined && supplied !== undefined
+        ? supplied
+        : new GraphStore({ graph: shell.kernel.graph }),
+    owned: current !== undefined || supplied === undefined,
+    retained: 0,
+    generation: 0,
+  }
+  entries.set(shell, created)
+  if (current !== undefined && current.retained === 0 && current.owned) current.store.close()
+  return created
+}
+
+export function retainStore(entry: StoreEntry): () => void {
+  entry.generation += 1
+  entry.retained += 1
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    entry.retained -= 1
+    const generation = ++entry.generation
+    queueMicrotask(() => {
+      if (entry.retained !== 0 || entry.generation !== generation || !entry.owned) return
+      if (entries.get(entry.shell) === entry) entries.delete(entry.shell)
+      entry.store.close()
+    })
+  }
+}
+
+/** The exact caller/schema-scoped GraphStore for the current View subtree. */
+export function useGraphStore(): GraphStoreValue {
+  const store = useContext(GraphContext)
+  if (store === null) throw new Error('useGraphStore must be used within a <ShellProvider>')
+  return store
+}

package/src/host/actions.hook.ts

@@ -0,0 +1,165 @@
+import type {
+  AccessRequest,
+  AccessResult,
+  ExternalOpenRequest,
+  ExternalOpenResult,
+  HostCapabilities,
+  ModalRequest,
+  ModalResult,
+  NotificationRequest,
+  NotificationResult,
+  OpenViewRequest,
+  OpenViewResult,
+} from '@astrale-os/shell'
+
+import { useMemo } from 'react'
+
+import { useSendIntent } from '../intents/send-intent.hook.js'
+import { useShell } from '../session/shell.hook.js'
+
+export function useHostCapabilities(): HostCapabilities {
+  return useShell().hostCapabilities
+}
+
+export class HostCapabilityUnavailableError extends Error {
+  readonly code = 'SHELL_REACT_HOST_CAPABILITY_UNAVAILABLE' as const
+  constructor(readonly capability: string) {
+    super(`Host capability '${capability}' is unavailable.`)
+    this.name = 'HostCapabilityUnavailableError'
+  }
+}
+
+export interface HostDialogApi {
+  readonly supported: boolean
+  open(request: ModalRequest): Promise<ModalResult>
+  confirm(request: Omit<ModalRequest, 'nested'>): Promise<boolean>
+}
+
+export function useHostDialog(): HostDialogApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(
+    () => ({
+      supported: capabilities.actions.modal !== undefined,
+      open: (request: ModalRequest) => {
+        if (capabilities.actions.modal === undefined) return unsupported('actions.modal')
+        portable(request)
+        return send('actions.modal', request)
+      },
+      confirm: async (request: Omit<ModalRequest, 'nested'>) => {
+        if (capabilities.actions.modal === undefined) return unsupported('actions.modal')
+        portable(request)
+        return (await send('actions.modal', request)).outcome === 'confirmed'
+      },
+    }),
+    [capabilities, send],
+  )
+}
+
+export interface NotifyApi {
+  (request: NotificationRequest): Promise<NotificationResult>
+  readonly supported: boolean
+}
+
+export function useNotify(): NotifyApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const notify = ((request: NotificationRequest) => {
+      if (capabilities.actions.notify === undefined) return unsupported('actions.notify')
+      portable(request)
+      return send('actions.notify', request)
+    }) as NotifyApi
+    Object.defineProperty(notify, 'supported', {
+      enumerable: true,
+      value: capabilities.actions.notify !== undefined,
+    })
+    return notify
+  }, [capabilities, send])
+}
+
+export interface OpenViewApi {
+  (request: OpenViewRequest): Promise<OpenViewResult>
+  readonly supported: boolean
+}
+
+export function useOpenView(): OpenViewApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const open = ((request: OpenViewRequest) => {
+      if (capabilities.navigation.openView === undefined) return unsupported('view.open')
+      portable(request)
+      return send('view.open', request)
+    }) as OpenViewApi
+    Object.defineProperty(open, 'supported', {
+      enumerable: true,
+      value: capabilities.navigation.openView !== undefined,
+    })
+    return open
+  }, [capabilities, send])
+}
+
+export interface ExternalOpenApi {
+  (request: ExternalOpenRequest): Promise<ExternalOpenResult>
+  readonly supported: boolean
+}
+
+export function useExternalOpen(): ExternalOpenApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const open = ((request: ExternalOpenRequest) => {
+      if (capabilities.navigation.external === undefined) return unsupported('browser.openExternal')
+      portable(request)
+      return send('browser.openExternal', request)
+    }) as ExternalOpenApi
+    Object.defineProperty(open, 'supported', {
+      enumerable: true,
+      value: capabilities.navigation.external !== undefined,
+    })
+    return open
+  }, [capabilities, send])
+}
+
+export interface RequestAccessApi {
+  (request: AccessRequest): Promise<AccessResult>
+  readonly supported: boolean
+}
+
+export function useRequestAccess(): RequestAccessApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const request = ((input: AccessRequest) => {
+      if (capabilities.access.request === undefined) return unsupported('access.request')
+      portable(input)
+      return send('access.request', input)
+    }) as RequestAccessApi
+    Object.defineProperty(request, 'supported', {
+      enumerable: true,
+      value: capabilities.access.request !== undefined,
+    })
+    return request
+  }, [capabilities, send])
+}
+
+function unsupported<Result>(capability: string): Promise<Result> {
+  return Promise.reject(new HostCapabilityUnavailableError(capability))
+}
+
+function portable(input: unknown): void {
+  const seen = new WeakSet<object>()
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+    if (typeof value === 'number' && Number.isFinite(value)) return
+    if (typeof value !== 'object' || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+      throw new TypeError('Host action payload must be serializable data.')
+    }
+    if (seen.has(value)) throw new TypeError('Host action payload cannot contain cycles.')
+    seen.add(value)
+    if (Array.isArray(value)) value.forEach(visit)
+    else Object.values(value).forEach(visit)
+  }
+  visit(input)
+}

package/src/host/components.tsx

@@ -0,0 +1,29 @@
+import type { ReactElement, ReactNode } from 'react'
+
+import type { HostDialogApi, NotifyApi, OpenViewApi, RequestAccessApi } from './actions.hook.js'
+
+import { useHostDialog, useNotify, useOpenView, useRequestAccess } from './actions.hook.js'
+
+export function HostDialog(props: {
+  readonly children: (dialog: HostDialogApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useHostDialog())}</>
+}
+
+export function Notify(props: {
+  readonly children: (notify: NotifyApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useNotify())}</>
+}
+
+export function NestedView(props: {
+  readonly children: (open: OpenViewApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useOpenView())}</>
+}
+
+export function RequestAccess(props: {
+  readonly children: (request: RequestAccessApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useRequestAccess())}</>
+}

package/src/host/index.ts

@@ -0,0 +1,17 @@
+export {
+  useExternalOpen,
+  useHostCapabilities,
+  useHostDialog,
+  useNotify,
+  useOpenView,
+  useRequestAccess,
+} from './actions.hook.js'
+export type {
+  ExternalOpenApi,
+  HostDialogApi,
+  NotifyApi,
+  OpenViewApi,
+  RequestAccessApi,
+} from './actions.hook.js'
+export { HostDialog, NestedView, Notify, RequestAccess } from './components.js'
+export { HostCapabilityUnavailableError } from './actions.hook.js'