apps/khata-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated sse supporting react-openapi README.md

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-06-18 20:42:23 +05:30
parent 154b15fe51
commit cbac57dc36
1 changed files with 88 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
react-openapi/README.md
View File

@@ -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 <SseStreamView resource={res} />;
}
```
### Loading Custom Components from Resources
Pass per-resource overrides via `specConfiguration`:
```tsx
<AppProvider config={config} resourceComponents={{
pets: { list: PetList, detail: PetDetail, form: PetForm },
calls: { detail: CallStream }, // SSE: only detail is used
}} />
```
Within resource components, use `components` from `useResource()`:
```tsx
const { components } = useResource('pets');
const row = data.map(item => <components.ListCell field={field} value={item[field.name]} />);
```
## OpenAPI Spec Authoring Guide