From cbac57dc3603a911a990d052712ad3b6b8efdb24 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Thu, 18 Jun 2026 20:42:23 +0530 Subject: [PATCH] updated sse supporting react-openapi README.md --- react-openapi/README.md | 96 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 88 insertions(+), 8 deletions(-) diff --git a/react-openapi/README.md b/react-openapi/README.md index bb449fb..9c5a752 100644 --- a/react-openapi/README.md +++ b/react-openapi/README.md @@ -43,17 +43,31 @@ function App() { ### Components -| Export | Purpose | -|---------------|------------------------------------------------------------------------------------------------------------| -| `AppProvider` | Fetches the spec, validates it, initializes the API client, and provides context. Wrap your app with this. | -| `Admin` | Renders the admin layout (sidebar + routes) for all resources. Takes `basePath`. | +| Export | Purpose | +|------------------------|----------------------------------------------------------------------------------------------------------------| +| `AppProvider` | Fetches the spec, validates it, initializes the API client, and provides context. Wrap your app with this. | +| `Admin` | Renders the admin layout (sidebar + routes) for all resources. Takes `basePath`. | +| `ListCellRenderer` | Renders a cell value in a list/table column. Respects FK display formats, inline refs, enums, booleans. | +| `DetailFieldRenderer` | Renders a read-only field value in a detail view (label + value pair). | +| `FormFieldRenderer` | Renders an editable form field based on `FieldConfig`. Dispatches to `FkSelectField`, `BooleanField`, etc. | +| `SseStreamView` | Renders a live SSE stream card with connection status, event counter, latest event preview, and snackbar. | +| `SseConnectionStatus` | Renders a green/red dot with "Connected"/"Disconnected" for an SSE resource. Reactive across all components. | ### Hooks -| Export | Purpose | -|-------------------------|---------------------------------------------------------------------------------------------------------| -| `useAppContext()` | Returns `{ config, resources, loading, errors, warnings }`. Access all resource configs. | -| `useResource(resource)` | Returns `{ list, get, create, update, remove, loading, error }` — CRUD methods for a specific resource. | +| Export | Purpose | +|-------------------------------|-------------------------------------------------------------------------------------------------------------------| +| `useAppContext()` | Returns `{ config, resources, schemas, loading, errors, warnings }`. Access all resource configs. | +| `useResource(resourceName)` | Returns `{ resource, components, list, get, create, update, remove, stream?, loading, error }`. CRUD + streaming. | + +The `stream` property is only present for SSE resources (`resource.streaming === true`). It accepts `{ onEvent, onError?, onOpen? }` and returns `{ close }`. + +### Utilities + +| Export | Purpose | +|---------------------|---------------------------------------------------------------------| +| `getApi()` | Returns the configured Axios instance. Useful for custom API calls. | +| `applyDisplayFormat`| Formats an object using a template string like `"{name} - #{id}"`. | ### Types @@ -64,6 +78,72 @@ function App() { | `FieldConfig` | Internal representation of a field after spec parsing | | `FKFieldConfig` | `{ resource, prefetch }` | | `ResourceRelationship` | `{ fieldName, config, targetSchemaName }` | +| `FilterComponentProps` | `{ value, onChange, data?, labelOverride? }` | + +### `ResourceConfig` Properties + +| Property | Type | Description | +|----------------|-----------------------------------|---------------------------------------------------------------------------| +| `name` | `string` | URL-friendly resource name (e.g. `"pets"`, `"calls"`) | +| `schemaName` | `string` | OpenAPI schema key (e.g. `"Pet"`, `"Call"`) | +| `displayName` | `string` | Human-readable name for UI labels (e.g. `"Pets"`, `"Calls"`, `"Two Parts"`) | +| `path` | `string` | API base path (e.g. `"/pets"`, `"/calls"`) | +| `streaming` | `boolean` (optional) | `true` if this resource uses SSE streaming instead of REST CRUD | + +### SSE Streaming (Server-Sent Events) + +Resources with `x-sse: true` on their OpenAPI spec path object are treated as streaming resources. Instead of CRUD, they expose: + +- **`stream()`** — accepts `{ onEvent, onError?, onOpen? }` and returns `{ close }`. +- **Connection status** — reactive across `SseConnectionStatus` and `SseStreamView`. +- **Auto-reconnect** — SSE automatically reconnects on connection loss (browser-native). + +**OpenAPI extension:** +```yaml +/pets/events: + x-sse: true + get: + summary: Subscribe to Pet events + responses: + 200: + description: SSE stream of Pet change events + content: + text/event-stream: + schema: + type: object +``` +When `x-sse: true` is set, the resource is excluded from sidebars, list/detail routes, and CRUD hooks. It only appears in the `streaming` resource collection. + +**Custom UI example:** + +```tsx +import { useAppContext, SseStreamView } from 'react-openapi'; + +function MyStreamPage() { + const { resources } = useAppContext(); + const res = resources.find(r => r.name === 'calls'); + if (!res) return null; + return ; +} +``` + +### Loading Custom Components from Resources + +Pass per-resource overrides via `specConfiguration`: + +```tsx + +``` + +Within resource components, use `components` from `useResource()`: + +```tsx +const { components } = useResource('pets'); +const row = data.map(item => ); +``` ## OpenAPI Spec Authoring Guide