@stone-js/starters 0.8.11 → 0.8.13

package/basic-react-native-imperative/README.md

@@ -0,0 +1,150 @@
+# Stone.js - Basic React Native starter
+
+Stone.js's basic starter to create a React Native (Expo) app using the imperative API.
+
+The same welcome screen the web starters show, on a phone. Same mark, same palette, same words,
+because it is the same domain: `app/HomeScreen.tsx` is a page, with `handle`, `head` and `render`,
+and only `render` knows it is native.
+
+## Project Setup
+
+```sh
+npm install
+```
+
+### Run it
+
+```sh
+npm start           # Expo dev server: press i for iOS, a for Android
+npm run ios         # straight to the iOS simulator
+npm run android     # straight to an Android emulator
+```
+
+### Run it in a browser
+
+The fastest loop is often a browser tab: Fast Refresh, and the same code then runs on a device
+untouched. It is opt-in, because the web target needs two dependencies a native-only app has no
+reason to carry.
+
+```sh
+npx expo install react-dom react-native-web
+npm run web
+```
+
+Use it for the domain, the navigation and most of the interface. Use a device before believing
+anything about the parts that are actually native: `react-native-web` covers the core primitives,
+not the camera, secure storage or a native gesture handler.
+
+### Bundle for production
+
+```sh
+npm run export      # a Hermes bytecode bundle, per platform
+```
+
+An installable build is `npx expo run:ios` or an [EAS build](https://docs.expo.dev/build/setup/):
+both need a native toolchain, and they are better commands than a wrapper would be.
+
+### Run tests
+
+```sh
+npm run test
+npm run test:cvg
+```
+
+The tests boot the real kernel, router, adapter and renderer under Node, send a deep link, and
+assert what landed on the navigation stack. No device, no simulator, no Metro.
+
+### Type-check
+
+```sh
+npm run typecheck
+```
+
+## What is where
+
+| File | What it does |
+|---|---|
+| `app/Application.ts` | Enables the router, the adapter and the renderer. One call, two blueprints. |
+| `app/HomeScreen.tsx` | The page factory and its `definePage` blueprint. Adding a screen is adding a file like it. |
+| `app/WelcomeView.tsx` | What the screen draws, in React Native components. |
+| `app/theme.ts` | The Stone.js palette, following the device's light or dark appearance. |
+| `index.ts` | Polyfills, boot, and `registerRootComponent`. |
+| `metro.config.js` | `withStone`: collects `app/` into `.stone/modules.ts` before Metro bundles. |
+
+## Nothing lists your screens
+
+A web application never lists its pages, and this one does not either. `withStone` collects
+everything under `app/` and writes `.stone/modules.ts` whenever Metro starts, so `expo start`,
+`expo run:ios` and an EAS build all get it without anyone remembering to ask.
+
+It runs when Metro starts, not while it runs: **adding** a screen to a running dev server means
+restarting it. **Editing** one needs nothing, Fast Refresh was never involved.
+
+`.stone/` is generated. It is in `.gitignore`, and there is no reason to open it.
+
+## Navigating
+
+```tsx
+import { useNavigate, useGoBack } from '@stone-js/use-react-native'
+
+const navigate = useNavigate()
+
+navigate('/tasks/42')                  // push a screen
+navigate('/tasks/42', 'replace')       // swap the current one
+navigate('/sign-in', 'reset')          // start again, leaving no history
+```
+
+Navigation goes through the router, so a screen never renders another screen itself. `useGoBack()`
+returns `{ goBack, canGoBack }`: wire `goBack` to your header button and to Android's hardware back
+button, and let the platform leave the application when `canGoBack` is false.
+
+Deep links arrive the same way. This starter's scheme is `stone`, so `stone://app/?name=Ada` reaches
+the page that owns `/`, with `name` readable through `event.get('name')`. Change `scheme` in
+`app.json` to your own.
+
+## Using a native navigator
+
+`App.tsx` renders `StoneNativeApp`, which shows the screen on top of the stack. That is the floor,
+not the ceiling: it is what makes the first run work with nothing installed. The platform's
+transitions, the swipe-back gesture, and a screen keeping its own state while another covers it are
+things only a native navigator gives you.
+
+The stack is public state, so a navigator drives itself from it:
+
+```tsx
+import { useScreens } from '@stone-js/use-react-native'
+import { NavigationContainer } from '@react-navigation/native'
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+export default function App () {
+  const screens = useScreens()
+
+  return (
+    <NavigationContainer>
+      <Stack.Navigator>
+        {screens.map((screen) => (
+          <Stack.Screen key={screen.key} name={screen.key} options={{ title: screen.title }}>
+            {() => screen.element}
+          </Stack.Screen>
+        ))}
+      </Stack.Navigator>
+    </NavigationContainer>
+  )
+}
+```
+
+Nothing about your pages changes.
+
+## The declarative twin
+
+The same application, written with decorators instead of values, is
+[`basic-react-native-declarative`](../basic-react-native-declarative). Neither paradigm wraps the
+other; both write to the same manifest.
+
+## Learn more
+
+- [Stone.js documentation](https://stonejs.dev/docs)
+- [`@stone-js/use-react-native`](https://www.npmjs.com/package/@stone-js/use-react-native)
+- [`@stone-js/react-native-adapter`](https://www.npmjs.com/package/@stone-js/react-native-adapter)

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

@@ -0,0 +1,25 @@
+import { LogLevel } from '@stone-js/core'
+import { routerBlueprint } from '@stone-js/router'
+import { defineStoneReactNativeApp } from '@stone-js/use-react-native'
+import { reactNativeAdapterBlueprint } from '@stone-js/react-native-adapter'
+
+/**
+ * Application
+ *
+ * This is the main application entry point.
+ *
+ * The same four things the declarative starter says with decorators, said with values instead:
+ * `defineStoneReactNativeApp` enables the renderer, and the blueprints it is handed enable the
+ * router and the React Native adapter. Neither paradigm is a wrapper around the other; both write
+ * to the same manifest.
+ *
+ * The web starter's Application is this same call with one blueprint swapped: the browser adapter's
+ * for the native one. That is the promise, in four lines: the domain is written once, and what
+ * changes is the context it runs in.
+ *
+ * Screens live in their own files, one route each. See `app/HomeScreen.tsx`.
+ */
+export const Application = defineStoneReactNativeApp(
+  { logger: { level: LogLevel.INFO } },
+  [routerBlueprint, reactNativeAdapterBlueprint]
+)

package/basic-react-native-imperative/app/HomeScreen.tsx

@@ -0,0 +1,84 @@
+import { JSX } from 'react'
+import { WelcomeView } from './WelcomeView'
+import { ILogger, Promiseable } from '@stone-js/core'
+import { definePage, HeadContext, IPage, PageHeadContext, PageRenderContext, ReactIncomingEvent } from '@stone-js/use-react-native'
+
+/**
+ * The home screen, as a factory.
+ *
+ * A page, exactly as on the web: it answers with `handle`, names itself with `head` and draws itself
+ * with `render`. The only native thing here is what `render` returns, and it returns React Native
+ * components instead of DOM ones.
+ *
+ * The factory receives the container's services as its argument, which is how this paradigm gets
+ * dependency injection without a constructor.
+ *
+ * @param options - The injected services.
+ * @returns The page.
+ */
+export const HomeScreen = ({ logger }: AppOptions): IPage<ReactIncomingEvent> => {
+  return {
+    /**
+     * Handle incoming events.
+     *
+     * A deep link carries its parameters here: `stone://app/?name=Ada` arrives as an event, and
+     * `event.get` reads from it the same way an HTTP request would be read.
+     *
+     * @param event - Incoming event.
+     * @returns The screen's data.
+     */
+    handle (event: ReactIncomingEvent): ResponseData {
+      const message = `Hello ${String(event.get<string>('name', 'World'))}!`
+
+      logger.info(message)
+
+      return { message }
+    },
+
+    /**
+     * Set the screen's head.
+     *
+     * A phone has no meta tags, so the title is what a navigator shows in its header. The same
+     * `head` a web page declares, read by a different renderer.
+     *
+     * @returns The head context.
+     */
+    head ({ event }: PageHeadContext): Promiseable<HeadContext> {
+      return {
+        title: `${String(event.get<string>('name', 'World'))} · Welcome to Stone.js`,
+        description: 'A universal Stone.js application. Write your domain once; Stone.js is the context that runs it anywhere.'
+      }
+    },
+
+    /**
+     * Render the screen.
+     *
+     * @returns The rendered screen.
+     */
+    render ({ data }: PageRenderContext<ResponseData>): JSX.Element {
+      return <WelcomeView message={data?.message} />
+    }
+  }
+}
+
+/**
+ * HomeScreen Blueprint
+ *
+ * Binds the page to its route. Adding a screen is adding a file like this one: nothing lists it,
+ * because `withStone` collects everything under `app/` before Metro bundles.
+ */
+export const HomeScreenBlueprint = definePage(HomeScreen, { path: '/' })
+
+/**
+ * Application options.
+ */
+interface AppOptions {
+  logger: ILogger
+}
+
+/**
+ * Response data
+ */
+export interface ResponseData {
+  message: string
+}

package/basic-react-native-imperative/app/PortalMark.tsx

@@ -0,0 +1,32 @@
+import { JSX } from 'react'
+import { Image, useColorScheme } from 'react-native'
+
+/**
+ * Le Portail, the Stone.js mark.
+ *
+ * The same three arcs as `public/logo.svg` in the web starters: two stone segments rising, and the
+ * keystone lit in ember. Two files rather than one, because the segments have to contrast with the
+ * ground the screen paints, exactly as the brand ships a dark-ground and a light-ground Portal.
+ *
+ * Shipped as an image on purpose. Drawing it would mean `react-native-svg`, a native module, and
+ * a starter's first job is to run on a device the moment it is installed, with nothing to link
+ * and no version to match against Expo Go's.
+ *
+ * @param props.size - Side length in points.
+ * @returns The mark.
+ */
+export function PortalMark ({ size = 104 }: { size?: number }): JSX.Element {
+  const scheme = useColorScheme()
+
+  return (
+    <Image
+      accessibilityRole='image'
+      accessibilityLabel='Stone.js'
+      source={scheme === 'light'
+        ? require('../assets/logo-light.png')
+        : require('../assets/logo-dark.png')}
+      style={{ width: size, height: size }}
+      resizeMode='contain'
+    />
+  )
+}

package/basic-react-native-imperative/app/WelcomeView.tsx

@@ -0,0 +1,146 @@
+import { JSX } from 'react'
+import { PortalMark } from './PortalMark'
+import { useStoneTheme } from './theme'
+import { Linking, Platform, Pressable, StyleSheet, Text, View } from 'react-native'
+
+const DOCS = 'https://stonejs.dev/docs'
+const GITHUB = 'https://github.com/stone-foundation/stone-js-framework'
+
+/**
+ * The welcome screen.
+ *
+ * The native twin of the web starters' welcome page: the same mark, the same palette, the same
+ * words. What differs is only what a phone does differently, which is the whole point of the
+ * framework: `View` instead of `div`, a `StyleSheet` instead of a stylesheet, `Linking` instead of
+ * an anchor, and a glow drawn as a circle because there is no `radial-gradient`.
+ *
+ * @param props.message - What the handler returned.
+ * @returns The screen.
+ */
+export function WelcomeView ({ message }: { message?: string }): JSX.Element {
+  const theme = useStoneTheme()
+
+  const open = (url: string): void => { void Linking.openURL(url) }
+
+  return (
+    <View style={[styles.screen, { backgroundColor: theme.ink }]}>
+      <View style={[styles.glow, { backgroundColor: theme.inkGlow }]} pointerEvents='none' />
+
+      <View style={styles.hero}>
+        <PortalMark size={104} />
+
+        <Text style={[styles.eyebrow, { color: theme.creamDim }]}>WELCOME TO</Text>
+        <Text style={[styles.title, { color: theme.ember2 }]}>Stone.js</Text>
+        <Text style={[styles.lead, { color: theme.cream }]}>{message}</Text>
+        <Text style={[styles.tagline, { color: theme.creamDim }]}>
+          Your app is running. Write your domain once, Stone.js is the context that runs it
+          anywhere: server, serverless, browser, CLI and the edge.
+        </Text>
+
+        <View style={styles.links}>
+          <Pressable
+            accessibilityRole='link'
+            onPress={() => open(DOCS)}
+            style={[styles.pill, { borderColor: theme.line, backgroundColor: theme.card }]}
+          >
+            <Text style={[styles.pillText, { color: theme.cream }]}>Documentation</Text>
+          </Pressable>
+          <Pressable
+            accessibilityRole='link'
+            onPress={() => open(GITHUB)}
+            style={[styles.pill, { borderColor: theme.line, backgroundColor: theme.card }]}
+          >
+            <Text style={[styles.pillText, { color: theme.cream }]}>GitHub</Text>
+          </Pressable>
+        </View>
+
+        <Text style={[styles.edit, { color: theme.creamDim }]}>
+          Edit <Text style={[styles.editFile, { color: theme.ember1 }]}>app/HomeScreen.tsx</Text>
+        </Text>
+      </View>
+
+      <Text style={[styles.brand, { color: theme.creamDim }]}>
+        <Text style={{ color: theme.ember2 }}>●</Text> Stone.js · the continuum framework
+      </Text>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  screen: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 24,
+    paddingVertical: 48,
+    overflow: 'hidden'
+  },
+  // The web starter's ember glow, as the only shape a phone can draw it with.
+  glow: {
+    position: 'absolute',
+    top: '4%',
+    width: 420,
+    height: 420,
+    borderRadius: 210,
+    opacity: 0.55
+  },
+  hero: {
+    width: '100%',
+    maxWidth: 420,
+    alignItems: 'center'
+  },
+  eyebrow: {
+    marginTop: 22,
+    fontSize: 12,
+    fontWeight: '600',
+    letterSpacing: 3.4
+  },
+  title: {
+    marginTop: 6,
+    fontSize: 52,
+    fontWeight: '800',
+    letterSpacing: -1.6
+  },
+  lead: {
+    marginTop: 16,
+    fontSize: 20,
+    fontWeight: '600',
+    textAlign: 'center'
+  },
+  tagline: {
+    marginTop: 10,
+    fontSize: 15,
+    lineHeight: 24,
+    textAlign: 'center'
+  },
+  links: {
+    marginTop: 30,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+    gap: 12
+  },
+  pill: {
+    borderWidth: 1,
+    borderRadius: 12,
+    paddingVertical: 11,
+    paddingHorizontal: 18
+  },
+  pillText: {
+    fontSize: 14,
+    fontWeight: '600'
+  },
+  edit: {
+    marginTop: 18,
+    fontSize: 13,
+    fontFamily: Platform.select({ ios: 'Menlo', android: 'monospace', default: 'monospace' })
+  },
+  editFile: {
+    fontWeight: '700'
+  },
+  brand: {
+    position: 'absolute',
+    bottom: 32,
+    fontSize: 13
+  }
+})

package/basic-react-native-imperative/app/theme.ts

@@ -0,0 +1,66 @@
+import { useColorScheme } from 'react-native'
+
+/**
+ * The Stone.js brand, "Obsidienne & Braise", as values a StyleSheet can use.
+ *
+ * The same palette the web starters paint in CSS custom properties. A native application has no
+ * cascade, so the tokens are plain values and the screen reads them through `useStoneTheme`.
+ */
+export interface StoneTheme {
+  /** The page ground. */
+  ink: string
+  /** The glow at the top of the ground, behind the mark. */
+  inkGlow: string
+  /** Primary text. */
+  cream: string
+  /** Secondary text. */
+  creamDim: string
+  /** The ember gradient, light end. Also the accent for small text. */
+  ember1: string
+  /** The ember gradient, dark end. */
+  ember2: string
+  /** Hairlines and card borders. */
+  line: string
+  /** Card and pill surfaces. */
+  card: string
+  /** The mark's two arcs. */
+  mark: string
+}
+
+const dark: StoneTheme = {
+  ink: '#14110F',
+  inkGlow: '#241C17',
+  cream: '#F4EFE6',
+  creamDim: '#A69A8C',
+  ember1: '#FFC46B',
+  ember2: '#FF5A1F',
+  line: 'rgba(244, 239, 230, 0.10)',
+  card: 'rgba(244, 239, 230, 0.05)',
+  mark: '#E2D9CC'
+}
+
+const light: StoneTheme = {
+  ink: '#F4EFE6',
+  inkGlow: '#FFFFFF',
+  cream: '#1B1613',
+  creamDim: '#6B6154',
+  // On a light ground the ember needs the darker end to stay readable, per the brand's
+  // contrast notes: `braise.clair` for large elements, `braise.texte` for small text.
+  ember1: '#E04E10',
+  ember2: '#A83A08',
+  line: 'rgba(27, 22, 19, 0.12)',
+  card: 'rgba(27, 22, 19, 0.04)',
+  mark: '#1B1613'
+}
+
+/**
+ * The palette matching the device's appearance.
+ *
+ * Dark is the default, as in the web starters: `useColorScheme` returns `null` when the platform
+ * expresses no preference, and the brand's ground is obsidian.
+ *
+ * @returns The active theme.
+ */
+export function useStoneTheme (): StoneTheme {
+  return useColorScheme() === 'light' ? light : dark
+}

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

@@ -0,0 +1,32 @@
+{
+  "expo": {
+    "name": "Stone.js",
+    "slug": "basic-react-native-imperative",
+    "scheme": "stone",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "automatic",
+    "backgroundColor": "#14110F",
+    "splash": {
+      "image": "./assets/splash-icon.png",
+      "resizeMode": "contain",
+      "backgroundColor": "#14110F"
+    },
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#14110F",
+        "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-imperative/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-imperative/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Platform polyfills come first, before anything from Stone.js loads.
+ *
+ * - React Native's built-in `URL` is a stub (no `pathname`, no `searchParams`), and the router
+ *   reads `pathname` on every event, so the polyfill is required rather than nice to have.
+ * - `TextEncoder` is installed only when the engine does not provide it (older Hermes).
+ */
+import 'react-native-url-polyfill/auto'
+
+if (typeof globalThis.TextEncoder === 'undefined') {
+  require('fast-text-encoding')
+}
+
+import { stoneApp } from '@stone-js/core'
+import { registerRootComponent } from 'expo'
+import App from './App'
+
+/**
+ * Every module under `app/`, collected at build time.
+ *
+ * Generated by `withStone` in `metro.config.js`, because collecting modules is a bundler question
+ * and Metro has no `import.meta.glob`. Never edit it, never commit it.
+ */
+import { modules } from './.stone/modules'
+
+// Boot the framework, then hand the root component to Expo. `registerRootComponent` works the same
+// in Expo Go and in a native build.
+void stoneApp({ modules }).run()
+
+registerRootComponent(App)

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

@@ -0,0 +1,13 @@
+const { getDefaultConfig } = require('expo/metro-config')
+const { withStone } = require('@stone-js/use-react-native/metro')
+
+/**
+ * `withStone` collects every module under `app/` and writes `.stone/modules.ts` before Metro
+ * bundles, because Metro resolves imports statically and has no `import.meta.glob`. It hooks in
+ * here rather than in a command on purpose: Metro loads this file whatever started it, so
+ * `expo start`, `expo run:ios` and an EAS build all get the generation without anyone asking.
+ *
+ * Pinning the project root also keeps Metro scoped to this starter, even when it lives inside a
+ * larger workspace, as it does in the Stone.js monorepo.
+ */
+module.exports = withStone(getDefaultConfig(__dirname), __dirname)

package/basic-react-native-imperative/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "basic-react-native-imperative",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Stone.js's basic starter to create a React Native (Expo) app using the imperative API.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "main": "index.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "start": "expo start",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "export": "expo export",
+    "modules": "node -e \"require('@stone-js/use-react-native/metro').writeManifest(process.cwd())\"",
+    "typecheck": "npm run modules && tsc --noEmit",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage"
+  },
+  "dependencies": {
+    "@stone-js/browser-core": "^0.8.13",
+    "@stone-js/core": "^0.8.13",
+    "@stone-js/react-native-adapter": "^0.8.13",
+    "@stone-js/router": "^0.8.13",
+    "@stone-js/use-react-native": "^0.8.13",
+    "expo": "~57.0.14",
+    "expo-status-bar": "~57.0.1",
+    "fast-text-encoding": "^1.0.6",
+    "react": "19.2.3",
+    "react-native": "0.86.2",
+    "react-native-url-polyfill": "^3.0.0"
+  },
+  "devDependencies": {
+    "@babel/plugin-proposal-decorators": "^7.28.0",
+    "@stone-js/cli": "^0.8.13",
+    "@stone-js/testing": "^0.8.13",
+    "@types/react": "~19.2.2",
+    "@vitest/coverage-v8": "^3.0.9",
+    "babel-preset-expo": "^57.0.7",
+    "typescript": "~6.0.3",
+    "vitest": "^3.0.9"
+  }
+}