@proveanything/smartlinks 2.0.15 → 2.0.17
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/dist/docs/API_SUMMARY.md +3 -1
- package/dist/docs/app-records-pattern.md +1 -1
- package/dist/docs/deploying-apps.md +25 -7
- package/dist/docs/theme-tokens.md +239 -0
- package/dist/docs/ui-utils.md +121 -104
- package/dist/openapi.yaml +699 -183
- package/dist/theme-boot.js +78 -0
- package/dist/theme.css +55 -0
- package/dist/types/appManifest.d.ts +12 -0
- package/docs/API_SUMMARY.md +3 -1
- package/docs/app-records-pattern.md +1 -1
- package/docs/deploying-apps.md +25 -7
- package/docs/theme-lookbook.v1.json +120 -0
- package/docs/theme-tokens.md +239 -0
- package/docs/ui-utils.md +121 -104
- package/openapi.yaml +699 -183
- package/package.json +5 -1
- package/scripts/doctor.mjs +49 -1
package/docs/ui-utils.md
CHANGED
|
@@ -1,104 +1,121 @@
|
|
|
1
|
-
# UI Utils — `@proveanything/smartlinks-utils-ui`
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
- **
|
|
10
|
-
- **Per-component reference:**
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
import
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
1
|
+
# UI Utils — `@proveanything/smartlinks-utils-ui`
|
|
2
|
+
|
|
3
|
+
The standardised, **admin-only** React toolkit for SmartLinks microapps. This page
|
|
4
|
+
is self-contained: the table and examples below are enough to build with. The
|
|
5
|
+
exhaustive per-component reference (props, slots, hooks, design tokens) ships
|
|
6
|
+
**inside the package** — read it from `node_modules/@proveanything/smartlinks-utils-ui/docs/`
|
|
7
|
+
after install. Nothing here depends on an external site.
|
|
8
|
+
|
|
9
|
+
- **NPM:** [`@proveanything/smartlinks-utils-ui`](https://www.npmjs.com/package/@proveanything/smartlinks-utils-ui)
|
|
10
|
+
- **Per-component reference:** `node_modules/@proveanything/smartlinks-utils-ui/docs/*.md`
|
|
11
|
+
(`records-admin-shell.md`, `admin-page-header.md`, `asset-picker.md`, `conditions-editor.md`,
|
|
12
|
+
`facet-rule-editor.md`, `link-picker.md`, `records-admin-hooks.md`, `public-consumption.md`, …)
|
|
13
|
+
- **Tracks:** `@proveanything/smartlinks ≥ 2.0` (peer dep)
|
|
14
|
+
|
|
15
|
+
## Admin is standardised; the consumer surface is bespoke
|
|
16
|
+
|
|
17
|
+
Two different design mandates, and the split is deliberate:
|
|
18
|
+
|
|
19
|
+
- **Admin surfaces** (the desktop `admin.html` a brand operator uses) are a
|
|
20
|
+
**product family** — like Salesforce: consistent, predictable chrome across every
|
|
21
|
+
app an operator opens. Do **not** hand-roll admin tables, editors or page headers.
|
|
22
|
+
Mount `RecordsAdminShell` for anything record-shaped; otherwise wrap the page in
|
|
23
|
+
`AdminPageHeader` and use the pickers. That consistency *is* the product.
|
|
24
|
+
- **Consumer / public surfaces** (the container, widgets, public pages the
|
|
25
|
+
end-customer sees) are **bespoke and brand-led** — entirely your design. utils-ui
|
|
26
|
+
belongs here only as read-side hooks (`useResolvedRecord`, `useResolveAllRecords`),
|
|
27
|
+
never as UI.
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install @proveanything/smartlinks-utils-ui
|
|
33
|
+
# Peer deps you probably already have:
|
|
34
|
+
npm install react react-dom @proveanything/smartlinks @tanstack/react-query
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Import the styles **once** in your admin entry (typically `src/admin-main.tsx`):
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import '@proveanything/smartlinks-utils-ui/styles.css';
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Components inherit your shadcn-compatible CSS variables (`--primary`,
|
|
44
|
+
`--background`, `--border`, …) — no extra theming required.
|
|
45
|
+
|
|
46
|
+
> **Admin-only.** Every component in this package calls the SDK with
|
|
47
|
+
> `admin: true` somewhere (save, upload, etc.). Never import it from a
|
|
48
|
+
> public widget or from `MobileAdminContainer`.
|
|
49
|
+
|
|
50
|
+
## What's in the box
|
|
51
|
+
|
|
52
|
+
| Module | Subpath import | Use it for |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| **RecordsAdminShell** | `/records-admin` | Full admin UI for the `app.records` pattern. Top-level scopes: **Global** (`'collection'`), **Rule** (`'rule'`, AND-of-OR over facets), and **Product** — with automatic variant & batch drill-down where the collection enables them. Browser pane, editor pane with sticky save/discard/delete, optimistic save, deep-linking, lifecycle hooks, conflict handling. Decide **cardinality** up front: `'singleton'` (one winning record per scope — warranty, nutrition) vs `'list'` (many records per scope — auction items, FAQs, gallery). See `docs/records-admin-shell.md`. |
|
|
55
|
+
| **Records hooks** | `/records-admin` | `useResolvedRecord`, `useMergedRecord`, `useCollectedRecords`, `useResolveAllRecords`, `useRulePreview`, … for the **public widget** side. See `docs/records-admin-hooks.md`. |
|
|
56
|
+
| **AdminPageHeader** | (root) | Standardised title / subtitle / icon / help / actions header. **Required** for any admin app that doesn't mount `RecordsAdminShell` (which embeds it). No bespoke admin chrome. |
|
|
57
|
+
| **AssetPicker** | `/asset-picker` | Pick / upload / paste / URL-import / AI-generate / stock-search / crop media assets. MIME filtering, scope-aware, tag editor. |
|
|
58
|
+
| **IconPicker** | `/icon-picker` | Searchable Font Awesome 7 Pro picker (requires the FA kit script on the host page). |
|
|
59
|
+
| **FontPicker** | `/font-picker` | Google Fonts catalogue + custom uploaded font families with live previews. |
|
|
60
|
+
| **ConditionsEditor** | `/conditions-editor` | Recursive AND/OR rule builder (12 condition types, facet-aware). |
|
|
61
|
+
| **FacetRuleEditor** | `/facet-rule-editor` | Author server-side facet rules (AND-of-OR) for record targeting. |
|
|
62
|
+
| **LinkPicker** | `/link-picker` | Universal navigation picker: external URL, an installed app, or a deep link inside an app. Stores a `LinkTarget` discriminated union — never a resolved URL. Ships with `resolveLink` and `useLinkTargets`. |
|
|
63
|
+
| **Liquid editors** | `/liquid-editor` | Author Liquid templates with a code or rich (TipTap) editor, variable autocomplete. |
|
|
64
|
+
| **Hints** | (root) | `useHintsPreference`, `useIntroState`, `HintsPreferenceToggle` — global "show/hide intro hints" preference shared across admin apps. |
|
|
65
|
+
|
|
66
|
+
Each module has a per-subpath export so bundlers tree-shake the rest:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
|
|
70
|
+
import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Minimal examples
|
|
74
|
+
|
|
75
|
+
### Records admin (most apps need this)
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
|
|
79
|
+
import * as SL from '@proveanything/smartlinks';
|
|
80
|
+
|
|
81
|
+
<RecordsAdminShell
|
|
82
|
+
SL={SL}
|
|
83
|
+
collectionId={collectionId}
|
|
84
|
+
appId={appId}
|
|
85
|
+
recordType="nutrition"
|
|
86
|
+
label="Nutrition info"
|
|
87
|
+
scopes={['collection', 'rule', 'product']} // canonical top-level tabs
|
|
88
|
+
// items={{ cardinality: 'list' }} // ← opt in for multi-item apps
|
|
89
|
+
defaultData={() => ({})}
|
|
90
|
+
renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
|
|
91
|
+
/>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Public widget — read the resolved value
|
|
95
|
+
|
|
96
|
+
```tsx
|
|
97
|
+
import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
|
|
98
|
+
|
|
99
|
+
const { data, source } = useResolvedRecord({
|
|
100
|
+
SL, appId, recordType: 'nutrition',
|
|
101
|
+
collectionId, productId, variantId, batchId,
|
|
102
|
+
});
|
|
103
|
+
// source: 'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'collection' | null
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
For multi-item (`cardinality: 'list'`) apps, use `useResolveAllRecords` /
|
|
107
|
+
`app.records.resolveAll()` instead — it returns every applicable record, not
|
|
108
|
+
just the winner.
|
|
109
|
+
|
|
110
|
+
For everything else (props, slots, cardinality decisions, deep-link adapters,
|
|
111
|
+
lifecycle hooks, conflict handling, design tokens) → **read the matching file in
|
|
112
|
+
`node_modules/@proveanything/smartlinks-utils-ui/docs/`**.
|
|
113
|
+
|
|
114
|
+
## Prerequisites
|
|
115
|
+
|
|
116
|
+
All components assume `SL.initializeApi()` has already run.
|
|
117
|
+
|
|
118
|
+
## Where to go next
|
|
119
|
+
|
|
120
|
+
- Per-component reference (shipped with the package): `node_modules/@proveanything/smartlinks-utils-ui/docs/`
|
|
121
|
+
- Records pattern (concepts, scope inheritance, resolution order): [`app-records-pattern.md`](./app-records-pattern.md)
|