@proveanything/smartlinks 2.0.16 → 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 +1 -1
- package/dist/docs/app-records-pattern.md +1 -1
- package/dist/docs/theme-tokens.md +9 -2
- package/dist/docs/ui-utils.md +121 -104
- package/dist/openapi.yaml +695 -183
- package/docs/API_SUMMARY.md +1 -1
- package/docs/app-records-pattern.md +1 -1
- package/docs/theme-tokens.md +9 -2
- package/docs/ui-utils.md +121 -104
- package/openapi.yaml +695 -183
- package/package.json +3 -1
package/docs/API_SUMMARY.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
> Status: **standard**. New apps MUST follow this contract; existing apps SHOULD migrate.
|
|
8
8
|
>
|
|
9
9
|
> SDK: `@proveanything/smartlinks` ≥ **2.0** (R5).
|
|
10
|
-
> Admin shell (React only): `@proveanything/smartlinks-utils-ui` ≥ **0
|
|
10
|
+
> Admin shell (React only): `@proveanything/smartlinks-utils-ui` ≥ **2.0** — required for the admin side if using the React shell; not needed in public widgets.
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
package/docs/theme-tokens.md
CHANGED
|
@@ -1,8 +1,15 @@
|
|
|
1
1
|
# SmartLinks Theme Tokens — host theming contract
|
|
2
2
|
|
|
3
|
-
Status: **v1 (draft)
|
|
3
|
+
Status: **v1 (draft) — FORTHCOMING, not yet live host-side.**
|
|
4
|
+
> ⚠️ **Do not build apps against this yet.** The host (Hub/Portal) does not yet set `--sl-*` tokens
|
|
5
|
+
> or send `smartlinks:root-state`. Until it does, apps follow the **current** theming — see
|
|
6
|
+
> [`theme.system.md`](./theme.system.md) (`useSmartLinksTheme()` + shadcn vars `--primary`/`--background`,
|
|
7
|
+
> the `?theme=` base64 payload). This document is the target model that will supersede it once the host
|
|
8
|
+
> serves it; it exists so the SDK preset (`theme.css`), the iframe bootstrap (`theme-boot.js`) and the
|
|
9
|
+
> Hub theme engine can be built against a fixed contract.
|
|
10
|
+
|
|
4
11
|
Applies to: `@proveanything/smartlinks` ^2.0 (R5), container + widget embeds
|
|
5
|
-
Companion to: [`css-baseline.md`](./css-baseline.md) (mechanics) — this doc is **brand** (colour, shape, type)
|
|
12
|
+
Companion to: [`css-baseline.md`](./css-baseline.md) (mechanics, live) — this doc is **brand** (colour, shape, type)
|
|
6
13
|
|
|
7
14
|
---
|
|
8
15
|
|
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)
|