@stone-js/starters 0.8.8 → 0.8.10

package/basic-react-native-declarative/adapter/NativeAdapter.ts

@@ -0,0 +1,108 @@
+import { RawResponseWrapper } from './RawResponseWrapper'
+import { NativeAdapterContext, NativeResponse, RawNativeResponseOptions } from './declarations'
+import { NativeEventSource, NativeNavigationEvent, nativeEventSource } from './NativeEventSource'
+import { Adapter, AdapterEventBuilder, AdapterEventHandlerType, IBlueprint } from '@stone-js/core'
+import { IncomingBrowserEvent, IncomingBrowserEventOptions, OutgoingBrowserResponse } from '@stone-js/browser-core'
+
+/**
+ * Native proof-of-concept adapter for Stone.js.
+ *
+ * Captures navigation intents from the in-memory event source, normalizes them
+ * into `IncomingBrowserEvent` instances, sends them through the kernel and
+ * executes the deferred render effect. It is the exact native counterpart of
+ * `BrowserAdapter`, with the event source replacing `window`.
+ *
+ * Temporary by design: it prefigures `@stone-js/react-native-adapter`, which
+ * will capture real deep links (`Linking`) and app-state changes on top of the
+ * same skeleton.
+ */
+export class NativeAdapter extends Adapter<
+NativeNavigationEvent,
+NativeResponse,
+NativeEventSource,
+IncomingBrowserEvent,
+IncomingBrowserEventOptions,
+OutgoingBrowserResponse,
+NativeAdapterContext
+> {
+  private unsubscribe?: () => void
+
+  /**
+   * Creates an instance of the `NativeAdapter`.
+   *
+   * @param blueprint - The application blueprint.
+   * @returns A new instance of `NativeAdapter`.
+   */
+  static create (blueprint: IBlueprint): NativeAdapter {
+    return new this(blueprint)
+  }
+
+  /**
+   * Executes the adapter: subscribes to navigation intents and dispatches the
+   * initial event, exactly like the browser adapter dispatches its synthetic
+   * first navigation on startup.
+   *
+   * Idempotent: running again tears down the previous subscription first.
+   */
+  public async run<ExecutionResultType = undefined>(): Promise<ExecutionResultType> {
+    await this.executeHooks('onStart')
+
+    const eventHandler = this.resolveEventHandler()
+
+    await this.executeEventHandlerHooks('onInit', eventHandler)
+
+    this.unsubscribe?.()
+    this.unsubscribe = nativeEventSource.subscribe((rawEvent) => {
+      void this.eventListener(eventHandler, rawEvent)
+    })
+
+    await this.eventListener(eventHandler, { url: nativeEventSource.initialUrl })
+
+    return undefined as ExecutionResultType
+  }
+
+  /**
+   * Tear down the adapter: remove the navigation subscription and run the
+   * `onStop` hooks. Safe to call multiple times.
+   */
+  public async stop (): Promise<void> {
+    if (this.unsubscribe === undefined) { return }
+    this.unsubscribe()
+    this.unsubscribe = undefined
+    await this.executeHooks('onStop')
+  }
+
+  /**
+   * Processes one navigation intent through the kernel.
+   *
+   * @param eventHandler - The resolved kernel event handler.
+   * @param rawEvent - The raw navigation event.
+   * @returns The platform response.
+   */
+  protected async eventListener (
+    eventHandler: AdapterEventHandlerType<IncomingBrowserEvent, OutgoingBrowserResponse>,
+    rawEvent: NativeNavigationEvent
+  ): Promise<NativeResponse> {
+    const incomingEventBuilder = AdapterEventBuilder.create<IncomingBrowserEventOptions, IncomingBrowserEvent>({
+      resolver: (options) => IncomingBrowserEvent.create(options)
+    })
+
+    const rawResponseBuilder = AdapterEventBuilder.create<RawNativeResponseOptions, RawResponseWrapper>({
+      resolver: (options) => RawResponseWrapper.create(options)
+    })
+
+    const context: NativeAdapterContext = {
+      rawEvent,
+      executionContext: nativeEventSource,
+      rawResponseBuilder,
+      incomingEventBuilder
+    }
+
+    try {
+      return await this.sendEventThroughDestination(context, eventHandler)
+    } catch (error: any) {
+      const builder = await this.handleError(error, context)
+      return await this.buildRawResponse({ ...context, rawResponseBuilder: builder })
+    }
+  }
+}

package/basic-react-native-declarative/adapter/NativeErrorHandler.ts

@@ -0,0 +1,53 @@
+import { emitNativeError } from './renderSink'
+import { NativeResponse } from './declarations'
+import { NativeEventSource, NativeNavigationEvent } from './NativeEventSource'
+import {
+  ILogger,
+  IBlueprint,
+  LoggerResolver,
+  AdapterErrorContext,
+  IAdapterErrorHandler,
+  defaultLoggerResolver,
+  AdapterEventBuilderType
+} from '@stone-js/core'
+
+/**
+ * NativeErrorHandler options.
+ */
+export interface NativeErrorHandlerOptions {
+  blueprint: IBlueprint
+}
+
+/**
+ * Adapter-level error handler: logs the error and surfaces it on screen
+ * through the render sink, so a broken chain is visible instead of silent.
+ */
+export class NativeErrorHandler implements IAdapterErrorHandler<NativeNavigationEvent, NativeResponse, NativeEventSource> {
+  private readonly logger: ILogger
+
+  /**
+   * Create a NativeErrorHandler.
+   *
+   * @param options - NativeErrorHandler options.
+   */
+  constructor ({ blueprint }: NativeErrorHandlerOptions) {
+    this.logger = blueprint.get<LoggerResolver>('stone.logger.resolver', defaultLoggerResolver)(blueprint)
+  }
+
+  /**
+   * Handle an error.
+   *
+   * @param error - The error to handle.
+   * @param context - The context of the adapter.
+   * @returns The raw response builder.
+   */
+  public handle (
+    error: Error,
+    context: AdapterErrorContext<NativeNavigationEvent, NativeResponse, NativeEventSource>
+  ): AdapterEventBuilderType<NativeResponse> {
+    this.logger.error(error.message, { error })
+    emitNativeError(error)
+
+    return context.rawResponseBuilder
+  }
+}

package/basic-react-native-declarative/adapter/NativeEventSource.ts

@@ -0,0 +1,58 @@
+/**
+ * The native cause captured by the adapter: an intent to show a URL.
+ *
+ * On a real device this is what a deep link, a push-notification tap or an
+ * in-app navigation collapses to. The proof-of-concept models all of them as
+ * one tiny in-memory event source; the future `@stone-js/react-native-adapter`
+ * will plug `Linking` and `AppState` into the exact same shape.
+ */
+export interface NativeNavigationEvent {
+  /** The URL to resolve, e.g. `stone://app/hello/Noowow`. */
+  url: string
+  /** Optional navigation metadata, mirroring the browser's `history.state`. */
+  metadata?: unknown
+}
+
+/**
+ * A navigation listener registered by the adapter.
+ */
+export type NativeNavigationListener = (event: NativeNavigationEvent) => void
+
+/**
+ * The in-memory navigation event source: the native counterpart of `window`
+ * for the browser adapter. It is pure JavaScript, so the same code runs under
+ * React Native, Node (tests) and anywhere else.
+ */
+export class NativeEventSource {
+  /** The synthetic first event, dispatched when the adapter starts. */
+  public readonly initialUrl = 'stone://app/'
+
+  private readonly listeners = new Set<NativeNavigationListener>()
+
+  /**
+   * Register a navigation listener.
+   *
+   * @param listener - The listener to register.
+   * @returns A teardown function removing the listener.
+   */
+  subscribe (listener: NativeNavigationListener): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /**
+   * Emit a navigation intent, exactly like the router does in the browser
+   * through the `@stonejs/router.navigate` custom event.
+   *
+   * @param url - The URL to navigate to.
+   * @param metadata - Optional navigation metadata.
+   */
+  navigate (url: string, metadata?: unknown): void {
+    this.listeners.forEach((listener) => listener({ url, metadata }))
+  }
+}
+
+/**
+ * The application-wide event source instance.
+ */
+export const nativeEventSource = new NativeEventSource()

package/basic-react-native-declarative/adapter/RawResponseWrapper.ts

@@ -0,0 +1,30 @@
+import { IRawResponseWrapper } from '@stone-js/core'
+import { NativeResponse, RawNativeResponseOptions } from './declarations'
+
+/**
+ * Wraps the raw native response: the platform effect is the deferred `render`
+ * closure contributed by the response middleware, executed once the kernel has
+ * resolved the outgoing response.
+ */
+export class RawResponseWrapper implements IRawResponseWrapper<NativeResponse> {
+  /**
+   * Factory method to create an instance of `RawResponseWrapper`.
+   *
+   * @param options - The raw response options.
+   * @returns A new instance of `RawResponseWrapper`.
+   */
+  static create (options: RawNativeResponseOptions): RawResponseWrapper {
+    return new this(options)
+  }
+
+  private constructor (private readonly options: RawNativeResponseOptions) {}
+
+  /**
+   * Execute the deferred render effect and return its result.
+   *
+   * @returns The platform response.
+   */
+  async respond (): Promise<NativeResponse> {
+    return await this.options?.render?.()
+  }
+}

package/basic-react-native-declarative/adapter/declarations.ts

@@ -0,0 +1,40 @@
+import { RawResponseWrapper } from './RawResponseWrapper'
+import { NativeEventSource, NativeNavigationEvent } from './NativeEventSource'
+import { AdapterContext, IAdapterEventBuilder, RawResponseOptions } from '@stone-js/core'
+import { IncomingBrowserEvent, IncomingBrowserEventOptions, OutgoingBrowserResponse } from '@stone-js/browser-core'
+
+/**
+ * The platform identifier exposed on every incoming event's source.
+ */
+export const NATIVE_PLATFORM = 'react-native'
+
+/**
+ * The raw platform response. The native platform has no transport response:
+ * the effect is a render, so the raw response is whatever the renderer returns.
+ */
+export type NativeResponse = unknown
+
+/**
+ * Raw response options carrying the deferred `render` effect, mirroring the
+ * browser adapter's contract.
+ */
+export interface RawNativeResponseOptions extends RawResponseOptions {
+  render?: () => NativeResponse | Promise<NativeResponse>
+}
+
+/**
+ * The adapter context for the native proof-of-concept adapter.
+ */
+export type NativeAdapterContext = AdapterContext<
+NativeNavigationEvent,
+NativeResponse,
+NativeEventSource,
+IncomingBrowserEvent,
+IncomingBrowserEventOptions,
+OutgoingBrowserResponse
+>
+
+/**
+ * The response builder used by the native adapter middleware.
+ */
+export type NativeAdapterResponseBuilder = IAdapterEventBuilder<RawNativeResponseOptions, RawResponseWrapper>

package/basic-react-native-declarative/adapter/middleware.ts

@@ -0,0 +1,73 @@
+import { emitNativeRender } from './renderSink'
+import { NextMiddleware } from '@stone-js/core'
+import { CookieCollection } from '@stone-js/browser-core'
+import { NATIVE_PLATFORM, NativeAdapterContext, NativeAdapterResponseBuilder } from './declarations'
+
+/**
+ * Transforms the raw navigation event into the intention: an
+ * `IncomingBrowserEvent`, reused as-is from `@stone-js/browser-core`.
+ *
+ * This is the native mirror of the browser adapter's IncomingEventMiddleware:
+ * `location` comes from the event's URL instead of `window.location`, and the
+ * cookie collection is purely in memory (no `document`).
+ */
+export class IncomingEventMiddleware {
+  /**
+   * Handle the incoming raw event.
+   *
+   * @param context - The adapter context.
+   * @param next - The next middleware.
+   * @returns The response builder.
+   */
+  async handle (
+    context: NativeAdapterContext,
+    next: NextMiddleware<NativeAdapterContext, NativeAdapterResponseBuilder>
+  ): Promise<NativeAdapterResponseBuilder> {
+    const url = new URL(context.rawEvent.url)
+
+    context
+      .incomingEventBuilder
+      .add('url', url)
+      .add('queryString', url.search)
+      .add('protocol', url.protocol.replace(':', ''))
+      .add('metadata', context.rawEvent.metadata ?? {})
+      .add('cookies', CookieCollection.create(undefined, {}))
+      .add('source', {
+        rawEvent: context.rawEvent,
+        platform: NATIVE_PLATFORM,
+        rawContext: context.executionContext
+      })
+
+    return await next(context)
+  }
+}
+
+/**
+ * Contributes the deferred render effect: once the kernel has produced the
+ * outgoing response, hand it to the registered render target.
+ *
+ * This is the native mirror of the role `BrowserResponseMiddleware` plays for
+ * the browser platform in `@stone-js/use-react`.
+ */
+export class ResponseMiddleware {
+  /**
+   * Handle the outgoing response.
+   *
+   * @param context - The adapter context.
+   * @param next - The next middleware.
+   * @returns The response builder.
+   */
+  async handle (
+    context: NativeAdapterContext,
+    next: NextMiddleware<NativeAdapterContext, NativeAdapterResponseBuilder>
+  ): Promise<NativeAdapterResponseBuilder> {
+    context.rawResponseBuilder.add('render', () => {
+      if (context.outgoingResponse !== undefined) {
+        emitNativeRender(context.outgoingResponse)
+      }
+      return context.outgoingResponse
+    })
+
+    return await next(context)
+  }
+}

package/basic-react-native-declarative/adapter/nativeAdapterBlueprint.ts

@@ -0,0 +1,51 @@
+import { NATIVE_PLATFORM } from './declarations'
+import { NativeAdapter } from './NativeAdapter'
+import { NativeErrorHandler } from './NativeErrorHandler'
+import { IncomingEventMiddleware, ResponseMiddleware } from './middleware'
+import { AdapterConfig, AppConfig, defaultKernelResolver, IBlueprint, StoneBlueprint } from '@stone-js/core'
+import { OutgoingBrowserResponse, OutgoingBrowserResponseOptions } from '@stone-js/browser-core'
+
+/**
+ * Adapter resolver for the native proof-of-concept adapter.
+ *
+ * @param blueprint - The `IBlueprint` providing configuration and dependencies.
+ * @returns A `NativeAdapter` instance.
+ */
+export const nativeAdapterResolver = (blueprint: IBlueprint): NativeAdapter => {
+  return NativeAdapter.create(blueprint)
+}
+
+/**
+ * Blueprint for the native proof-of-concept adapter.
+ *
+ * Activated the canonical way: handed to `@StoneApp(options, [blueprints])`
+ * (declarative) or `defineStoneApp(handler, options, [blueprints])`
+ * (imperative). Being the only adapter, it is selected automatically.
+ */
+export const nativeAdapterBlueprint: StoneBlueprint = {
+  stone: {
+    kernel: {
+      responseResolver: (options: OutgoingBrowserResponseOptions) => {
+        return OutgoingBrowserResponse.create({ ...options, statusCode: options.statusCode ?? 200 })
+      }
+    },
+    adapters: [
+      {
+        current: false,
+        default: true,
+        variant: 'native',
+        platform: NATIVE_PLATFORM,
+        middleware: [
+          { module: IncomingEventMiddleware, isClass: true, priority: 0 },
+          { module: ResponseMiddleware, isClass: true, priority: 10 }
+        ],
+        resolver: nativeAdapterResolver,
+        eventHandlerResolver: defaultKernelResolver,
+        events: [],
+        errorHandlers: {
+          default: { module: NativeErrorHandler, isClass: true }
+        }
+      } as unknown as AdapterConfig
+    ]
+  } as Partial<AppConfig> as AppConfig
+}

package/basic-react-native-declarative/adapter/renderSink.ts

@@ -0,0 +1,52 @@
+import { OutgoingBrowserResponse } from '@stone-js/browser-core'
+
+/**
+ * A render listener: receives the kernel's outgoing response for display.
+ */
+export type NativeRenderListener = (response: OutgoingBrowserResponse) => void
+
+/**
+ * An error listener: receives adapter-level errors for display.
+ */
+export type NativeErrorListener = (error: Error) => void
+
+let renderListener: NativeRenderListener | undefined
+let errorListener: NativeErrorListener | undefined
+
+/**
+ * Register the render effect target. In this proof of concept the target is
+ * the React root component's state; the future `@stone-js/use-react-native`
+ * response middleware will push into the native navigation stack instead.
+ *
+ * @param listener - The render listener.
+ */
+export function onNativeRender (listener: NativeRenderListener): void {
+  renderListener = listener
+}
+
+/**
+ * Register the error display target.
+ *
+ * @param listener - The error listener.
+ */
+export function onNativeError (listener: NativeErrorListener): void {
+  errorListener = listener
+}
+
+/**
+ * Push an outgoing response to the registered render target.
+ *
+ * @param response - The kernel's outgoing response.
+ */
+export function emitNativeRender (response: OutgoingBrowserResponse): void {
+  renderListener?.(response)
+}
+
+/**
+ * Push an error to the registered error target.
+ *
+ * @param error - The error to display.
+ */
+export function emitNativeError (error: Error): void {
+  errorListener?.(error)
+}

package/basic-react-native-declarative/app/Application.ts

@@ -0,0 +1,17 @@
+import { Routing } from '@stone-js/router'
+import { LogLevel, StoneApp } from '@stone-js/core'
+import { nativeAdapterBlueprint } from '../adapter/nativeAdapterBlueprint'
+
+/**
+ * Application
+ *
+ * This is the main application entry point.
+ *
+ * @Routing() enables the Stone router: incoming navigation events are matched
+ * against the route definitions declared by the controllers.
+ * @StoneApp() enables the Stone application (required). Extra blueprints are
+ * activated through its second argument: here, the native adapter.
+ */
+@Routing()
+@StoneApp({ name: 'Stone.js Native', logger: { level: LogLevel.INFO } }, [nativeAdapterBlueprint])
+export class Application {}

package/basic-react-native-declarative/app/WelcomeController.ts

@@ -0,0 +1,66 @@
+import { Controller, Match } from '@stone-js/router'
+import { IncomingBrowserEvent } from '@stone-js/browser-core'
+
+/**
+ * The payload every route of this starter returns.
+ */
+export interface WelcomeData {
+  message: string
+  route: string
+  framework: {
+    name: string
+    tagline: string
+    docs: string
+  }
+}
+
+/**
+ * WelcomeController
+ *
+ * The routes are matched against the URL carried by each navigation event,
+ * exactly like they would be in a browser SPA or behind an HTTP adapter:
+ * the domain does not know it is running inside a native application.
+ */
+@Controller()
+export class WelcomeController {
+  /**
+   * The landing route, dispatched once when the application starts.
+   *
+   * @returns The welcome payload.
+   */
+  @Match('/')
+  welcome (): WelcomeData {
+    return this.present('Welcome to Stone.js on React Native!', '/')
+  }
+
+  /**
+   * A parameterized route: the `name` route parameter is read from the event.
+   *
+   * @param event - The incoming navigation event.
+   * @returns The greeting payload.
+   */
+  @Match('/hello/:name')
+  hello (event: IncomingBrowserEvent): WelcomeData {
+    const name = String(event.get<string>('name', 'World'))
+    return this.present(`Hello ${name}! Same domain, native screen.`, `/hello/${name}`)
+  }
+
+  /**
+   * Build the branded payload returned by every route.
+   *
+   * @param message - The message to display.
+   * @param route - The matched route path.
+   * @returns The payload.
+   */
+  private present (message: string, route: string): WelcomeData {
+    return {
+      message,
+      route,
+      framework: {
+        name: 'Stone.js',
+        tagline: 'The continuum framework',
+        docs: 'https://stonejs.dev'
+      }
+    }
+  }
+}

package/basic-react-native-declarative/app.json

@@ -0,0 +1,25 @@
+{
+  "expo": {
+    "name": "basic-react-native-declarative",
+    "slug": "basic-react-native-declarative",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "light",
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#E6F4FE",
+        "foregroundImage": "./assets/android-icon-foreground.png",
+        "backgroundImage": "./assets/android-icon-background.png",
+        "monochromeImage": "./assets/android-icon-monochrome.png"
+      },
+      "predictiveBackGestureEnabled": false
+    },
+    "web": {
+      "favicon": "./assets/favicon.png"
+    }
+  }
+}

package/basic-react-native-declarative/babel.config.js

@@ -0,0 +1,16 @@
+/**
+ * Stone.js runs on TC39 stage-3 decorators (2023-11) with `Symbol.metadata`.
+ *
+ * `babel-preset-expo` applies `@babel/plugin-proposal-decorators` itself (in
+ * legacy mode by default): the decorator semantics are configured through the
+ * preset's `decorators` option, never by adding the plugin separately, so the
+ * preset keeps its ordering guarantees against the class-field transforms.
+ */
+module.exports = function (api) {
+  api.cache(true)
+  return {
+    presets: [
+      ['babel-preset-expo', { decorators: { version: '2023-11' } }]
+    ]
+  }
+}

package/basic-react-native-declarative/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Platform polyfills come first, before anything from Stone.js loads.
+ *
+ * - React Native's built-in `URL` is a stub (no `pathname`, no `searchParams`);
+ *   Stone.js relies on the full WHATWG URL API, so the polyfill is required.
+ * - `TextEncoder` is installed only when the JS engine does not provide it
+ *   (older Hermes versions).
+ */
+import 'react-native-url-polyfill/auto'
+
+if (typeof globalThis.TextEncoder === 'undefined') {
+  require('fast-text-encoding')
+}
+
+import { registerRootComponent } from 'expo'
+
+import App from './App'
+
+// registerRootComponent calls AppRegistry.registerComponent('main', () => App);
+// It also ensures that whether you load the app in Expo Go or in a native build,
+// the environment is set up appropriately
+registerRootComponent(App)

package/basic-react-native-declarative/metro.config.js

@@ -0,0 +1,7 @@
+const { getDefaultConfig } = require('expo/metro-config')
+
+/**
+ * Pinning the project root keeps Metro scoped to this starter, even when the
+ * starter lives inside a larger workspace (as it does in the Stone.js monorepo).
+ */
+module.exports = getDefaultConfig(__dirname)