@owlmeans/client 0.1.18-rc.2 → 0.1.18-rc.21

package/src/navigate.ts

@@ -1,6 +1,5 @@
 import { useMemo } from 'react'
 import type { Navigator } from './types.js'
-import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import { useContext } from './context.js'
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 
@@ -12,28 +11,26 @@ export const useNavigate = (): Navigator => {
     const navigator: Navigator = {
       _navigate: navigate,
       
-      navigate: async (module, request) => {
-        const [url, ok] = await module.call(request)
-
-        if (ok === EntrypointOutcome.Ok) {
-          if (url.startsWith('http')) {
-            globalThis.location.href = url
-          } else {
-            navigate(url, {
-              state: {
-                ...module.route.route, silent: request?.silent
-              },
-              replace: request?.replace ?? false
-            })
-          }
+      navigate: async (entrypoint, request) => {
+        const url = await entrypoint.url(request)
+
+        if (url.startsWith('http')) {
+          globalThis.location.href = url
+        } else {
+          navigate(url, {
+            state: {
+              ...entrypoint.route.route, silent: request?.silent
+            },
+            replace: request?.replace ?? false
+          })
         }
       },
 
-      go: async (alias, request) =>
-        navigator.navigate(context.entrypoint<ClientEntrypoint<string>>(alias), request),
+      go: async (target, request) =>
+        navigator.navigate(context.entrypoint<ClientEntrypoint<string>>(target), request),
 
-      press: (alias, request) => () => {
-        void navigator.go(alias, request)
+      press: (target, request) => () => {
+        void navigator.go(target, request)
       },
 
       back: async () => {

package/src/router.ts

@@ -1,18 +1,25 @@
 import type { FC } from 'react'
 import type { RouterModel, RouterProps, RouterProvider } from './types.js'
 import { createElement, useEffect, useRef, useState } from 'react'
-import { buildModuleTree, initializeRouter, visitModuleTree } from './utils/router.js'
+import { buildEntrypointTree, initializeRouter, visitEntrypointTree } from './utils/router.js'
 import { createRouteRenderer } from './utils/route.js'
 import { useContext } from './context.js'
 import type { ClientConfig } from '@owlmeans/client-context'
 import type { ClientContext } from './types.js'
 import { assertContext } from '@owlmeans/context'
-import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import type { LibraryRouter, RouteObject } from '@owlmeans/router'
 
 type Config = ClientConfig
 interface Context<C extends Config = Config> extends ClientContext<C> { }
 
+/** A child path that keeps its leading separator reads as absolute, and the router rejects it. */
+const relative = (segment: string): string => {
+  segment = segment.trim()
+  segment = segment.endsWith('/') ? segment.slice(0, -1) : segment
+
+  return segment.startsWith('/') ? segment.substring(1) : segment
+}
+
 export const Router: FC<RouterProps> = ({ provide }) => {
   const progress = useRef(false)
   const context = useContext()
@@ -55,21 +62,18 @@ export const makeRouterModel = (): RouterModel => {
     routes: [],
     resolve: async (ctx) => {
       const context = assertContext<Config, Context>(ctx as Context, location)
-      const moduleTree = buildModuleTree(context as Context)
-
-      const reactRoutes: RouteObject[] = await visitModuleTree(moduleTree, async (module, children) => {
-        const ctx = assertContext<BasicConfig, BasicContext<BasicConfig>>(
-          (module.ctx ?? context) as BasicContext<BasicConfig>, location
-        )
-        await module.route.resolve(ctx)
+      const entrypointTree = buildEntrypointTree(context as Context)
 
+      const reactRoutes: RouteObject[] = await visitEntrypointTree(entrypointTree, async (module, children) => {
         const renderer = module.handle != null
           ? { Component: createRouteRenderer({ context, module, hasChildren: children.length > 0 }) }
           : undefined
 
+        // The React tree nests, so each node contributes only its OWN segment — its ancestors are
+        // the branches it hangs under and already carry theirs.
         const route: RouteObject = {
           ...(module.route.route.default ? { index: true } as any : undefined),
-          ...(!module.route.route.default ? { path: module.getPath(true), children } : undefined),
+          ...(!module.route.route.default ? { path: relative(module.segment()), children } : undefined),
           ...renderer
         }
 

package/src/services/debug.ts

@@ -62,13 +62,13 @@ export const createDebugService = (alias: string = DEF_DEBUG_ALIAS): DebugServic
   }, service => async () => {
     service.initialized = true
     const context = assertContext(service.ctx, location) as ClientContext
-    const record = await context.getConfigResource().load<DebugConfigRecord>(DEBUG_CONFIG_KEY)
+    const record = await context.getConfigResource<DebugConfigRecord>().load(DEBUG_CONFIG_KEY)
     if (record?.states != null) {
       service.addItem({
         alias: 'reset-states',
         title: `Reset states`,
         action: async (modal, context) => {
-          const record = await context.getConfigResource().load<DebugConfigRecord>(DEBUG_CONFIG_KEY)
+          const record = await context.getConfigResource<DebugConfigRecord>().load(DEBUG_CONFIG_KEY)
           if (record?.states != null) {
             await service.erase(record.states)
             context.rerender()

package/src/store.ts

@@ -1,68 +1,85 @@
-import { useEffect, useId, useMemo, useState } from 'react'
-import type { StateModel, UseStoreHelper, UseStoreHelperOptions, UseStoreListHelper } from '@owlmeans/state'
-import { useContext } from './context.js'
+import { useMemo, useSyncExternalStore } from 'react'
 import type { ResourceRecord } from '@owlmeans/resource'
+import type { StateModel } from '@owlmeans/state'
+import { useContext } from './context.js'
+import type { UseStoreListOptions } from './types.js'
 
-export const useStoreModel: UseStoreHelper = (id, opts) => {
-  const list = useStoreList(id, opts)
+/**
+ * Turn one state subscription into the pair `useSyncExternalStore` wants.
+ *
+ * The value is cached rather than rebuilt per render: the hook is asked for a snapshot on every
+ * render and must answer with the same reference until something actually changed, or React
+ * re-renders forever. A state subscription hands its value over synchronously, so the first
+ * snapshot is taken by subscribing and unsubscribing again — no render ever runs without one,
+ * and no subscription outlives the call.
+ */
+const bind = <V>(subscribe: (listener: (value: V) => void) => () => void) => {
+  let current: V | undefined
+  let seeded = false
 
-  if (list.length < 1) {
-    throw new SyntaxError('Store always return model and create it if not exists')
+  const capture = (notify?: () => void) => (value: V) => {
+    current = value
+    seeded = true
+    notify?.()
   }
 
-  return list[0]
-}
+  return {
+    subscribe: (notify: () => void) => subscribe(capture(notify)),
+    snapshot: (): V => {
+      if (!seeded) {
+        subscribe(capture())()
+      }
 
-export const useStoreList: UseStoreListHelper = (ids, opts) => {
-  if (typeof ids === 'object' && !Array.isArray(ids)) {
-    opts = ids
-  }
-  const params: UseStoreHelperOptions<ResourceRecord> = typeof opts === 'object' ? opts : {}
-  if (typeof ids === 'string' || Array.isArray(ids)) {
-    params.id = ids
-  }
-  if (typeof opts === 'string') {
-    params.resource = opts
-  } else if (typeof opts === 'boolean') {
-    params.listen = opts
+      return current as V
+    }
   }
-  params.listen = params.listen ?? true
+}
 
+/**
+ * One record from a state resource, live.
+ *
+ * It never throws for missing data: an id the store knows nothing about yields a model whose
+ * `empty` is true — reading `record` gives the resource's configured default, and nothing is
+ * written into the store on the way. An ABSENT id is the same answer rather than an error, since
+ * a screen renders before the record that supplies the id has arrived; on a `single` resource an
+ * absent id addresses its sole record. Writing through an empty model with no id is refused.
+ */
+export const useStoreModel = <T extends ResourceRecord = ResourceRecord>(
+  id?: string, alias?: string
+): StateModel<T> => {
   const context = useContext()
-  const resource = useMemo(() => context.getStateResource(params.resource), [params.resource])
+  const resource = useMemo(() => context.getStateResource<T>(alias), [context, alias])
+  const store = useMemo(
+    () => bind<StateModel<T>>(listener => resource.watch(id, listener)),
+    [resource, id]
+  )
 
-  const deps = [
-    Array.isArray(params.id) ? params.id.join(',') : params.id,
-    params.query == null,
-    JSON.stringify(params.default),
-    params.listen
-  ]
-
-  const id = useId()
-  const [models, setModels] = useState<StateModel<ResourceRecord>[]>([])
-
-  let _return = [...models]
-
-  const unsubscribe = useMemo(() => {
-    const [unsubscribe, _initialModels] = resource.subscribe({
-      _systemId: id,
-      id: params.id,
-      listener: models => {
-        params.listen && setModels(models)
-      },
-      default: params.default,
-      query: params.query,
-    })
-    setModels(_initialModels)
-
-    if (_return.length < 1) {
-      _return.push(..._initialModels)
-    }
+  return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot)
+}
 
-    return unsubscribe
-  }, deps)
+/**
+ * A live LIST from a state resource: every record the query accepts, re-evaluated on every write
+ * that changes the answer, so a screen never recomputes ids and never re-subscribes to keep up.
+ * Omitting `query` matches everything.
+ */
+export const useStoreList = <T extends ResourceRecord = ResourceRecord>(
+  opts?: UseStoreListOptions<T>
+): StateModel<T>[] => {
+  const context = useContext()
+  const resource = useMemo(() => context.getStateResource<T>(opts?.resource), [context, opts?.resource])
 
-  useEffect(() => unsubscribe, deps)
+  /**
+   * The subscription is keyed on the query's CONTENT, not on whether one was given: a screen
+   * that narrows its filter has to re-subscribe, and keyed on identity it kept answering the
+   * first filter it ever saw with nothing to say the list had gone stale.
+   */
+  const key = JSON.stringify([opts?.query ?? null, opts?.sort ?? null])
+  const store = useMemo(
+    () => bind<StateModel<T>[]>(
+      listener => resource.query(opts?.query, listener, { sort: opts?.sort })
+    ),
+    [resource, key]
+  )
 
-  return _return as StateModel<any>[]
+  return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot)
 }

package/src/types.ts

@@ -1,11 +1,12 @@
 import type { PropsWithChildren, FC, DependencyList } from 'react'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
 import type { ClientConfig, ClientContext as BasicClientContext } from '@owlmeans/client-context'
+import type { Criteria, ResourceRecord, Sort } from '@owlmeans/resource'
 import type { StateResourceAppend } from '@owlmeans/state'
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import type { DebugServiceAppend, ModalServiceAppend } from './components/types.js'
 import type { ConfigResourceAppend } from '@owlmeans/config'
-import type { ConfigRecord } from '@owlmeans/context'
+import type { ConfigRecord, EntrypointReference } from '@owlmeans/context'
 import type { NavigateFunction, RouterService, Location, RouteObject, LibraryRouter } from '@owlmeans/router'
 
 
@@ -35,10 +36,10 @@ export interface AppProps extends PropsWithChildren {
   noRouter?: boolean
 }
 
-export interface RoutedComponent<ExtraProps = {}> extends FC<PropsWithChildren<ModuleContextParams & ExtraProps>> {
+export interface RoutedComponent<ExtraProps = {}> extends FC<PropsWithChildren<EntrypointContextParams & ExtraProps>> {
 }
 
-export interface ModuleContextParams<T extends {} = {}> {
+export interface EntrypointContextParams<T extends {} = {}> {
   alias: string
   params: AbstractRequest<T>['params']
   path: string
@@ -61,13 +62,16 @@ export interface NavRequest<T extends Record<string, any> = Record<string, any>>
   silent?: boolean
 }
 
+/** A navigation target is a protocol reference in application code, with strings retained for adapters. */
+export type EntrypointTarget = EntrypointReference | string
+
 export interface Navigator {
   _navigate: NavigateFunction
   navigate: <R extends NavRequest = NavRequest>(module: ClientEntrypoint<string, AbstractRequest>, request?: R) => Promise<void>
-  go: <R extends NavRequest = NavRequest>(alias: string, request?: R) => Promise<void>
+  go: <R extends NavRequest = NavRequest>(target: EntrypointTarget, request?: R) => Promise<void>
   back: () => Promise<void>
   pressBack: () => () => void
-  press: <R extends NavRequest = NavRequest>(alias: string, request?: R) => () => void
+  press: <R extends NavRequest = NavRequest>(target: EntrypointTarget, request?: R) => () => void
   location: <R extends NavRequest = NavRequest>() => Location<R>
 }
 
@@ -79,3 +83,12 @@ export interface UseValueParams<T> {
   default?: T
   deps?: DependencyList
 }
+
+/** What `useStoreList` subscribes to. Every field is optional; nothing at all means everything. */
+export interface UseStoreListOptions<T extends ResourceRecord = ResourceRecord> {
+  /** The live query. Omitted or `{}` matches every record the resource holds. */
+  query?: Criteria<T>
+  sort?: Sort<T>[]
+  /** Which state resource to read; the context's default one when omitted. */
+  resource?: string
+}

package/src/utils/{module.ts → entrypoint.ts}

@@ -1,12 +1,12 @@
 
 import { createContext } from 'react'
-import type { ModuleContextParams, ClientContext } from '../types.js'
+import type { EntrypointContextParams, ClientContext } from '../types.js'
 import type { ClientConfig } from '@owlmeans/client-context'
 
 type Config = ClientConfig
 interface Context<C extends Config = Config> extends ClientContext<C> { }
 
-export const ModuleContext = createContext<ModuleContextParams>({
+export const EntrypointContext = createContext<EntrypointContextParams>({
   alias: '',
   params: {},
   path: '',

package/src/utils/index.ts

@@ -1,4 +1,4 @@
 
 export * from './router.js'
 export * from './route.js'
-export * from './module.js'
+export * from './entrypoint.js'

package/src/utils/route.tsx

@@ -1,5 +1,5 @@
 import type { FC, PropsWithChildren, ReactElement } from 'react'
-import type { ModuleContextParams, RoutedComponent, ClientContext } from '../types.js'
+import type { EntrypointContextParams, RoutedComponent, ClientContext } from '../types.js'
 import { isValidElement, memo, useEffect } from 'react'
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import { provideRequest } from '@owlmeans/client-entrypoint'
@@ -15,10 +15,17 @@ export const createRouteRenderer: (params: RendererParams) => FC = ({ context, m
   const params = context.router().useParams()
   const reply = provideResponse()
 
+  // Own guards plus every ancestor's — the same set the request would be judged by. Whether a
+  // screen is guarded is a question about THIS list being non-empty, never about the declaration
+  // carrying a `guards` property: binding always assigns the array, empty when nothing was
+  // declared, and an empty list means an open screen. Asking the wrong question refuses every
+  // guest screen with `frontend-guard`, since no guard can match when there are none.
+  const aliases = module.getGuards()
+
   useEffect(() => {
-    if (module.guards != null) {
-      const guards = module.getGuards().map(guard => context.service<GuardService>(guard))
-      const request = provideRequest(module.alias, module.getPath())
+    if (aliases.length > 0) {
+      const guards = aliases.map(guard => context.service<GuardService>(guard))
+      const request = provideRequest(module.alias, module.path())
       const reply = provideResponse()
       let canceled = false
       Promise.all(guards.map(async guard => {
@@ -38,10 +45,10 @@ export const createRouteRenderer: (params: RendererParams) => FC = ({ context, m
       })
       return () => { canceled = true }
     }
-  }, module.guards ?? [])
+  }, aliases)
 
   let Renderer: HandledRenderer<{}> = module.handle?.({
-    alias: module.alias, path: module.getPath(),
+    alias: module.alias, path: module.path(),
     params, body: {}, headers: {}, query: {},
   }, reply) as HandledRenderer<{}>
 
@@ -55,8 +62,8 @@ export const createRouteRenderer: (params: RendererParams) => FC = ({ context, m
   const Outlet = context.router().outlet()
   if (isComponent(Renderer)) {
     const EnsuredRenderer = memo(Renderer) as RoutedComponent
-    const props: ModuleContextParams = {
-      context, params, alias: module.getAlias(), path: module.getPath()
+    const props: EntrypointContextParams = {
+      context, params, alias: module.alias, path: module.path()
     }
     if (hasChildren) {
       return <EnsuredRenderer {...props}><Outlet /></EnsuredRenderer>

package/src/utils/router.ts

@@ -7,8 +7,8 @@ import type { ClientContext } from '../types.js'
 type Config = ClientConfig
 interface Context<C extends Config = Config> extends ClientContext<C> { }
 
-export const buildModuleTree = <R, C extends Config = Config, T extends Context<C> = Context<C>>(context: T): ModuleTree<R> => {
-  const modules = context.entrypoints<ClientEntrypoint<R>>().filter(
+export const buildEntrypointTree = <R, C extends Config = Config, T extends Context<C> = Context<C>>(context: T): EntrypointTree<R> => {
+  const entrypoints = context.entrypoints<ClientEntrypoint<R>>().filter(
     module => module.route.route.type === AppType.Frontend
       && (module.sticky || module.route.route.service == null
         || module.route.route.service === context.cfg.service)
@@ -17,8 +17,8 @@ export const buildModuleTree = <R, C extends Config = Config, T extends Context<
   const flatTree = new Map<ClientEntrypoint<R>, ClientEntrypoint<R>[]>()
   const roots: ClientEntrypoint<R>[] = []
 
-  modules.forEach(module => {
-    const parentAlias = module.getParentAlias()
+  entrypoints.forEach(module => {
+    const parentAlias = module.route.route.parent
     if (parentAlias == null) {
       roots.push(module)
     } else {
@@ -29,18 +29,18 @@ export const buildModuleTree = <R, C extends Config = Config, T extends Context<
     }
   })
 
-  const reduceModules = (modules: ClientEntrypoint<R>[]): ModuleTree<R> => modules.reduce(
-    (tree, module) => tree.set(module, reduceModules(flatTree.get(module) ?? [])), new Map()
+  const reduceEntrypoints = (entrypoints: ClientEntrypoint<R>[]): EntrypointTree<R> => entrypoints.reduce(
+    (tree, module) => tree.set(module, reduceEntrypoints(flatTree.get(module) ?? [])), new Map()
   )
 
-  return reduceModules(roots)
+  return reduceEntrypoints(roots)
 }
 
-export const visitModuleTree = async <T, R>(tree: ModuleTree<T>, visitor: ModuleTreeVisitor<T, R>): Promise<R[]> =>
+export const visitEntrypointTree = async <T, R>(tree: EntrypointTree<T>, visitor: EntrypointTreeVisitor<T, R>): Promise<R[]> =>
   Array.from(tree.entries()).reduce<Promise<R[]>>(
     async (result, [module, tree], _, source) => [
       ...(await result),
-      await visitor(module, await visitModuleTree(tree, visitor), source.length === 1)
+      await visitor(module, await visitEntrypointTree(tree, visitor), source.length === 1)
     ], Promise.resolve([]))
 
 export const initializeRouter = async (context: Context) => {
@@ -52,9 +52,9 @@ export const initializeRouter = async (context: Context) => {
   return await model.resolve(context)
 }
 
-export interface ModuleTreeVisitor<T, R> {
+export interface EntrypointTreeVisitor<T, R> {
   (module: ClientEntrypoint<T>, children: R[], alone: boolean): Promise<R>
 }
 
-interface ModuleTree<T> extends Map<ClientEntrypoint<T>, ModuleTree<T>> {
+interface EntrypointTree<T> extends Map<ClientEntrypoint<T>, EntrypointTree<T>> {
 }

package/build/module.d.ts

@@ -1,3 +0,0 @@
-import type { ModuleContextParams } from './types.js';
-export declare const useModule: <T extends {} = {}>() => ModuleContextParams<T>;
-//# sourceMappingURL=module.d.ts.map

package/build/module.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,EAAE,GAAG,EAAE,OAAoC,mBAAmB,CAAC,CAAC,CAAC,CAAA"}

package/build/module.js

@@ -1,4 +0,0 @@
-import { useContext } from 'react';
-import { ModuleContext } from './utils/index.js';
-export const useModule = () => useContext(ModuleContext);
-//# sourceMappingURL=module.js.map

package/build/module.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGhD,MAAM,CAAC,MAAM,SAAS,GAAG,GAAsB,EAAE,CAAC,UAAU,CAAC,aAAa,CAA2B,CAAA"}

package/build/utils/module.d.ts

@@ -1,3 +0,0 @@
-import type { ModuleContextParams } from '../types.js';
-export declare const ModuleContext: import("react").Context<ModuleContextParams<{}>>;
-//# sourceMappingURL=module.d.ts.map

package/build/utils/module.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/utils/module.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,aAAa,CAAA;AAMrE,eAAO,MAAM,aAAa,kDAKxB,CAAA"}

package/build/utils/module.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/utils/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAOrC,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAsB;IAC9D,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE;IACV,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAa;CACvB,CAAC,CAAA"}

package/src/module.ts

@@ -1,6 +0,0 @@
-
-import { useContext } from 'react'
-import { ModuleContext } from './utils/index.js'
-import type { ModuleContextParams } from './types.js'
-
-export const useModule = <T extends {} = {}>() => useContext(ModuleContext) as ModuleContextParams<T>