@piedata/pieui 1.1.24 → 1.1.25
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# PieUI
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
**Install**
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
bun add @piedata/pieui
|
|
9
|
+
npm install @piedata/pieui
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
React and React DOM `>=19` are peer dependencies.
|
|
13
|
+
|
|
14
|
+
**Quick Start**
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
import { PieRoot, initializePieComponents } from '@piedata/pieui'
|
|
18
|
+
|
|
19
|
+
initializePieComponents()
|
|
20
|
+
|
|
21
|
+
export function App() {
|
|
22
|
+
return (
|
|
23
|
+
<PieRoot
|
|
24
|
+
location={{
|
|
25
|
+
pathname: window.location.pathname,
|
|
26
|
+
search: window.location.search,
|
|
27
|
+
}}
|
|
28
|
+
fallback={<>Loading...</>}
|
|
29
|
+
onError={() => console.error('Failed to load UI')}
|
|
30
|
+
onNavigate={(url) => {
|
|
31
|
+
window.location.href = url
|
|
32
|
+
}}
|
|
33
|
+
config={{
|
|
34
|
+
apiServer: 'https://api.example.com/',
|
|
35
|
+
centrifugeServer:
|
|
36
|
+
'wss://realtime.example.com/connection/websocket',
|
|
37
|
+
enableRenderingLog: false,
|
|
38
|
+
}}
|
|
39
|
+
initializePie={() => {
|
|
40
|
+
// Register custom components here if needed.
|
|
41
|
+
}}
|
|
42
|
+
/>
|
|
43
|
+
)
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
If you are embedding PieUI inside a Telegram WebApp, use `PieTelegramRoot` instead of `PieRoot`.
|
|
48
|
+
|
|
49
|
+
**Register Custom Components**
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
import { registerPieComponent } from '@piedata/pieui'
|
|
53
|
+
import MyCard from './MyCard'
|
|
54
|
+
|
|
55
|
+
registerPieComponent({
|
|
56
|
+
name: 'MyCard',
|
|
57
|
+
component: MyCard,
|
|
58
|
+
metadata: {
|
|
59
|
+
author: 'You',
|
|
60
|
+
description: 'Custom card',
|
|
61
|
+
},
|
|
62
|
+
})
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Exports**
|
|
66
|
+
Runtime exports:
|
|
67
|
+
|
|
68
|
+
- `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.
|
|
69
|
+
- `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.
|
|
70
|
+
- `PieTelegramRoot`: Same as `PieRoot`, but adds Telegram WebApp `initData` to the request query string via `useWebApp`. Throws if `apiServer` is missing.
|
|
71
|
+
- `PieBaseRoot`: Provider wrapper without fetching UI configuration. Renders `children` inside the same PieUI provider stack and form shell.
|
|
72
|
+
- `PieCard`: Wrapper for card components that wires optional Socket.IO, Centrifuge, or Mitt event handlers based on `methods` and `data.name`. Returns `children` unchanged.
|
|
73
|
+
- `registerPieComponent`: Registers a component (or lazy loader) into the PieUI registry, with optional metadata and fallback.
|
|
74
|
+
- `initializePieComponents`: Registers the built-in card components once (SequenceCard, BoxCard, UnionCard, AjaxGroupCard, AjaxButtonCard, RedirectButtonCard, ChatCard, HiddenCard, AutoRedirectCard, HTMLEmbedCard, IOEventsCard, OpenAIVoiceAgentCard, TableCard).
|
|
75
|
+
- `isPieComponentsInitialized`: Returns `true` if `initializePieComponents` has already been called.
|
|
76
|
+
- `useAjaxSubmit`: Hook that returns a function to `POST` to `api/ajax_content` and updates UI state via `setUiAjaxConfiguration`. Supports streamed JSON line events.
|
|
77
|
+
- `sx2radium`: Converts a style object to Radium-friendly `CSSProperties`, including converting object `animationName` into Radium keyframes.
|
|
78
|
+
- `cn`: Class name merge helper using `clsx` and `tailwind-merge`.
|
|
79
|
+
- `PIEBREAK`: String delimiter (`__piedemo__`) used internally to build form field names.
|
|
80
|
+
|
|
81
|
+
Type exports:
|
|
82
|
+
|
|
83
|
+
- `PieComponentProps`: Union type of the supported Pie component prop shapes.
|
|
84
|
+
- `PieSimpleComponentProps`: `{ data }` props for simple components.
|
|
85
|
+
- `PieComplexComponentProps`: `{ data, setUiAjaxConfiguration? }` props for components that trigger AJAX or updates.
|
|
86
|
+
- `PieContainerComponentProps`: `{ data, content, setUiAjaxConfiguration? }` props for components that render a single nested `UIConfigType`.
|
|
87
|
+
- `PieComplexContainerComponentProps`: `{ data, content: UIConfigType[], setUiAjaxConfiguration? }` props for components that render an array of nested configs.
|
|
88
|
+
- `PieConfig`: Configuration object for Pie roots. Includes `apiServer` and optional `centrifugeServer`, `enableRenderingLog`, `pageProcessor`.
|
|
89
|
+
- `UIConfigType`: Server-driven UI configuration with `card`, `data`, and `content` (nested `UIConfigType` or array).
|
|
90
|
+
- `SetUiAjaxConfigurationType`: Setter type for updating the UI configuration or streaming UI events.
|