@ragrails/api-playground-react 0.1.2 → 0.1.4

package/README.md

@@ -1,23 +1,44 @@
 # @ragrails/api-playground-react
 
 [![npm version](https://img.shields.io/npm/v/@ragrails/api-playground-react.svg)](https://www.npmjs.com/package/@ragrails/api-playground-react)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/@ragrails/api-playground-react.svg)](https://bundlephobia.com/package/@ragrails/api-playground-react)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/%40ragrails%2Fapi-playground-react.svg)](https://bundlephobia.com/package/@ragrails/api-playground-react)
 [![types](https://img.shields.io/npm/types/@ragrails/api-playground-react.svg)](https://www.npmjs.com/package/@ragrails/api-playground-react)
 [![license](https://img.shields.io/npm/l/@ragrails/api-playground-react.svg)](./LICENSE)
 
-An embeddable, themeable **API playground** for React.
+A lightweight, embeddable React API playground for interactive API docs, developer portals, SDK docs, and internal tools.
 
-<!-- Add a screenshot/GIF here for the npm page, e.g.:
-![API playground widget](https://your-cdn-or-repo/screenshot.png)
--->
- Drop in a cURL command and get a polished docs widget: language-tabbed code snippets (cURL · JavaScript · Python · Go) and an interactive **Try it out** console that sends real requests, with headers/body/auth editing, response viewing, and history.
+Give developers a fast way to understand and test your API without leaving your docs. Add one component and get cURL-powered code snippets, a **Try it out** console, request editing, auth, cURL import, live API responses, and history.
 
-- 🎯 **One prop in** — pass a cURL string, everything else is derived.
-- 🧪 **Live console** — edit method, URL, headers, body, and auth; **Send** runs a real `fetch`.
-- 🧾 **Snippets** — cURL, JavaScript, Python, Go, generated from the same request.
-- 🌓 **Theming** — `dark` / `light` / `system`, plus primary color & background overrides.
-- 📦 **Zero Tailwind for consumers** — ships a single pre-compiled stylesheet.
-- 🔒 **Self-contained** — its own theme scope; won't leak styles into your app.
+## Features
+
+- **Embeddable API tester**: add an interactive playground to docs, portals, and internal tools.
+- **Multi-language examples**: show cURL, JavaScript, Python, and Go snippets.
+- **Try-it-out console**: let developers edit requests and see responses immediately.
+- **cURL import**: paste an existing cURL command and start testing from it.
+- **Headers, body, and auth**: support common request controls out of the box.
+- **Sample responses**: show expected output alongside the request.
+- **Request history**: help users move between previous API calls.
+- **Brandable design**: match your product with theme and color options.
+- **Light, dark, and auto mode**: choose a fixed theme or follow the user's system preference.
+- **Lightweight setup**: no Tailwind setup and no required stylesheet import.
+
+## Benefits
+
+- **Reduce friction**: users can test an endpoint at the moment they read about it.
+- **Improve comprehension**: examples become interactive instead of static.
+- **Speed up onboarding**: new developers can see inputs, auth, and responses in context.
+- **Keep docs consistent**: one cURL request powers the experience.
+- **Fit existing products**: embed it where your users already learn and work.
+
+## Use Cases
+
+- Interactive API documentation
+- Developer portals
+- SDK documentation
+- API onboarding flows
+- Internal API tools
+- Support and debugging pages
+- REST API testing inside React apps
 
 ## Install
 
@@ -25,96 +46,166 @@ An embeddable, themeable **API playground** for React.
 npm i @ragrails/api-playground-react
 ```
 
-`react` and `react-dom` (v18 or v19) are peer dependencies.
+`react` and `react-dom` are peer dependencies. React 18 and 19 are supported.
 
-## Quick start
+## Quick Start
 
 ```tsx
-import { ApiWidget } from '@ragrails/api-playground-react'
-import '@ragrails/api-playground-react/styles.css' // import once, anywhere in your app
-
-export function Docs() {
-  return <ApiWidget request={`curl -X GET 'https://jsonplaceholder.typicode.com/users/1'`} />
+import { ApiPlayground } from '@ragrails/api-playground-react'
+
+export function ApiDocs() {
+  return (
+    <ApiPlayground
+      request={`curl -X GET 'https://jsonplaceholder.typicode.com/users/1'`}
+    />
+  )
 }
 ```
 
-That single `request` drives the snippet view and the interactive console.
+That is enough to render a snippet card with a **Try it out** console.
+
+Styles are included automatically. An optional CSS export is available if your app prefers explicit stylesheet loading:
+
+```tsx
+import '@ragrails/api-playground-react/styles.css'
+```
+
+## A Complete Example
+
+```tsx
+import { useState } from 'react'
+import { ApiPlayground } from '@ragrails/api-playground-react'
+
+const initialRequest = `curl -X POST 'https://jsonplaceholder.typicode.com/posts' \\
+  -H 'Content-Type: application/json' \\
+  -d '{ "title": "API client", "body": "Live request from the widget", "userId": 1 }'`
+
+export function CreatePostDocs() {
+  const [request, setRequest] = useState(initialRequest)
+
+  return (
+    <ApiPlayground
+      request={request}
+      onUpdateRequest={setRequest}
+      title="Create Post"
+      sampleResponse={`{
+  "id": 101,
+  "title": "API client",
+  "body": "Live request from the widget",
+  "userId": 1
+}`}
+      customization={{
+        primary: '#7855ff',
+        background: '#16171d',
+      }}
+    />
+  )
+}
+```
 
 ## Props
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `request` | `string` | — | **Required.** The request as a cURL command — the source of truth. |
-| `title` | `string` | derived | Caption shown above the snippet (e.g. `"Get Users"`). |
-| `sampleResponse` | `string` | — | Example response (JSON) displayed under the snippet. |
-| `mode` | `'dark' \| 'light' \| 'system'` | `'dark'` | Color theme. `'system'` follows the OS and updates live. |
-| `customization` | `{ primary?: string; background?: string }` | — | Override the brand color / background (any CSS color). |
-| `editable` | `boolean` | `true` | When `false`, the console is read-only. |
-| `allowImport` | `boolean` | `true` | Show the **Import** action (paste a cURL command). |
-| `syncSnippet` | `boolean` | `false` | When `true`, console edits update the start snippet; otherwise it stays the documented request. |
-| `onUpdateRequest` | `(curl: string) => void` | — | Notified whenever the live request changes. |
+| `request` | `string` | Required | The cURL request shown and tested by the widget. |
+| `onUpdateRequest` | `(request: string) => void` | `undefined` | Receives the latest cURL request after edits or imports. |
+| `title` | `string` | inferred | Label shown above the snippet. Defaults to the request method and path. |
+| `sampleResponse` | `string` | `undefined` | Example response body shown below the snippet. JSON strings are syntax-highlighted. |
+| `editable` | `boolean` | `true` | Enables or disables editing in the console. |
+| `allowImport` | `boolean` | `true` | Shows or hides the cURL import action. |
+| `customization` | `{ primary?: string; background?: string }` | `undefined` | Overrides the widget's primary color and background. Accepts any CSS color. |
+| `mode` | `'dark' \| 'light' \| 'system'` | `'dark'` | Controls the widget theme. `system` follows the user's OS preference. |
+| `syncSnippet` | `boolean` | `false` | When `true`, the snippet follows console edits. |
 
-## Theming
+## Common Patterns
 
-The widget renders its own theme scope, independent of your app's theme.
+### Read-only documentation
+
+Use this when the page should explain an endpoint but not allow mutation.
 
 ```tsx
-// Light theme with a custom brand color
-<ApiWidget
+<ApiPlayground
   request={curl}
-  mode="light"
-  customization={{ primary: '#0ea5e9' }}
+  editable={false}
+  allowImport={false}
 />
-
-// Follow the operating system
-<ApiWidget request={curl} mode="system" />
 ```
 
-Fonts fall back to the system UI stack. To use a custom typeface, set `--font-heading` / `--font-sans` on a wrapping element.
+### Controlled request state
 
-## Examples
+Use `onUpdateRequest` when the parent app should own the latest cURL string.
 
 ```tsx
-// POST with headers, body, and a sample response
-<ApiWidget
-  request={`curl -X POST 'https://api.example.com/posts' \\
-  -H 'Content-Type: application/json' \\
-  -d '{ "title": "Hello", "userId": 1 }'`}
-  title="Create Post"
-  sampleResponse={`{ "id": 101, "title": "Hello", "userId": 1 }`}
+const [request, setRequest] = useState(curl)
+
+<ApiPlayground
+  request={request}
+  onUpdateRequest={setRequest}
 />
+```
 
-// Read-only documentation widget (no editing, no import)
-<ApiWidget request={curl} editable={false} allowImport={false} />
+### Brand customization
+
+```tsx
+<ApiPlayground
+  request={curl}
+  customization={{
+    primary: '#52b788',
+    background: '#101114',
+  }}
+/>
 ```
 
-## How it works
+### Light, dark, and auto mode
+
+Use a fixed theme, or let the widget automatically match the user's system preference.
+
+```tsx
+<ApiPlayground request={curl} mode="light" />
+<ApiPlayground request={curl} mode="dark" />
+<ApiPlayground request={curl} mode="system" />
+```
+
+## Live Testing
+
+The console sends real browser requests and displays the response status, timing, headers, and body.
+
+For protected APIs, users can configure bearer tokens or API key headers directly in the console.
 
-The cURL `request` is the single source of truth. The **snippet** is generated from it, and the **console** parses it into editable fields. Editing in the console updates an internal live request; with `syncSnippet={false}` (default) the documented snippet stays put, so the widget doubles as both reference docs and a live tester.
+## cURL Import
 
-**Send performs a real `fetch`** to the target URL, so it is subject to CORS — the API must allow the browser's origin. Network/CORS failures are shown as an error response.
+When import is enabled, users can paste a cURL request and continue testing from it. This is useful for docs, support flows, onboarding, and internal tools where developers already share API examples as cURL.
 
-## Additional exports
+## Styling
 
-Besides `ApiWidget`, the package exports the building blocks and helpers:
+The widget includes its styles automatically. Consumers do not need Tailwind, a Tailwind config, or a required stylesheet import.
+
+The optional stylesheet export remains available:
+
+```tsx
+import '@ragrails/api-playground-react/styles.css'
+```
+
+Use that path if your app prefers explicit CSS loading.
+
+The widget is themeable with `mode` and `customization`.
+
+## TypeScript
+
+Types are included. No separate `@types` package is required.
 
 ```ts
-import {
-  ApiWidget,
-  RequestSnippet,      // snippet-only view
-  ApiConsole,          // interactive console
-  ImportCard,          // cURL import card
-  parseCurl,           // cURL string -> WidgetRequest
-  generateSnippet,     // WidgetRequest -> code string (curl/js/python/go)
-  executeWidgetRequest // run a WidgetRequest with fetch
-} from '@ragrails/api-playground-react'
-
-import type {
-  ApiWidgetProps, ApiWidgetMode, ApiWidgetCustomization,
-  WidgetRequest, WidgetResponse, WidgetHeader, WidgetAuth, SnippetLanguage,
-} from '@ragrails/api-playground-react'
+import type { ApiPlaygroundProps } from '@ragrails/api-playground-react'
 ```
 
+## Notes
+
+- The browser enforces CORS for real requests.
+- Keep secrets out of checked-in docs examples. Let users paste tokens in the console when possible.
+- Use `editable={false}` for destructive endpoints if you only want to document the request.
+- Use `syncSnippet={false}` when your docs should preserve the canonical example while users experiment.
+
 ## License
 
 MIT
+# api-playground