@tetrascience-npm/tetrascience-react-ui 0.4.0-beta.1.1 → 0.4.0-beta.10.1

package/README.md

@@ -2,6 +2,8 @@
 
 React component library for building TetraScience applications.
 
+[![npm version](https://img.shields.io/npm/v/@tetrascience-npm/tetrascience-react-ui)](https://www.npmjs.com/package/@tetrascience-npm/tetrascience-react-ui) [![CI](https://github.com/tetrascience/ts-lib-ui-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/tetrascience/ts-lib-ui-kit/actions/workflows/ci.yml) 📖 **[Storybook – Live Component Demos](https://ts-lib-ui-kit-storybook.vercel.app/)** | 🛠️ **[Contributing Guide](./CONTRIBUTING.md)**
+
 This library provides:
 
 - **UI Components**: Reusable React components following atomic design principles
@@ -9,6 +11,12 @@ This library provides:
 - **Theming**: Customisable design system with ThemeProvider
 - **TypeScript**: Full type support with exported prop types
 
+## Requirements
+
+- **React 19+**
+- **Node.js 18+**
+- **TypeScript 5.5+** (optional, but recommended)
+
 ## Installation
 
 ```bash
@@ -121,10 +129,10 @@ import {
 const userToken = await jwtManager.getTokenFromExpressRequest(req);
 
 // Create TDPClient with the user's auth token
+// Other fields (tdpEndpoint, connectorId, orgSlug) are read from environment variables
 const client = new TDPClient({
   authToken: userToken,
   artifactType: 'data-app',
-  orgSlug: process.env.ORG_SLUG,
 });
 await client.init();
 
@@ -199,6 +207,81 @@ try {
 
 > **Note:** Authentication tokens are obtained from the user's JWT via `jwtManager`. The `TS_AUTH_TOKEN` environment variable is only for local development fallback.
 
+### Connector Key/Value Store
+
+The TDP connector key/value store lets data apps persist small pieces of state (user preferences, cached results, last-run timestamps, etc.) without an external database. The `TDPClient` from `@tetrascience-npm/ts-connectors-sdk` provides `getValue`, `getValues`, `saveValue`, and `saveValues` methods.
+
+**Reading and writing values with the user's JWT token:**
+
+```typescript
+import { TDPClient } from '@tetrascience-npm/ts-connectors-sdk';
+import { jwtManager } from '@tetrascience-npm/tetrascience-react-ui/server';
+
+// In an Express route handler:
+app.get('/api/kv/:key', async (req, res) => {
+  // 1. Get the user's JWT from request cookies
+  const userToken = await jwtManager.getTokenFromExpressRequest(req);
+  if (!userToken) return res.status(401).json({ error: 'Not authenticated' });
+
+  // 2. Create a TDPClient authenticated as the user
+  //    (CONNECTOR_ID, TDP_ENDPOINT, ORG_SLUG are read from env vars)
+  const client = new TDPClient({
+    authToken: userToken,
+    artifactType: 'data-app',
+  });
+  await client.init();
+
+  // 3. Read a value
+  const value = await client.getValue(req.params.key);
+  res.json({ key: req.params.key, value });
+});
+
+app.put('/api/kv/:key', async (req, res) => {
+  const userToken = await jwtManager.getTokenFromExpressRequest(req);
+  if (!userToken) return res.status(401).json({ error: 'Not authenticated' });
+
+  const client = new TDPClient({
+    authToken: userToken,
+    artifactType: 'data-app',
+  });
+  await client.init();
+
+  // Write a value (any JSON-serialisable type)
+  await client.saveValue(req.params.key, req.body.value, { secure: false });
+  res.json({ key: req.params.key, saved: true });
+});
+```
+
+**Reading multiple values at once:**
+
+```typescript
+const values = await client.getValues(['theme', 'locale', 'last-run']);
+// values[0] → theme, values[1] → locale, values[2] → last-run
+```
+
+> See the [example app](./examples/vite-themed-app/) for a complete working server with KV store endpoints.
+
+### TDP Search (`server`)
+
+**TdpSearchManager** - Server-side handler for the TdpSearch component. Resolves auth from request cookies (via `jwtManager`), calls TDP `searchEql`, and returns the response so the frontend hook works with minimal wiring.
+
+```typescript
+import { tdpSearchManager } from "@tetrascience-npm/tetrascience-react-ui/server";
+
+// Express: mount a POST route (e.g. /api/search)
+app.post("/api/search", express.json(), async (req, res) => {
+  try {
+    const body = req.body; // SearchEqlRequest (searchTerm, from, size, sort, order, ...)
+    const response = await tdpSearchManager.handleSearchRequest(req, body);
+    res.json(response);
+  } catch (err) {
+    res.status(401).json({ error: err instanceof Error ? err.message : "Search failed" });
+  }
+});
+```
+
+Frontend: use `<TdpSearch columns={...} />` with default `apiEndpoint="/api/search"`, or pass `apiEndpoint` if you use a different path. Auth is taken from cookies (`ts-auth-token` or `ts-token-ref` via `jwtManager`).
+
 ## TypeScript Support
 
 Full TypeScript support with exported types:
@@ -228,6 +311,8 @@ Visit <http://localhost:5173> to see the example app with custom theming.
 
 ## Documentation
 
+- [Storybook – Live Component Demos](https://ts-lib-ui-kit-storybook.vercel.app/) - Browse all components with interactive examples
+- [NPM Package](https://www.npmjs.com/package/@tetrascience-npm/tetrascience-react-ui) - Installation and version info
 - [Getting Started Guide](./get_started_1.md) - Step-by-step tutorial
 - [Theming Guide](./THEMING.md) - Customise the design system
 - [Contributing](./CONTRIBUTING.md#development-setup) - Clone the repo and run `yarn storybook`