@piedata/pieui 1.1.24 → 1.1.26

package/README.md

@@ -0,0 +1,90 @@
+# PieUI
+
+PieUI is a React component library for rendering server-driven UI "cards" with optional real-time and AJAX updates. It provides a component registry, root wrappers that set up providers, and helpers for styling and class name management.
+
+**Install**
+
+```sh
+bun add @piedata/pieui
+npm install @piedata/pieui
+```
+
+React and React DOM `>=19` are peer dependencies.
+
+**Quick Start**
+
+```tsx
+import { PieRoot, initializePieComponents } from '@piedata/pieui'
+
+initializePieComponents()
+
+export function App() {
+    return (
+        <PieRoot
+            location={{
+                pathname: window.location.pathname,
+                search: window.location.search,
+            }}
+            fallback={<>Loading...</>}
+            onError={() => console.error('Failed to load UI')}
+            onNavigate={(url) => {
+                window.location.href = url
+            }}
+            config={{
+                apiServer: 'https://api.example.com/',
+                centrifugeServer:
+                    'wss://realtime.example.com/connection/websocket',
+                enableRenderingLog: false,
+            }}
+            initializePie={() => {
+                // Register custom components here if needed.
+            }}
+        />
+    )
+}
+```
+
+If you are embedding PieUI inside a Telegram WebApp, use `PieTelegramRoot` instead of `PieRoot`.
+
+**Register Custom Components**
+
+```tsx
+import { registerPieComponent } from '@piedata/pieui'
+import MyCard from './MyCard'
+
+registerPieComponent({
+    name: 'MyCard',
+    component: MyCard,
+    metadata: {
+        author: 'You',
+        description: 'Custom card',
+    },
+})
+```
+
+**Exports**
+Runtime exports:
+
+- `UI`: Renders a `UIConfigType` by looking up `uiConfig.card` in the registry. Supports lazy components via `Suspense` and passes `data`, `content`, and `setUiAjaxConfiguration` into the rendered component.
+- `PieRoot`: Fetches UI configuration from `config.apiServer + "/api/content"` using the current `location` and renders `UI` inside PieUI providers (React Query, Socket.IO, Centrifuge, Mitt, Radium). Calls `initializePieComponents()` and your `initializePie` callback once.
+- `PieTelegramRoot`: Same as `PieRoot`, but adds Telegram WebApp `initData` to the request query string via `useWebApp`. Throws if `apiServer` is missing.
+- `PieBaseRoot`: Provider wrapper without fetching UI configuration. Renders `children` inside the same PieUI provider stack and form shell.
+- `PieCard`: Wrapper for card components that wires optional Socket.IO, Centrifuge, or Mitt event handlers based on `methods` and `data.name`. Returns `children` unchanged.
+- `registerPieComponent`: Registers a component (or lazy loader) into the PieUI registry, with optional metadata and fallback.
+- `initializePieComponents`: Registers the built-in card components once (SequenceCard, BoxCard, UnionCard, AjaxGroupCard, AjaxButtonCard, RedirectButtonCard, ChatCard, HiddenCard, AutoRedirectCard, HTMLEmbedCard, IOEventsCard, OpenAIVoiceAgentCard, TableCard).
+- `isPieComponentsInitialized`: Returns `true` if `initializePieComponents` has already been called.
+- `useAjaxSubmit`: Hook that returns a function to `POST` to `api/ajax_content` and updates UI state via `setUiAjaxConfiguration`. Supports streamed JSON line events.
+- `sx2radium`: Converts a style object to Radium-friendly `CSSProperties`, including converting object `animationName` into Radium keyframes.
+- `cn`: Class name merge helper using `clsx` and `tailwind-merge`.
+- `PIEBREAK`: String delimiter (`__piedemo__`) used internally to build form field names.
+
+Type exports:
+
+- `PieComponentProps`: Union type of the supported Pie component prop shapes.
+- `PieSimpleComponentProps`: `{ data }` props for simple components.
+- `PieComplexComponentProps`: `{ data, setUiAjaxConfiguration? }` props for components that trigger AJAX or updates.
+- `PieContainerComponentProps`: `{ data, content, setUiAjaxConfiguration? }` props for components that render a single nested `UIConfigType`.
+- `PieComplexContainerComponentProps`: `{ data, content: UIConfigType[], setUiAjaxConfiguration? }` props for components that render an array of nested configs.
+- `PieConfig`: Configuration object for Pie roots. Includes `apiServer` and optional `centrifugeServer`, `enableRenderingLog`, `pageProcessor`.
+- `UIConfigType`: Server-driven UI configuration with `card`, `data`, and `content` (nested `UIConfigType` or array).
+- `SetUiAjaxConfigurationType`: Setter type for updating the UI configuration or streaming UI events.

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { registerPieComponent } from './util/registry';
 export { initializePieComponents, isPieComponentsInitialized, } from './util/initializeComponents';
 export type { PieComponentProps, PieSimpleComponentProps, PieComplexComponentProps, PieContainerComponentProps, PieComplexContainerComponentProps, PieConfig, UIConfigType, SetUiAjaxConfigurationType, } from './types';
 export { useAjaxSubmit } from './util/ajaxCommonUtils';
+export { default as useOpenAIWebRTC, type OpenAIEvent, type UseOpenAIWebRTCReturn, } from './util/useOpenAIWebRTC';
 export { sx2radium } from './util/sx2radium';
 export { cn } from './util/tailwindCommonUtils';
 export { PIEBREAK } from './util/pieConfig';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EACH,uBAAuB,EACvB,0BAA0B,GAC7B,MAAM,6BAA6B,CAAA;AAEpC,YAAY,EACR,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,iCAAiC,EACjC,SAAS,EACT,YAAY,EACZ,0BAA0B,GAC7B,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,4BAA4B,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EACH,uBAAuB,EACvB,0BAA0B,GAC7B,MAAM,6BAA6B,CAAA;AAEpC,YAAY,EACR,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,iCAAiC,EACjC,SAAS,EACT,YAAY,EACZ,0BAA0B,GAC7B,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,EACH,OAAO,IAAI,eAAe,EAC1B,KAAK,WAAW,EAChB,KAAK,qBAAqB,GAC7B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,4BAA4B,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA"}