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

package/src/navigation/hooks/scope.hook.ts

@@ -9,8 +9,8 @@ import type { NavSnapshot } from '../history.js'
 import type { NavLocation } from '../location.js'
 import type { Navigate } from '../scope.context.js'
 
-import { buildLocation, useSettled } from '../location.js'
-import { useNavCtx, useMemoryShape } from '../scope.context.js'
+import { buildLocation } from '../location.js'
+import { useGraphPoint, useNavCtx } from '../scope.context.js'
 import { useNavigateHandle } from './navigate.hook.js'
 
 /** The nearest scope, for chrome/persistence (API §8.2). */
@@ -25,10 +25,8 @@ export function useNavScope(): NavScopeHandle {
   const ctx = useNavCtx()
   const navigate = useNavigateHandle(ctx)
   const entry = ctx.history.current
-  const shape = entry?.node ?? null
-  const result = useMemoryShape(ctx.memory, shape)
-  const settled = useSettled(result, shape)
-  const location = useMemo(() => buildLocation(entry, result, settled), [entry, result, settled])
+  const result = useGraphPoint(entry?.node ?? null)
+  const location = useMemo(() => buildLocation(entry, result), [entry, result])
   const snapshot = useCallback(() => ctx.history.snapshot(), [ctx.history])
   return { location, snapshot, navigate }
 }

package/src/navigation/index.ts

@@ -7,8 +7,24 @@ export { useNavigate } from './hooks/navigate.hook.js'
 export { useAncestors } from './hooks/ancestors.hook.js'
 export { useNavScope } from './hooks/scope.hook.js'
 export type { NavScopeHandle } from './hooks/scope.hook.js'
-export { Link } from './link.js'
-export type { LinkProps } from './link.js'
+export { Link, NodeLink, ViewLink } from './link.js'
+export type { LinkProps, NodeLinkProps, ViewLinkProps } from './link.js'
+export {
+  NavigationScope,
+  defineNavigation,
+  enumParam,
+  location,
+  pathParam,
+  useNavigation,
+} from './codec.js'
+export type {
+  LocationDefinition,
+  NavigationDefinition,
+  NavigationParam,
+  NavigationParams,
+  NavigationRoutes,
+  NavigationTarget,
+} from './codec.js'
 export { memoryAdapter } from './adapters/memory.adapter.js'
 export { urlAdapter } from './adapters/url.adapter.js'
 export type { NavAdapter } from './adapters/adapter.js'

package/src/navigation/link.tsx

@@ -8,6 +8,7 @@ import type {
   ReactNode,
 } from 'react'
 
+import { Query } from '@astrale-os/sdk/query'
 /**
  * Link (API §8.2) — navigates the nearest scope. Renders `<a href>` when the
  * scope's adapter exposes a URL form (cmd/ctrl/middle-click then falls through
@@ -16,6 +17,7 @@ import type {
  */
 import { useCallback, useEffect } from 'react'
 
+import type { NavigationDefinition, NavigationTarget } from './codec.js'
 import type { NavTarget } from './snapshot.js'
 
 import { useNavCtx } from './scope.context.js'
@@ -48,8 +50,9 @@ export function Link(props: LinkProps): ReactElement {
   const nodeRef = target.node
 
   const preload = useCallback(() => {
-    void ctx.memory?.preload(nodeRef)
-  }, [ctx.memory, nodeRef])
+    const query = Query.from({ kind: 'node', paths: [nodeRef] }).select({ kind: 'graph' })
+    void ctx.store.preload(query, { page: { size: 1 } }).catch(() => {})
+  }, [ctx.store, nodeRef])
 
   useEffect(() => {
     if (prefetch === 'render') preload()
@@ -108,3 +111,25 @@ export function Link(props: LinkProps): ReactElement {
     </a>
   )
 }
+
+export type ViewLinkProps<Definition extends NavigationDefinition> = Omit<LinkProps, 'to'> & {
+  readonly navigation: Definition
+  readonly to: NavigationTarget<Definition>
+}
+
+/** Codec-admitted link for one declared View location. */
+export function ViewLink<Definition extends NavigationDefinition>(
+  props: ViewLinkProps<Definition>,
+): ReactElement {
+  const { navigation, to, ...link } = props
+  return <Link {...link} to={navigation.encode(to)} />
+}
+
+export type NodeLinkProps = Omit<LinkProps, 'to'> & {
+  readonly to: Extract<NavTarget, string | object>
+}
+
+/** Canonical node-only link; use ViewLink when a View/params contract exists. */
+export function NodeLink(props: NodeLinkProps): ReactElement {
+  return <Link {...props} />
+}

package/src/navigation/location.ts

@@ -1,122 +1,55 @@
-import type { LiveResult } from '@astrale-os/kernel-client/store'
+import type { Node, NodeId } from '@astrale-os/sdk/graph/node'
+import type { NodePath } from '@astrale-os/sdk/graph/path'
+import type { Key } from '@astrale-os/sdk/schema'
 
-import { rawOf } from '@astrale-os/kernel-client/graph'
-/**
- * NavLocation projection (API §8.1) — the live, id-anchored location a scope
- * points at (live path, missing flag), its `buildLocation` assembly, the
- * `useSettled` guard against a one-render false-empty, and the framework-free
- * path math (parent/chain) the scope and hooks share.
- */
-import { useEffect, useRef } from 'react'
+import { Path } from '@astrale-os/sdk/graph/path'
 
+import type { ReadState } from '../graph/memory/read/envelope.js'
 import type { SerializedLocation } from './history.js'
 
-/**
- * The rich graph `Node`, derived from the memory's read envelope — kernel-client
- * does not re-export `Node` at its root yet (API §14 G8), so shell-react reads it
- * off `LiveResult` rather than taking a direct kernel-core dependency.
- */
-export type Node = NonNullable<LiveResult['node']>
-export type NodeId = Node['id']
+export interface PointResult extends ReadState {
+  readonly node: Node | null
+}
 
-/** The live, id-anchored location a scope currently points at (API §8.1). */
+/** One canonical location and its current caller-visible point projection. */
 export interface NavLocation {
-  /** The anchor — survives rename/move. */
-  readonly id: NodeId
-  /** LIVE projection of the node's current path (empty until first resolve). */
-  readonly path: string
-  /** Live memory node — null while cold, or after the anchor stops resolving. */
+  readonly target: NodePath | null
+  readonly id: NodeId | null
   readonly node: Node | null
-  /** View function ref rendering it, when one is open. */
-  readonly view?: string
+  readonly view?: Key.View
   readonly params: Readonly<Record<string, string>>
-  /** The anchor no longer resolves (deleted / masked). */
   readonly missing: boolean
 }
 
 const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({})
 
-/** The idle location a scope with no current entry projects (inert / boot). */
-export const IDLE_LOCATION: NavLocation = {
-  id: '' as NodeId,
-  path: '',
+export const IDLE_LOCATION: NavLocation = Object.freeze({
+  target: null,
+  id: null,
   node: null,
   params: EMPTY_PARAMS,
   missing: false,
-}
+})
 
-/** Project a serialized entry + its live read into the public {@link NavLocation}. */
 export function buildLocation(
   entry: SerializedLocation | null,
-  result: LiveResult | null,
-  settled: boolean,
+  result: PointResult | null,
 ): NavLocation {
   if (entry === null) return IDLE_LOCATION
   const node = result?.node ?? null
   return {
-    id: (node?.id ?? idHint(entry.node)) as NodeId,
-    path: node ? pathOf(node) : pathHint(entry.node),
+    target: entry.node,
+    id: node?.id ?? idAnchor(entry.node),
     node,
-    ...(entry.view !== undefined ? { view: entry.view } : {}),
-    params: entry.params ?? IDLE_LOCATION.params,
-    missing: settled && node === null,
+    ...(entry.view === undefined ? {} : { view: entry.view }),
+    params: entry.params ?? EMPTY_PARAMS,
+    missing: result !== null && !result.pending && node === null,
   }
 }
 
-/**
- * Whether a read has definitively settled — data present, a hard error, or a
- * completed empty fetch. Guards `missing` (and the missing policy) against the
- * one-render false-empty before a cold shape's first fetch is even in flight.
- */
-export function useSettled(result: LiveResult | null, key: string | null): boolean {
-  const sawPending = useRef(new Map<string, boolean>())
-  useEffect(() => {
-    if (key !== null && result?.pending === true) sawPending.current.set(key, true)
-  }, [key, result?.pending])
-  if (key === null || result === null) return false
-  if (result.node !== null) return true
-  if (result.error !== undefined) return true
-  return !result.pending && sawPending.current.get(key) === true
-}
-
-// ── path math ──────────────────────────────────────────────────────────────
-
-/** The raw path of a live node (empty when cold). */
-export function pathOf(node: Node | null): string {
-  return node ? rawOf(node.path) : ''
-}
-
-/** Best-effort anchor id from a stored ref (`@<id>` → id, else the raw ref). */
-export function idHint(ref: string): string {
-  return ref.startsWith('@') ? ref.slice(1) : ref
-}
-
-/** Best-effort path from a stored ref (a `/…` ref is already a path). */
-export function pathHint(ref: string): string {
-  return ref.startsWith('/') ? ref : ''
+function idAnchor(target: NodePath): NodeId | null {
+  const path = Path.from(target)
+  return path.ast.anchor.kind === 'id' && path.ast.steps.length === 0 ? path.ast.anchor.id : null
 }
 
-/** The parent absolute path, or null at (or above) root. */
-export function parentPath(raw: string): string | null {
-  const norm = raw.replace(/\/+$/, '')
-  if (norm === '' || norm === '/') return null
-  const idx = norm.lastIndexOf('/')
-  return idx <= 0 ? '/' : norm.slice(0, idx)
-}
-
-/**
- * The inclusive, root-first path chain for an absolute path — the ancestry the
- * kernel tree encodes in the slug path (`/a/b/c` → `/`, `/a`, `/a/b`, `/a/b/c`).
- * The node itself is the last element, so breadcrumbs map the chain directly.
- */
-export function chainPaths(raw: string): string[] {
-  const norm = raw.replace(/\/+$/, '')
-  if (norm === '' || norm === '/') return ['/']
-  const out = ['/']
-  let acc = ''
-  for (const seg of norm.split('/').filter(Boolean)) {
-    acc += `/${seg}`
-    out.push(acc)
-  }
-  return out
-}
+export type { Node, NodeId }