@_linked/cli 1.13.0 → 1.15.0

package/defaults/app-react-native/apps/mobile/__tests__/integration/globalSetup.ts

@@ -0,0 +1,160 @@
+/// <reference types="node" />
+// Before the integration tests: check that the target is this repo's Compose Fuseki, reset the in-memory test
+// dataset, start the API-only backend.
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+import {
+  API_PORT,
+  API_URL,
+  FUSEKI_DATASET,
+  apiDir,
+  describeComposePortFailure,
+  readApiEnvFile,
+  repoRoot,
+  resolveFusekiEnv,
+} from './apiEnv';
+
+// The variables that select S3FileStore (services/api/src/fileStoreEnv.ts); blanked even when unset anywhere.
+const S3_ENV_KEYS = ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION', 'S3_BUCKET_ENDPOINT', 'S3_FILES_BUCKET_NAME'];
+
+// Test hooks: INTEGRATION_API_BIN replaces `linked` (e.g. with a process that never answers) and
+// INTEGRATION_API_TIMEOUT_MS shortens the wait, to exercise the failure cleanup.
+const apiBin = process.env.INTEGRATION_API_BIN || resolve(repoRoot, 'node_modules/.bin/linked');
+const startTimeoutMs = Number(process.env.INTEGRATION_API_TIMEOUT_MS) || 60_000;
+
+async function answers(url: string): Promise<boolean> {
+  try {
+    await fetch(url, { signal: AbortSignal.timeout(1000) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refuses unless the target is safe to wipe: the dataset name ends in `-test`, and the Fuseki URL is on localhost at
+ * the host port Docker Compose publishes for this repo's `fuseki` service (so never another project's Fuseki).
+ */
+function assertSafeTarget(baseUrl: string) {
+  const target = `${baseUrl}/$/datasets/${FUSEKI_DATASET}`;
+  const refuse = (reason: string): never => {
+    throw new Error(`Refusing to reset ${target}: ${reason}`);
+  };
+  if (!FUSEKI_DATASET.endsWith('-test')) refuse('the dataset name does not end in "-test".');
+
+  const url = new URL(baseUrl);
+  if (!['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) refuse(`${url.hostname} is not localhost.`);
+  const urlPort = url.port || (url.protocol === 'https:' ? '443' : '80');
+
+  const compose = spawnSync('docker', ['compose', 'port', 'fuseki', '3030'], { cwd: repoRoot, encoding: 'utf8' });
+  const composePort = compose.status === 0 ? /:(\d+)\s*$/.exec(compose.stdout.trim())?.[1] : undefined;
+  if (!composePort) refuse(describeComposePortFailure(compose));
+  if (composePort !== urlPort) {
+    refuse(`port ${urlPort} is not the Compose Fuseki port ${composePort}. Set FUSEKI_PORT=${composePort}.`);
+  }
+}
+
+/** Kills the API's whole process group; safe to call repeatedly and after it exited. */
+function killGroup(api: ChildProcess, signal: NodeJS.Signals = 'SIGTERM') {
+  if (!api.pid) return;
+  try {
+    process.kill(-api.pid, signal);
+  } catch {
+    // Already gone.
+  }
+}
+
+export default async function globalSetup() {
+  const fuseki = resolveFusekiEnv();
+
+  // 1. Refuse a foreign target before anything is deleted.
+  assertSafeTarget(fuseki.baseUrl);
+
+  // 2. Fail fast when Fuseki is down. FUSEKI_BASE_URL is passed so the script does not read services/api/.env.
+  const wait = spawnSync(process.execPath, [resolve(apiDir, 'scripts/wait-for-fuseki.mjs')], {
+    env: { ...process.env, FUSEKI_BASE_URL: fuseki.baseUrl },
+    encoding: 'utf8',
+  });
+  if (wait.status !== 0) throw new Error(wait.stderr.trim() || `wait-for-fuseki exited ${wait.status}`);
+
+  if (await answers(API_URL)) {
+    throw new Error(`Port ${API_PORT} is already in use; stop the process on it before running integration tests.`);
+  }
+
+  // 3. Reset: drop the dataset; the API's ensureDatasetExists() recreates it empty on boot.
+  const auth = `Basic ${Buffer.from(`${fuseki.user}:${fuseki.password}`).toString('base64')}`;
+  const del = await fetch(`${fuseki.baseUrl}/$/datasets/${FUSEKI_DATASET}`, {
+    method: 'DELETE',
+    headers: { Authorization: auth },
+  });
+  if (!del.ok && del.status !== 404) {
+    throw new Error(`Deleting Fuseki dataset ${FUSEKI_DATASET} failed: ${del.status} ${await del.text()}`);
+  }
+
+  // 4. Start the API. Every Fuseki variable is explicit, and the S3 ones are blanked, so nothing is taken from
+  // services/api/.env (`linked start` does not override variables that are already set, even when empty).
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  const s3Keys = [...Object.keys(process.env), ...Object.keys(readApiEnvFile()), ...S3_ENV_KEYS];
+  for (const key of s3Keys) if (/^(AWS|S3)_/.test(key)) env[key] = '';
+  // Except AWS_REGION: @_linked/s3 builds a client at import with `AWS_REGION ?? 'us-east-1'`, and an empty region
+  // throws "Region is missing". Removed instead; the blank S3_FILES_BUCKET_NAME already rules out S3FileStore.
+  delete env.AWS_REGION;
+  Object.assign(env, {
+    NODE_ENV: 'development',
+    PORT: String(API_PORT),
+    SITE_ROOT: API_URL,
+    DATA_ROOT: `${API_URL}/data`,
+    FUSEKI_BASE_URL: fuseki.baseUrl,
+    FUSEKI_USER: fuseki.user,
+    FUSEKI_PASSWORD: fuseki.password,
+    FUSEKI_DATASET,
+    FUSEKI_DB_TYPE: 'mem',
+  });
+
+  let output = '';
+  const api = spawn(apiBin, ['start', '--api-only'], {
+    cwd: apiDir,
+    env,
+    // `linked start` spawns its own children (Vite, the server). `detached` gives the CLI its own process group, so
+    // one `kill(-pid)` stops all of them; killing only the CLI's PID would leave the server listening on the port.
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  api.stdout?.on('data', (d) => (output += d));
+  api.stderr?.on('data', (d) => (output += d));
+  let exited: number | null = null;
+  api.on('exit', (code) => (exited = code ?? -1));
+
+  // A detached group outlives Jest unless it is killed: on exit, Ctrl+C and SIGTERM too, not only in teardown.
+  const onExit = () => killGroup(api, 'SIGKILL');
+  const onSignal = (signal: NodeJS.Signals) => {
+    killGroup(api);
+    // Re-raise when no one else handles it, so the default (terminate) still happens.
+    if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+  };
+  process.once('exit', onExit);
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  const stop = () => {
+    process.off('exit', onExit);
+    process.off('SIGINT', onSignal);
+    process.off('SIGTERM', onSignal);
+    killGroup(api);
+  };
+  (globalThis as any).__LINKED_API__ = { api, stop, killGroup: (signal: NodeJS.Signals) => killGroup(api, signal) };
+
+  const fail = (message: string): never => {
+    stop();
+    throw new Error(message);
+  };
+
+  // 5. Wait until it answers HTTP (page routes 404, which is fine).
+  const deadline = Date.now() + startTimeoutMs;
+  while (Date.now() < deadline) {
+    if (exited !== null) fail(`The API exited with ${exited} before it answered:\n${output}`);
+    if (await answers(API_URL)) return;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  fail(`The API did not answer on ${API_URL} within ${startTimeoutMs / 1000} s:\n${output}`);
+}

package/defaults/app-react-native/apps/mobile/__tests__/integration/globalTeardown.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+// Stops the API started by globalSetup (its whole process group) and removes its exit and signal handlers.
+import type { ChildProcess } from 'node:child_process';
+
+type StartedApi = { api: ChildProcess; stop: () => void; killGroup: (signal: NodeJS.Signals) => void };
+
+export default async function globalTeardown() {
+  const started: StartedApi | undefined = (globalThis as any).__LINKED_API__;
+  if (!started) return;
+  const { api, stop, killGroup } = started;
+  if (!api.pid || api.exitCode !== null || api.signalCode !== null) {
+    stop();
+    return;
+  }
+  const exited = new Promise((r) => api.once('exit', r));
+  stop();
+  const timer = setTimeout(() => killGroup('SIGKILL'), 5000);
+  await exited;
+  clearTimeout(timer);
+}

package/defaults/app-react-native/apps/mobile/__tests__/integration/nodeFetchEnvironment.js

@@ -0,0 +1,13 @@
+// The react-native test environment (jest-environment-node) with Node's own fetch saved before any setup file
+// runs. jest-expo's setup and `expo`'s winter runtime replace globalThis.fetch with `expo/fetch`, whose native
+// module jest-expo stubs (it never sends a request). restoreNodeFetch.ts puts Node's fetch back.
+const ReactNativeEnv = require('@react-native/jest-preset/jest/react-native-env.js');
+
+const FETCH_GLOBALS = ['fetch', 'Headers', 'Request', 'Response', 'FormData'];
+
+module.exports = class NodeFetchEnvironment extends ReactNativeEnv {
+  constructor(config, context) {
+    super(config, context);
+    this.global.__NODE_FETCH_GLOBALS__ = Object.fromEntries(FETCH_GLOBALS.map((name) => [name, globalThis[name]]));
+  }
+};

package/defaults/app-react-native/apps/mobile/__tests__/integration/personOverview.test.tsx

@@ -0,0 +1,51 @@
+// The example PersonOverview screen with the real BackendAPIStore and real fetch, against the API started by
+// globalSetup on the reset app-test dataset: list 0, add (1), edit (the name changes and persists), delete (0).
+import '@_linked/react/native';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react-native';
+
+import { PersonOverview } from '../../src/components/PersonOverview';
+import { API_URL } from './apiEnv';
+
+// env.ts resolves the API URL from Expo's config; point it at the test API. (jest.mock is hoisted above imports.)
+jest.mock('expo-constants', () => ({
+  __esModule: true,
+  default: { expoConfig: { extra: { apiUrl: 'http://localhost:4100', apiPort: 4000 } } },
+}));
+
+const WAIT = { timeout: 10000 };
+
+describe('PersonOverview against the API', () => {
+  it('uses the test API and a real fetch', () => {
+    expect(process.env.SITE_ROOT).toBe(API_URL);
+    // Node's fetch, not jest-expo's stubbed expo/fetch (see nodeFetchEnvironment.js).
+    expect(globalThis.fetch).toBe((globalThis as any).__NODE_FETCH_GLOBALS__.fetch);
+  });
+
+  it('lists 0, adds one (1), edits it, deletes it (0)', async () => {
+    await render(<PersonOverview />);
+    await waitFor(() => expect(screen.getByTestId('person-empty')).toBeOnTheScreen(), WAIT);
+
+    // Add
+    await fireEvent.changeText(screen.getByTestId('person-add-given'), 'Ada');
+    await fireEvent.changeText(screen.getByTestId('person-add-family'), 'Lovelace');
+    await fireEvent.press(screen.getByTestId('person-add'));
+    await waitFor(() => expect(screen.getAllByTestId('person-row')).toHaveLength(1), WAIT);
+    await waitFor(() => expect(screen.getByTestId('person-name')).toHaveTextContent('Ada Lovelace'), WAIT);
+
+    // Edit
+    await fireEvent.press(screen.getByTestId('person-edit-button'));
+    await fireEvent.changeText(screen.getByTestId('person-edit-given'), 'Grace');
+    await fireEvent.press(screen.getByTestId('person-save'));
+    await waitFor(() => expect(screen.getByTestId('person-name')).toHaveTextContent('Grace Lovelace'), WAIT);
+
+    // The edit is stored, not only patched locally: a fresh mount reads it back from the API.
+    await screen.unmount();
+    await render(<PersonOverview />);
+    await waitFor(() => expect(screen.getByTestId('person-name')).toHaveTextContent('Grace Lovelace'), WAIT);
+
+    // Delete
+    await fireEvent.press(screen.getByTestId('person-delete'));
+    await waitFor(() => expect(screen.getByTestId('person-empty')).toBeOnTheScreen(), WAIT);
+    expect(screen.queryAllByTestId('person-row')).toHaveLength(0);
+  });
+});

package/defaults/app-react-native/apps/mobile/__tests__/integration/restoreNodeFetch.ts

@@ -0,0 +1,8 @@
+// Runs after the setup files: installs expo's winter runtime first (it swaps in a stubbed `expo/fetch`), then
+// restores Node's fetch globals saved by nodeFetchEnvironment.js, so BackendAPIStore reaches the real API.
+require('expo');
+
+const saved: Record<string, unknown> = (globalThis as any).__NODE_FETCH_GLOBALS__;
+for (const [name, value] of Object.entries(saved)) {
+  Object.defineProperty(globalThis, name, { value, configurable: true, writable: true, enumerable: true });
+}

package/defaults/app-react-native/apps/mobile/__tests__/{linkedDefaults.test.tsx → nativeDefaults.test.tsx}

@@ -1,12 +1,10 @@
-// Asserts the cause of the React Native crash in @_linked/react's default loader and error
-// elements: they render DOM host elements (<svg>), which have no native view config.
-// Removing the import below must make both tests fail with Received: ["svg", ...].
-import '../src/shell/linkedDefaults';
-
+// Asserts the cause of the React Native crash in @_linked/react's root loader and error elements: they render
+// DOM host elements (<svg>), which have no native view config. @_linked/react/native replaces them on import;
+// importing linkedComponent from the root barrel instead must make both tests fail with Received: ["svg", ...].
 import { act, render, screen } from '@testing-library/react-native';
 import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
 import { setQueryDispatch } from '@_linked/core/queries/queryDispatch';
-import { linkedComponent } from '@_linked/react';
+import { linkedComponent } from '@_linked/react/native';
 import { Text } from 'react-native';
 import { Example } from 'app-shapes';
 
@@ -44,7 +42,7 @@ function lowercaseHostTypes(tree: Node | Node[] | null): string[] {
 
 const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
 
-describe('Linked render defaults on React Native', () => {
+describe('@_linked/react/native render defaults', () => {
   test('a loading component renders only React Native elements', async () => {
     mode = 'loading';
     await render(<ExampleLabel of={{ id: 'urn:example:1' }} />);

package/defaults/app-react-native/apps/mobile/__tests__/storage.test.ts

@@ -0,0 +1,24 @@
+// Importing storage alone must be enough: it pulls ./env, so SITE_ROOT is set before BackendAPIStore is constructed.
+jest.mock('expo-constants', () => ({
+  __esModule: true,
+  default: { expoConfig: { extra: { apiUrl: 'http://api.test:9000', apiPort: 4000 } } },
+}));
+
+const constructedWith: (string | undefined)[] = [];
+jest.mock('@_linked/server/shapes/quadstores/BackendAPIStore', () => ({
+  BackendAPIStore: class {
+    constructor() {
+      constructedWith.push(process.env.SITE_ROOT);
+    }
+  },
+}));
+
+test('importing src/shell/storage sets SITE_ROOT before BackendAPIStore is constructed', () => {
+  delete process.env.SITE_ROOT;
+  delete process.env.DATA_ROOT;
+
+  require('../src/shell/storage');
+
+  expect(constructedWith).toEqual(['http://api.test:9000']);
+  expect(process.env.DATA_ROOT).toBe('http://api.test:9000/data');
+});

package/defaults/app-react-native/apps/mobile/__tests__/stripJsonImportAttributes.test.ts

@@ -0,0 +1,45 @@
+import { transformSync } from '@babel/core';
+
+import stripJsonImportAttributes from '../babel/stripJsonImportAttributes';
+
+const transform = (code: string, withPlugin = true, parserOpts: Record<string, unknown> = {}) =>
+  transformSync(code, {
+    babelrc: false,
+    configFile: false,
+    parserOpts,
+    plugins: withPlugin ? [stripJsonImportAttributes] : [],
+  })!.code;
+
+// The plugin must produce exactly what Babel prints without it.
+const expectUnchanged = (code: string) => expect(transform(code)).toBe(transform(code, false));
+
+describe('stripJsonImportAttributes', () => {
+  test('drops the options of a dynamic JSON import', () => {
+    expect(transform("import('./a.json', { with: { type: 'json' } });")).toBe("import('./a.json');");
+  });
+
+  test('handles a template literal specifier', () => {
+    expect(transform("import(`./a.json`, { with: { type: 'json' } });")).toBe('import(`./a.json`);');
+  });
+
+  test('handles ImportExpression nodes (createImportExpressions)', () => {
+    const code = "import('./a.json', { with: { type: 'json' } });";
+    expect(transform(code, true, { createImportExpressions: true })).toBe("import('./a.json');");
+  });
+
+  test('leaves a non-JSON dynamic import unchanged', () => {
+    expectUnchanged("import('./a.js', { x: 1 });");
+    expect(transform("import('./a.js', { x: 1 });")).toContain('x: 1');
+  });
+
+  test('leaves a non-literal specifier unchanged', () => {
+    expectUnchanged("import(variable, { with: { type: 'json' } });");
+    expect(transform("import(variable, { with: { type: 'json' } });")).toContain("type: 'json'");
+  });
+
+  test('leaves a static JSON import with attributes unchanged', () => {
+    const code = "import d from './d.json' with { type: 'json' };";
+    expectUnchanged(code);
+    expect(transform(code)).toContain("with { type: 'json' }");
+  });
+});

package/defaults/app-react-native/apps/mobile/app.config.ts

@@ -0,0 +1,21 @@
+import type { ConfigContext, ExpoConfig } from 'expo/config';
+
+// The default API port lives in src/shell/apiPort.json (services/api/.env.example PORT), shared with env.ts. JSON,
+// because Expo's config loader cannot import a TypeScript module.
+import { defaultApiPort } from './src/shell/apiPort.json';
+
+// src/shell/env.ts combines the API port with the dev machine's host when EXPO_PUBLIC_API_URL is not set, so the
+// Simulator and a device on the LAN both work.
+const API_PORT = defaultApiPort;
+
+// The static app identity (name, slug, bundle identifier) stays in app.json; Expo passes it in as `config`.
+export default ({ config }: ConfigContext): ExpoConfig => ({
+  ...config,
+  name: config.name ?? 'App',
+  slug: config.slug ?? 'app',
+  extra: {
+    ...config.extra,
+    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? null,
+    apiPort: API_PORT,
+  },
+});

package/defaults/app-react-native/apps/mobile/babel/stripJsonImportAttributes.js

@@ -0,0 +1,41 @@
+/**
+ * Babel plugin: drop import attributes from dynamic `import()` of JSON files.
+ *
+ * Linked ontology packages load their data with
+ *   import('../data/x.json', { with: { type: 'json' } })
+ * Node requires the attribute for JSON, so the packages keep it. Metro's dependency collector rejects any
+ * `import()` with more than one argument ("Invalid call at line N"). This plugin removes the options argument
+ * when the specifier is a static string ending in `.json`, so Metro bundles it as an ordinary async JSON module.
+ * Everything else, including static `import x from './a.json' with { type: 'json' }`, is left untouched.
+ */
+
+function staticSpecifier(node) {
+  if (!node) return null;
+  if (node.type === 'StringLiteral') return node.value;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) return node.quasis[0].value.cooked;
+  return null;
+}
+
+const isJson = (specifier) => typeof specifier === 'string' && /\.json$/i.test(specifier);
+
+module.exports = function stripJsonImportAttributes() {
+  return {
+    name: 'strip-json-import-attributes',
+    visitor: {
+      // Default parser output (what Metro and babel-preset-expo use): `import(...)` is a CallExpression with an
+      // `Import` callee.
+      CallExpression(path) {
+        const { callee, arguments: args } = path.node;
+        if (callee.type !== 'Import' || args.length < 2) return;
+        if (!isJson(staticSpecifier(args[0]))) return;
+        path.node.arguments = [args[0]];
+      },
+      // With the parser option `createImportExpressions`, it is an ImportExpression with `source` and `options`.
+      ImportExpression(path) {
+        const { node } = path;
+        if (!node.options || !isJson(staticSpecifier(node.source))) return;
+        node.options = null;
+      },
+    },
+  };
+};

package/defaults/app-react-native/apps/mobile/babel.config.js

@@ -0,0 +1,13 @@
+// Metro passes this file as `extends` for every module it transforms, node_modules included (so @_linked/*), and
+// Jest (jest-expo) picks it up too. No root babel.config.js is needed: Metro's Babel root is apps/mobile.
+module.exports = function (api) {
+  // Cached for the process lifetime and in Metro's transform cache: after editing this file (or the plugin),
+  // restart with `npx expo start --clear`.
+  api.cache(true);
+  return {
+    // babel-preset-expo is installed nested under expo; resolve it from there, as Expo's own default config does.
+    presets: [require.resolve('babel-preset-expo', { paths: [require.resolve('expo/package.json')] })],
+    // Metro rejects `import('x.json', { with: { type: 'json' } })`, used by every Linked ontology package.
+    plugins: [require.resolve('./babel/stripJsonImportAttributes')],
+  };
+};

package/defaults/app-react-native/apps/mobile/jest.integration.config.js

@@ -0,0 +1,16 @@
+// Integration tests against a real API and Fuseki: `npm run fuseki:up && npm run test:integration`.
+// Same preset, transforms and module mapping as the unit config in package.json. jest-expo replaces the global
+// fetch with a stubbed `expo/fetch` that never sends a request (it is not a jest mock), so the environment saves
+// Node's fetch and restoreNodeFetch.ts reinstates it.
+const { jest: unitConfig } = require('./package.json');
+
+module.exports = {
+  ...unitConfig,
+  testMatch: ['<rootDir>/__tests__/integration/**/*.test.[jt]s?(x)'],
+  testPathIgnorePatterns: ['/node_modules/'],
+  testEnvironment: '<rootDir>/__tests__/integration/nodeFetchEnvironment.js',
+  setupFilesAfterEnv: ['<rootDir>/__tests__/integration/restoreNodeFetch.ts'],
+  globalSetup: '<rootDir>/__tests__/integration/globalSetup.ts',
+  globalTeardown: '<rootDir>/__tests__/integration/globalTeardown.ts',
+  testTimeout: 30000,
+};

package/defaults/app-react-native/apps/mobile/package.json

@@ -7,13 +7,17 @@
     "start": "expo start",
     "ios": "expo run:ios",
     "android": "expo run:android",
-    "test": "jest"
+    "test": "jest",
+    "test:integration": "jest -c jest.integration.config.js --runInBand"
   },
   "dependencies": {
-    "@_linked/core": "2.18.0",
-    "@_linked/react": "1.4.2",
+    "@_linked/core": "2.18.1",
+    "@_linked/react": "1.5.0",
+    "@_linked/schema": "1.1.2",
+    "@_linked/server": "2.3.0",
     "app-shapes": "*",
     "expo": "57.0.22",
+    "expo-constants": "57.0.18",
     "expo-dev-client": "57.0.19",
     "react": "19.2.3",
     "react-native": "0.86.3"
@@ -30,6 +34,10 @@
   },
   "jest": {
     "preset": "jest-expo",
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "<rootDir>/__tests__/integration/"
+    ],
     "transformIgnorePatterns": [
       "node_modules/(?!((jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@unimodules/.*|unimodules|sentry-expo|native-base|react-native-svg|@_linked/.*|app-shapes))"
     ],

package/defaults/app-react-native/apps/mobile/src/components/PersonOverview.tsx

@@ -0,0 +1,123 @@
+// Example PersonOverview — demonstrates @_linked/react's data binding:
+// linkedSetComponent for the list (auto-runs the query, injects results and
+// an injected _refresh); linkedComponent for each row (see PersonPreview).
+// After Person.create the form calls _refresh() to re-run the list query.
+// A React Native port of the web app-template's example (linked-cm/app-template).
+//
+// `linkedSetComponent` checks LinkedStorage when this module loads, so storage is imported first.
+// Replace or extend this with your own shapes (see https://linked.cm).
+import '../shell/storage';
+
+import React, { useCallback, useRef, useState } from 'react';
+import { Pressable, StyleSheet, Text, TextInput, View } from 'react-native';
+import { linkedSetComponent } from '@_linked/react';
+import { Person } from '@_linked/schema/shapes/Person';
+import { PersonPreview } from './PersonPreview';
+import { PersonListRefreshProvider } from './PersonOverviewContext';
+
+const PersonList = linkedSetComponent(
+  Person.select((p) => [p.givenName, p.familyName]),
+  ({ linkedData = [], _refresh, refreshRef }: any) => {
+    // Forward the list's _refresh up via a ref so the sibling form +
+    // child rows can trigger a re-fetch through context.
+    if (refreshRef) {
+      refreshRef.current = _refresh;
+    }
+
+    if (linkedData.length === 0) {
+      return (
+        <Text style={styles.empty} testID="person-empty">
+          No people yet. Add one below.
+        </Text>
+      );
+    }
+
+    return (
+      <View style={styles.list} testID="person-list">
+        {linkedData.map((p: { id: string }) => (
+          <PersonPreview key={p.id} of={{ id: p.id }} />
+        ))}
+      </View>
+    );
+  },
+);
+
+function PersonAddForm({ onAdded }: { onAdded: () => void }) {
+  const [given, setGiven] = useState('');
+  const [family, setFamily] = useState('');
+  const [busy, setBusy] = useState(false);
+
+  async function submit() {
+    if (!given && !family) return;
+    setBusy(true);
+    try {
+      await Person.create({ givenName: given, familyName: family });
+      setGiven('');
+      setFamily('');
+      onAdded();
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <View style={styles.form}>
+      <TextInput
+        style={styles.input}
+        value={given}
+        placeholder="First name"
+        onChangeText={setGiven}
+        testID="person-add-given"
+      />
+      <TextInput
+        style={styles.input}
+        value={family}
+        placeholder="Last name"
+        onChangeText={setFamily}
+        testID="person-add-family"
+      />
+      <Pressable style={styles.button} onPress={submit} disabled={busy} testID="person-add">
+        <Text style={styles.buttonText}>Add</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+export function PersonOverview() {
+  const refreshRef = useRef<() => void>(() => {});
+  const refresh = useCallback(() => refreshRef.current(), []);
+
+  return (
+    <PersonListRefreshProvider value={refresh}>
+      <View style={styles.root} testID="person-overview">
+        <Text style={styles.title}>People</Text>
+        <Text style={styles.intro}>
+          Example code using the @_linked query DSL against your local Fuseki dataset. Edit
+          src/components/PersonOverview.tsx to extend it.
+        </Text>
+        <PersonList refreshRef={refreshRef} />
+        <PersonAddForm onAdded={refresh} />
+      </View>
+    </PersonListRefreshProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { alignSelf: 'stretch', padding: 16, gap: 12 },
+  title: { fontSize: 22, fontWeight: '600' },
+  intro: { color: '#555' },
+  empty: { color: '#888', fontStyle: 'italic' },
+  list: { gap: 8 },
+  form: { flexDirection: 'row', flexWrap: 'wrap', gap: 8, alignItems: 'center' },
+  input: {
+    flexGrow: 1,
+    minWidth: 100,
+    borderWidth: 1,
+    borderColor: '#ccc',
+    borderRadius: 6,
+    paddingHorizontal: 8,
+    paddingVertical: 6,
+  },
+  button: { backgroundColor: '#222', borderRadius: 6, paddingHorizontal: 14, paddingVertical: 8 },
+  buttonText: { color: '#fff', fontWeight: '600' },
+});

package/defaults/app-react-native/apps/mobile/src/components/PersonOverviewContext.tsx

@@ -0,0 +1,12 @@
+// Small context that lets PersonPreview rows trigger a list refresh on
+// their parent PersonOverview without prop-drilling through the
+// linkedSetComponent's wrapped renderer.
+import React, { useContext } from 'react';
+
+const PersonListRefreshContext = React.createContext<() => void>(() => {});
+
+export const PersonListRefreshProvider = PersonListRefreshContext.Provider;
+
+export function usePersonListRefresh(): () => void {
+  return useContext(PersonListRefreshContext);
+}