@_linked/react 0.0.1

package/.context/jest-repro-bundler.config.js

@@ -0,0 +1,20 @@
+/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  rootDir: '../src/tests',
+  testMatch: ['**/*.test.ts', '**/*.test.tsx'],
+  transform: {
+    '^.+\\.(ts|tsx)$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/../../.context/tsconfig-repro-bundler.json',
+      },
+    ],
+  },
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@_linked/react/(.*)$': '<rootDir>/../$1',
+    '^@_linked/react$': '<rootDir>/../index',
+  },
+};

package/.context/jest-repro.config.js

@@ -0,0 +1,20 @@
+/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  rootDir: '../src/tests',
+  testMatch: ['**/*.test.ts', '**/*.test.tsx'],
+  transform: {
+    '^.+\\.(ts|tsx)$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/../../.context/tsconfig-repro-node-modules-paths.json',
+      },
+    ],
+  },
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@_linked/react/(.*)$': '<rootDir>/../$1',
+    '^@_linked/react$': '<rootDir>/../index',
+  },
+};

package/.context/tsconfig-repro-bundler.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "../",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "paths": {
+      "@_linked/react": ["./src/index"],
+      "@_linked/react/*": ["./src/*"]
+    }
+  },
+  "include": ["../src/**/*.ts", "../src/**/*.tsx"],
+  "exclude": []
+}

package/.context/tsconfig-repro-no-paths.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "../",
+    "paths": {
+      "@_linked/react": ["./src/index"],
+      "@_linked/react/*": ["./src/*"]
+    }
+  },
+  "include": ["../src/tests/react-component-integration.test.tsx"],
+  "exclude": []
+}

package/.context/tsconfig-repro-node-modules-paths.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "../",
+    "paths": {
+      "@_linked/core": ["./node_modules/@_linked/core/lib/esm/index.d.ts"],
+      "@_linked/core/*": ["./node_modules/@_linked/core/lib/esm/*"],
+      "@_linked/rdf-mem-store": ["./node_modules/@_linked/rdf-mem-store/lib/esm/index.d.ts"],
+      "@_linked/rdf-mem-store/*": ["./node_modules/@_linked/rdf-mem-store/lib/esm/*"],
+      "@_linked/react": ["./src/index"],
+      "@_linked/react/*": ["./src/*"]
+    }
+  },
+  "include": ["../src/tests/react-component-integration.test.tsx"],
+  "exclude": []
+}

package/.context/tsconfig-repro-node16.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "../",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "paths": {
+      "@_linked/react": ["./src/index"],
+      "@_linked/react/*": ["./src/*"]
+    }
+  },
+  "include": ["../src/tests/react-component-integration.test.tsx"],
+  "exclude": []
+}

package/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md — @_linked/react repository
+
+## Repository structure
+
+Single-package repository for `@_linked/react` (React bindings such as `linkedComponent` and `linkedSetComponent`). Runtime dependency target is `@_linked/core`; tests may also use `@_linked/rdf-mem-store`.
+
+Tests: `npm test`
+
+## Agent docs (`docs/`)
+
+Files are numbered with a 3-digit prefix for ordering. Names should be explicit about contents (lowercase-dash format). Every file starts with YAML frontmatter:
+
+```yaml
+---
+summary: One-line description of what this document covers
+packages: [core, react]
+---
+```
+
+```bash
+ls docs/                # list all docs
+head -4 docs/*.md       # get summaries (or replace * with a specific file)
+```
+
+Each package also has a `README.md` with API docs and a `## Changelog` at the bottom.
+
+## Planning and implementation workflow
+
+### When to plan
+
+Any task that requires significant code changes requires a plan. Simple checks, info gathering, and discussions do not. If it's not clear (small code changes), ask the user if he wants to plan first.
+
+### Creating a plan
+
+1. **Inspect the relevant code thoroughly** before writing anything. Read the source files, tests, and existing docs that relate to the task.
+2. Create a new doc in `docs/` with the next 3-digit prefix (e.g. `005-add-filter-support.md`). Start with YAML frontmatter.
+3. Write the plan with these sections:
+   - **Key considerations and choices** — tradeoffs, open questions, alternatives
+   - **Potential problems** — what could go wrong, edge cases
+   - **Phases** — ordered list of implementation steps. Each phase has a clear scope and describes how it will be validated. Small tasks: 1-2 phases. Larger tasks: more.
+4. **Ask the user to review the plan before implementing.**
+
+### Implementing phases
+
+- **One commit per phase.** Include the plan doc update (marking the phase complete) in the same commit.
+- **Every phase must be validated** — at minimum one relevant passing test.
+- **After each phase, report to the user:**
+  - What was done
+  - Any deviations from the plan
+  - Problems encountered
+  - Validation results (pass/fail counts and what was tested)
+  - What you plan to do next
+
+### Wrapping up
+
+Before committing final changes or preparing a PR:
+
+1. **Consolidate the plan doc** — collapse alternatives into the choices that were made, summarize implementation details and breaking changes, keep a brief problems section if relevant, remove anything redundant for future readers.
+2. **Update `## Changelog`** in each affected package's `README.md` — user-facing entry covering behavior changes, new APIs, breaking changes, and migration steps.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Semantu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# @_linked/react
+
+React bindings for `@_linked/core`.
+
+`@_linked/react` takes a Linked query from `@_linked/core`'s [Schema-Parameterized Query DSL](../core/README.md#schema-parameterized-query-dsl) and maps the top-level query result keys to props for a React component.
+
+This package provides:
+- `linkedComponent(...)`
+- `linkedSetComponent(...)`
+- `LinkedComponentClass`
+- `useStyles(...)`
+
+## Install
+
+```bash
+npm install @_linked/react @_linked/core react react-dom
+```
+
+## Usage
+
+### Setup package exports
+
+```tsx
+import {
+  linkedComponent,
+  linkedSetComponent,
+  linkedShape,
+} from '@_linked/react';
+```
+
+### `linkedComponent(...)`
+
+`linkedComponent(...)` wraps a React component with a Linked query. You pass a query built with `Shape.query(...)` (which prepares query execution), not `Shape.select(...)` (which executes immediately). At render time, when you pass `of={{id: ...}}`, the wrapper applies the prepared query to that subject and injects the query result keys as props into your component.
+
+```tsx
+const PersonCard = linkedComponent(
+  Person.query((p) => p.name),
+  ({name, source, _refresh}) => (
+    <article>
+      <h3>{name}</h3>
+      <small>{source.id}</small>
+      <button onClick={() => _refresh()}>Reload</button>
+    </article>
+  ),
+);
+
+// External API: pass `of` as a node reference (`{id: string}`), Shape, or QResult.
+<PersonCard of={{id: 'https://example.org/p1'}} />;
+```
+
+Props received by the wrapped component:
+- Query result props: all top-level keys from the query result become direct props (for example `name`).
+- `source`: the resolved shape instance for the input `of` subject.
+- `_refresh(updatedProps?)`: rerun the query (`_refresh()`) or patch local query-result props before rerender (`_refresh({...})`).
+- Custom props: any additional props you pass to the linked component are forwarded as normal.
+
+#### `_refresh(updatedProps?)` on linked components
+
+`_refresh` is injected into wrapped `linkedComponent(...)` render functions.
+
+- `_refresh()` reruns the query and rerenders when results return.
+- `_refresh(updatedProps)` merges `updatedProps` into current query result state and rerenders immediately (without fetching first).
+- `updatedProps` is for query result keys only (for example `name`, `active` from your query), not regular additional props passed by parents.
+
+Example use case: optimistic UI after a mutation.
+
+```tsx
+const PersonCard = linkedComponent(
+  Person.query((p) => [p.name, p.active]),
+  ({id, name, active, _refresh, title}) => (
+    <div>
+      <h4>{title}</h4>
+      <span>{name}</span>
+      <button
+        onClick={async () => {
+          // Patch query-result keys immediately (name/active/id/etc.)
+          _refresh({active: !active}); // optimistic local query-result update
+          await saveActiveFlag(id, !active); // your write call
+          _refresh(); // optional: sync with store response
+          // Not for parent custom props like `title`; those come from parent rerender.
+        }}
+      >
+        Toggle active
+      </button>
+    </div>
+  ),
+);
+```
+
+### `linkedSetComponent(...)`
+
+Use `linkedSetComponent(...)` when you want to render a list of sources.
+
+### `linkedSetComponent(...)` (direct query format)
+
+```tsx
+const NameList = linkedSetComponent(
+  Person.query((p) => p.name),
+  ({linkedData}) => (
+    <ul>
+      {(linkedData || []).map((person) => (
+        <li key={person.id}>{person.name}</li>
+      ))}
+    </ul>
+  ),
+);
+```
+
+### `linkedSetComponent(...)` (named data-prop format)
+
+```tsx
+const personQuery = Person.query((p) => [p.name, p.hobby]);
+
+const NameList = linkedSetComponent({persons: personQuery}, ({persons}) => (
+  <ul>
+    {persons.map((person) => (
+      <li key={person.id}>{person.name}</li>
+    ))}
+  </ul>
+));
+```
+
+Both formats are supported. For linked-set wrappers, the external API is also `of` (optional). Internally this becomes `sources` for the wrapped component.
+
+## Render lifecycle and loading state
+
+When `LinkedStorage` is initialized and data is not already preloaded in `of`:
+- First render: returns a loading element.
+- Query resolves: component rerenders with mapped query result props.
+- Source changes (`of` changes): prior query result is cleared and query runs again.
+
+Loading fallback is currently fixed to:
+
+```html
+<div class="ld-loader" role="status" aria-label="Loading"></div>
+```
+
+There is no API prop to replace this element today. You can style it via CSS class `.ld-loader`.
+
+## Linked set pagination API
+
+When `linkedSetComponent(...)` has a limit (explicit query limit or default limit), wrapped props include:
+- `query.nextPage()`
+- `query.previousPage()`
+- `query.setPage(pageIndex)`
+- `query.setLimit(limit)`
+
+There is no public `setOffset(...)` in the React query controller; use `setPage`, `nextPage`, or `previousPage`.
+
+Example:
+
+```tsx
+import React from 'react';
+
+const PeopleList = linkedSetComponent(
+  Person.query((p) => [p.name]).limit(5),
+  ({linkedData = [], query}) => {
+    const [page, setPage] = React.useState(0);
+
+    return (
+      <section>
+        <ul>
+          {linkedData.map((person) => (
+            <li key={person.id}>{person.name}</li>
+          ))}
+        </ul>
+
+        <div>
+          <button
+            onClick={() => {
+              query?.previousPage();
+              setPage((p) => Math.max(0, p - 1));
+            }}
+          >
+            Previous
+          </button>
+
+          <span>Page {page + 1}</span>
+
+          <button
+            onClick={() => {
+              query?.nextPage();
+              setPage((p) => p + 1);
+            }}
+          >
+            Next
+          </button>
+
+          <label>
+            Page size
+            <select
+              defaultValue="5"
+              onChange={(e) => {
+                const nextLimit = Number(e.target.value);
+                query?.setLimit(nextLimit);
+                query?.setPage(0);
+                setPage(0);
+              }}
+            >
+              <option value="5">5</option>
+              <option value="10">10</option>
+              <option value="25">25</option>
+            </select>
+          </label>
+        </div>
+      </section>
+    );
+  },
+);
+```
+
+## Notes
+
+- This package depends on `@_linked/core` query APIs and `preloadFor(...)` / `BoundComponent` behavior from core.
+- `@_linked/react` itself does not provide RDF storage; use a store package and set a default store in `LinkedStorage` (for example `@_linked/rdf-mem-store`).
+
+## Storage setup (example: `@_linked/rdf-mem-store`)
+
+For local in-memory setup, register `@_linked/rdf-mem-store` as the default store:
+
+```tsx
+import {LinkedStorage} from '@_linked/core';
+import {InMemoryStore} from '@_linked/rdf-mem-store';
+
+LinkedStorage.setDefaultStore(new InMemoryStore());
+```
+
+## TODO
+
+- Add `setOffset` to `linkedSetComponent` query controller.
+- Make loader configurable and/or switch to passing a loading-state prop.
+
+## Development
+
+```bash
+npm run build
+npm test
+```
+
+## Changelog
+
+### 1.0.0 (from LINCD.js)
+
+Initial extraction from the LINCD monolith. Moves React-specific linked component wrappers into a standalone package.
+
+- `linkedComponent(...)` and `linkedSetComponent(...)` extracted from `lincd`.
+- `LinkedComponentClass` base class for class-based linked components.
+- `useStyles(...)` hook for component styling.
+- Pagination API (`nextPage`, `previousPage`, `setPage`, `setLimit`) on linked set components.
+- `_refresh(updatedProps?)` for optimistic UI updates on linked components.