@proveanything/smartlinks 1.9.20 → 1.9.22

package/docs/records-admin-pattern.md

@@ -0,0 +1,315 @@
+# SmartLinks Records-Based Admin Pattern
+
+> Canonical guide for building admin UIs in microapps that store **per-product**, **per-facet**, **per-variant** or **per-batch** data.
+>
+> Audience: microapp developers (nutrition, allergy, ingredients, cooking-guide, warranty, provenance, …).
+>
+> Status: **standard** — new admin apps in this category MUST follow this contract. Existing apps SHOULD migrate.
+
+---
+
+## 1. Why a shared pattern?
+
+Many SmartLinks microapps store **structured data that varies along one or more product axes**:
+
+| App              | Varies by                                      |
+|------------------|------------------------------------------------|
+| Nutrition        | product, facet (bread type, region), batch     |
+| Allergy          | product, facet (recipe family)                 |
+| Ingredients      | product, variant (size), batch (production run)|
+| Cooking guide    | product, facet (cut of meat)                   |
+| Warranty         | product, variant, batch                        |
+| Provenance       | batch                                          |
+
+Without a shared pattern, every app reinvents:
+
+- the left-rail "browse + select" list
+- the per-axis precedence rules
+- the inheritance/override UI
+- the "no data yet" empty state
+- CSV import/export
+- bulk operations
+
+The result is drift: each app feels different and admins have to re-learn the model. This guide locks the model down at the SDK level so the matching UI primitives in `@proveanything/ui-utils` (see the [companion guide](ui-utils.md)) can stay simple.
+
+---
+
+## 2. Storage model: `app.records`
+
+**Do not** stuff per-axis data into `appConfiguration.products[productId]`. Use `app.records` (recordType-keyed) so that data is queryable, paginatable and survives schema changes.
+
+```ts
+import { app } from '@proveanything/smartlinks';
+
+await app.records.create(collectionId, appId, {
+  recordType: 'nutrition',          // app-defined, stable
+  ref: 'product:prod_abc',           // see §3
+  data: { /* domain payload */ },
+}, /* admin= */ true);
+```
+
+Each record has:
+
+| Field        | Purpose                                                     |
+|--------------|-------------------------------------------------------------|
+| `recordType` | Namespaces records inside the app. One app may have several (`nutrition`, `cooking_steps`). |
+| `ref`        | Encodes the **scope** of the record. See §3.                |
+| `data`       | The domain payload. Free-form per app.                      |
+| `meta`       | Reserved for system fields (timestamps, author).            |
+
+> **Rule:** `(appId, recordType, ref)` is unique. Treat it as the natural key.
+
+---
+
+## 3. The `ref` convention (REQUIRED)
+
+`ref` is a colon-delimited string that encodes which scope a record applies to. Standardising it is what makes the shared admin shell possible.
+
+```
+product:<productId>
+variant:<productId>:<variantId>
+batch:<productId>:<batchId>
+proof:<proofId>
+facet:<facetKey>:<valueKey>
+default
+```
+
+Notes:
+
+- Variants and batches are **always nested under a product** in the SDK, so their refs include `productId`.
+- `facet:` refs are **collection-wide** — facets cross products by design.
+- `default` is a single record per (app, recordType) used as the global fallback.
+- Refs are opaque to the SDK. Apps parse them. A helper module (`@proveanything/smartlinks-utils-ui/records-admin`) exports `parseRef`/`buildRef` so all apps agree on syntax. See Appendix A for the full implementation.
+
+### Adding scopes later
+
+If a new axis appears (e.g. `region:eu`), pick a new prefix and document it. Never reuse a prefix with different semantics.
+
+---
+
+## 4. Resolution order (REQUIRED)
+
+When the **public** side of an app needs "the data that applies to this proof / product / context", it walks the chain from most-specific to least-specific and returns the first match:
+
+```
+proof → batch → variant → product → facet(*) → default
+```
+
+`facet(*)` means: walk every facet attached to the product in a deterministic order (alphabetical by `facetKey`, then `valueKey`) and use the first matching facet record.
+
+> **Rule:** Resolution is **first-match-wins, not merge**. If you need field-level merging, build it on top with explicit `inheritsFrom` markers in the payload — but the default for shared infra is whole-record replacement, because it is far easier to reason about.
+
+The canonical resolver lives in `@proveanything/smartlinks-utils-ui/records-admin` so every app behaves identically:
+
+```ts
+import { resolveRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const resolved = await resolveRecord({
+  appId,
+  recordType: 'nutrition',
+  scope: { collectionId, productId, variantId, batchId, proofId },
+});
+// → { record, source: 'variant' | 'product' | 'facet' | … } | null
+```
+
+Apps that only support a subset of scopes pass `supportedScopes: ['product', 'facet']` and the resolver skips the rest.
+
+---
+
+## 5. Scope capabilities (declared per app)
+
+An app declares which scopes it accepts records for in `app.manifest.json`. This drives the admin UI and avoids dead tabs:
+
+```json
+// app.manifest.json (extension)
+{
+  "records": {
+    "nutrition": {
+      "scopes": ["product", "facet", "batch"],
+      "defaultScope": "facet",
+      "label": "Nutrition info"
+    }
+  }
+}
+```
+
+| Field          | Meaning                                                        |
+|----------------|----------------------------------------------------------------|
+| `scopes`       | Allowed scope kinds, in **resolution order**.                  |
+| `defaultScope` | Where the "Create new" button lands in the admin shell.        |
+| `label`        | Human-readable label for the record type (used in headings).   |
+
+The shared admin shell reads this manifest entry and renders only the relevant tabs. Apps don't hard-code tab lists.
+
+See [app-manifest.md](app-manifest.md) for the full schema reference.
+
+---
+
+## 6. Discovering whether variants / batches are in use
+
+The `Collection` object exposes top-level `variants: boolean` and `batches: boolean` flags that indicate whether the collection has these features enabled. Read them directly rather than probing by listing:
+
+```ts
+import { appConfiguration } from '@proveanything/smartlinks';
+
+const collection = await appConfiguration.getCollection(collectionId);
+
+const showVariantTab = collection.variants && scopeConfig?.scopes.includes('variant') === true;
+const showBatchTab   = collection.batches  && scopeConfig?.scopes.includes('batch') === true;
+```
+
+`scopeConfig` is the parsed manifest `records` entry for this `recordType` — e.g. `manifest.records?.nutrition`.
+
+Rules:
+
+1. If the collection has the feature **and** the app **declares** support for the scope, show the tab and offer "Add variant" / "Add batch" affordances.
+2. If the app does **not** declare support, hide the tab entirely even if `collection.variants` is true (another app created them).
+3. If the collection does not have the feature enabled, hide the tab even if the app declares support.
+
+---
+
+## 7. Inheritance & overrides
+
+Because resolution is first-match-wins, the admin UI must make inheritance **visible**:
+
+- When editing a **variant** record, show the **product** record as the inherited baseline.
+- Each field in the editor displays a small **↩ "Inherited"** marker when its value matches the parent and **● "Override"** when it differs.
+- A row-level "Reset to inherited" action removes the override (deletes the record at the current scope if all overrides are reset).
+
+Apps don't have to implement this themselves — the `<RecordEditor>` primitive in `@proveanything/smartlinks-utils-ui` does it given the resolved parent payload.
+
+---
+
+## 8. Bulk operations
+
+Standard verbs every shell should expose:
+
+| Verb              | Behaviour                                                            |
+|-------------------|----------------------------------------------------------------------|
+| **Apply to many** | Take the current record's payload, write it to N selected products / variants. |
+| **Copy from**     | Pick a source scope, copy its payload to the current scope.          |
+| **Clear**         | Delete records at the current scope (children unaffected).           |
+
+Use the `bulkUpsert` / `bulkDelete` helpers from `@proveanything/smartlinks-utils-ui/records-admin`, which handle batching and error collection for you:
+
+```ts
+import { bulkUpsert, bulkDelete } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+// Apply current payload to many refs
+await bulkUpsert({ SL, collectionId, appId, recordType, refs: targetRefs, data: payload });
+
+// Clear records at selected refs
+await bulkDelete({ SL, collectionId, appId, recordType, refs: targetRefs });
+```
+
+If you are using `<RecordsAdminShell>`, the bulk actions menu is included and wired automatically via the `onTelemetry` hook — you don't call these directly unless you're building a custom shell.
+
+---
+
+## 9. CSV import / export
+
+Adopt this column shape across all records-based apps:
+
+```
+scope,scopeRef,<field1>,<field2>,...
+product,prod_abc,250,12.5,...
+variant,prod_abc/var_500ml,260,12.5,...
+batch,prod_abc/B-2024-03,255,12.5,...
+facet,bread_type/sourdough,240,11.0,...
+```
+
+- `scope` is the kind; `scopeRef` is the human-readable reference (the shell maps it to the canonical `ref`).
+- Validation errors return a downloadable annotated CSV with an `error` column appended.
+- Round-tripping (export → reimport unchanged) MUST be a no-op.
+
+---
+
+## 10. Public-side hook contract
+
+To keep widgets consistent across apps, expose one hook per record type (implemented in `@proveanything/ui-utils`):
+
+```ts
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { data, source, isLoading } = useResolvedRecord({
+  appId,
+  recordType: 'nutrition',
+  // any combination of these — the hook walks the chain:
+  collectionId, productId, variantId, batchId, proofId,
+});
+```
+
+`source` is one of `'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null`. UI can show a badge ("Showing batch-specific values") when useful.
+
+---
+
+## 11. Telemetry
+
+All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanything/ui-utils` wires them automatically using `interactions.appendEvent` from the SDK — apps don't call this themselves.
+
+| Event                  | Props                                                |
+|------------------------|------------------------------------------------------|
+| `record.opened`        | `appId, recordType, ref, source`                     |
+| `record.saved`         | `appId, recordType, ref, fieldsChanged`              |
+| `record.deleted`       | `appId, recordType, ref`                             |
+| `record.bulkApplied`   | `appId, recordType, sourceRef, targetCount`          |
+| `record.imported`      | `appId, recordType, rows, errors`                    |
+
+---
+
+## 12. Required reading for app authors
+
+1. This document.
+2. The companion **[UI utils guide](ui-utils.md)** — explains the React primitives (`<RecordsAdminShell>`, `useResolvedRecord`, etc.) that implement this pattern.
+3. [PRODUCT_FACETS_SDK.md](PRODUCT_FACETS_SDK.md) — facet model.
+4. [app-data-storage.md](app-data-storage.md) — `app.records` surface.
+
+## 13. Migration checklist for existing apps
+
+- [ ] Stop writing per-product data into `appConfiguration`.
+- [ ] Move to `app.records` with `recordType` + `ref`.
+- [ ] Adopt the `ref` syntax in §3.
+- [ ] Add a `records` block to `app.manifest.json`.
+- [ ] Replace bespoke admin browser with `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui`.
+- [ ] Replace bespoke public hook with `useResolvedRecord`.
+- [ ] Remove any "is variants enabled?" config — use `collection.variants` / `collection.batches` flags instead (§6).
+
+---
+
+## Appendix A — `ref` parser reference
+
+This is the canonical implementation. Copy it into your app or import from `@proveanything/ui-utils/records`.
+
+```ts
+type ParsedRef =
+  | { kind: 'default' }
+  | { kind: 'product'; productId: string }
+  | { kind: 'variant'; productId: string; variantId: string }
+  | { kind: 'batch';   productId: string; batchId: string }
+  | { kind: 'proof';   proofId: string }
+  | { kind: 'facet';   facetKey: string; valueKey: string };
+
+export const buildRef = (p: ParsedRef): string => {
+  switch (p.kind) {
+    case 'default': return 'default';
+    case 'product': return `product:${p.productId}`;
+    case 'variant': return `variant:${p.productId}:${p.variantId}`;
+    case 'batch':   return `batch:${p.productId}:${p.batchId}`;
+    case 'proof':   return `proof:${p.proofId}`;
+    case 'facet':   return `facet:${p.facetKey}:${p.valueKey}`;
+  }
+};
+
+export const parseRef = (ref: string): ParsedRef | null => {
+  if (ref === 'default') return { kind: 'default' };
+  const [head, ...rest] = ref.split(':');
+  switch (head) {
+    case 'product': return rest.length === 1 ? { kind: 'product', productId: rest[0] } : null;
+    case 'variant': return rest.length === 2 ? { kind: 'variant', productId: rest[0], variantId: rest[1] } : null;
+    case 'batch':   return rest.length === 2 ? { kind: 'batch',   productId: rest[0], batchId:   rest[1] } : null;
+    case 'proof':   return rest.length === 1 ? { kind: 'proof',   proofId:   rest[0] } : null;
+    case 'facet':   return rest.length >= 2  ? { kind: 'facet',   facetKey:  rest[0], valueKey:  rest.slice(1).join(':') } : null;
+    default: return null;
+  }
+};
+```

package/docs/ui-utils.md

@@ -0,0 +1,294 @@
+# SmartLinks UI Utils (`@proveanything/smartlinks-utils-ui`)
+
+> Companion React component library for the SmartLinks SDK. Ships the heavy, opinionated admin UI pieces that almost every SmartLinks microapp ends up needing — built once, theme-able, tree-shakeable, and wired straight into the SmartLinks SDK.
+>
+> Package: `@proveanything/smartlinks-utils-ui`  
+> Tracks: `@proveanything/smartlinks ≥ 1.9`
+
+---
+
+## What is this module for?
+
+`@proveanything/smartlinks-utils-ui` sits on top of `@proveanything/smartlinks`. The core SDK handles data — records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and admin shells that translate SDK data into consistent admin interfaces.
+
+**When do you need it?**
+
+- You are building an admin UI for a records-based microapp (see [records-admin-pattern.md](records-admin-pattern.md))
+- You need a media asset picker, icon picker, or font picker in an admin panel
+- You need a recursive rule/conditions editor for targeting or audience logic
+- You want the standard inheritance/override editor for scoped records
+- You need the `useResolvedRecord` hook on the public widget side
+
+You do **not** need it for apps that only use `appConfiguration`, basic widgets without scoped data, or executor bundles.
+
+> **Admin-only**: all components call the SDK with `admin: true`. Do not render them in public-facing views.
+
+---
+
+## Install
+
+```bash
+npm install @proveanything/smartlinks-utils-ui
+```
+
+Peer dependencies (you already have these in a SmartLinks app):
+
+```bash
+npm install react react-dom @proveanything/smartlinks
+# Recommended — enables caching and pagination in Records Admin Shell:
+npm install @tanstack/react-query
+```
+
+Import the compiled styles **once** in your app entry (e.g. `main.tsx`):
+
+```tsx
+import '@proveanything/smartlinks-utils-ui/styles.css';
+```
+
+Components inherit your shadcn-compatible CSS variables (`--primary`, `--background`, `--border`, …) so they pick up your theme automatically.
+
+---
+
+## What's in the box
+
+| Module | What it is | When to reach for it |
+|--------|------------|----------------------|
+| [Records Admin Shell](#records-admin-shell) | Full admin UI for `app.records` with scope inheritance | Per-product / per-variant / per-batch / per-facet config tools |
+| [Asset Picker](#asset-picker) | Browse / upload / paste / URL-import images and files | Any time the admin needs to pick or upload media |
+| [Icon Picker](#icon-picker) | Searchable Font Awesome 7 Pro picker | Configurable buttons, badges, menus, tiles |
+| [Font Picker](#font-picker) | Google Fonts + custom uploaded fonts | Theme editors, brand customisation panels |
+| [Conditions Editor](#conditions-editor) | Recursive AND/OR rule builder for 12 condition types | Targeting, gating, audience rules, segmentation |
+
+---
+
+## Records Admin Shell
+
+The primary export. A complete admin UI for managing `app.records` — typed JSON blobs attached to facets, products, variants, and batches — with scope inheritance built in. You provide the form for one record; the shell handles everything else.
+
+```tsx
+import {
+  RecordsAdminShell,
+  InheritanceMarker,
+  type EditorContext,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
+import * as SL from '@proveanything/smartlinks';
+
+<RecordsAdminShell<NutritionData>
+  SL={SL}
+  collectionId={collectionId}
+  appId={appId}
+  recordType="nutrition"
+  label="Nutrition info"
+  scopes={['facet', 'product', 'variant', 'batch']}
+  contextScope={{ productId, variantId, batchId }}   // from iframe URL — optional
+  defaultData={() => ({})}
+  csvSchema={{ columns: [/* ... */] }}
+  renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
+  renderPreview={({ resolved }) => <pre>{JSON.stringify(resolved, null, 2)}</pre>}
+/>
+```
+
+**What it handles:**
+
+- **Browser pane** with scope tabs (Facet / Product / Variant / Batch), search, and status filter pills (All / Configured / Partial / Empty)
+- **Editor pane** with sticky save / discard / delete footer
+- **Per-field `<InheritanceMarker>`** showing whether a value is the record's own or inherited from a parent scope, with one-click revert-to-inherited
+- **Inheritance resolver** walks `batch → variant → product → facet` and returns both the resolved and parent values
+- **Collection-aware tabs**: calls `collection.get` and hides Variants / Batches tabs unless `collection.variants` / `collection.batches` are true — no flicker
+- **Server-side pagination** via `useInfiniteQuery` — handles thousands of products with a "Load more" button
+- **Context-aware**: pass `contextScope` from your iframe URL (`productId` / `variantId` / `batchId`) and the browser is constrained to that subtree with the right tab auto-selected
+- **CSV import / export** with a schema you define; failed rows come back as an annotated CSV
+- **Bulk actions menu** (apply-to-many, copy-from, clear) via `bulkUpsert` / `bulkDelete`
+- **Telemetry hook** (`onTelemetry`) emits typed events for save, delete, scope change, CSV import/export, bulk apply
+- **i18n strings** fully overridable
+
+> Requires a `<QueryClientProvider>` from `@tanstack/react-query` somewhere up the tree.
+
+### Lower-level pieces (advanced use)
+
+```tsx
+import {
+  // Hooks
+  useRecordList, useRecordEditor, useResolvedRecord, useScopeProbe,
+  // Data helpers
+  parseRef, buildRef, resolutionChain,
+  listRecords, getRecordByRef, upsertRecord, deleteRecord,
+  bulkUpsert, bulkDelete,
+  exportCsv, importCsv, downloadBlob,
+  // UI pieces
+  RecordBrowser, RecordEditor, ScopeBreadcrumb,
+  InheritanceMarker, ResolvedPreview, BulkActionsMenu,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
+```
+
+### `useResolvedRecord` hook
+
+```ts
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { data, source, isLoading } = useResolvedRecord({
+  SL,
+  appId,
+  recordType: 'nutrition',
+  collectionId,
+  productId,
+  variantId,   // optional
+  batchId,     // optional
+  proofId,     // optional
+});
+// source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null
+```
+
+Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required). Use this on the **public widget side** to read the correct value for a given context.
+
+### `parseRef` / `buildRef` utilities
+
+```ts
+import { parseRef, buildRef } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const parsed = parseRef('variant:prod_abc:var_500ml');
+// → { kind: 'variant', productId: 'prod_abc', variantId: 'var_500ml' }
+
+const ref = buildRef({ kind: 'facet', facetKey: 'bread_type', valueKey: 'sourdough' });
+// → 'facet:bread_type:sourdough'
+```
+
+See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type.
+
+---
+
+## Asset Picker
+
+```tsx
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+<AssetPicker
+  scope={{ type: 'collection', collectionId: 'abc123' }}
+  mode="dialog"               // or "inline"
+  allowUpload
+  accept={['image/*']}        // MIME filtering
+  onSelect={(asset) => setHeroUrl(asset.url)}
+  trigger={<Button>Choose image</Button>}
+/>
+```
+
+**What it does:**
+- Browses assets at **collection** or **product** scope (dual-scope tabs)
+- Four ingest paths: file upload, URL import, clipboard paste (with rename preview), and selection from existing assets
+- Inline mode for embedding in a panel; dialog mode for modal pickers
+- Double-click a tile to confirm instantly
+
+---
+
+## Icon Picker
+
+```tsx
+import { IconPicker } from '@proveanything/smartlinks-utils-ui/icon-picker';
+
+<IconPicker
+  mode="dialog"
+  value="fa-solid fa-heart"
+  onSelect={(icon) => setIcon(icon.name)}
+  trigger={<Button>Pick icon</Button>}
+/>
+```
+
+**What it does:**
+- Searches **Font Awesome 7 Pro** (uses the shared kit `75493b59b3`)
+- Family hierarchy: Classic (Solid / Regular / Light), Duotone, and Brands
+- Search-first with a background catalogue crawler — first results appear instantly, the full index fills in behind
+- Auto-switches families intelligently (e.g. brand searches surface brand icons even when "Classic" is selected)
+
+> Requires the FA kit script to be present on the host page.
+
+---
+
+## Font Picker
+
+```tsx
+import { FontPicker } from '@proveanything/smartlinks-utils-ui/font-picker';
+
+<FontPicker
+  mode="dialog"
+  value="Inter"
+  showPreview
+  onSelect={(font) => {
+    console.log(font.family);        // "Inter"
+    console.log(font.cssFontFamily); // "'Inter', ui-sans-serif, system-ui, sans-serif"
+    console.log(font.loadSnippet);   // <link href="..." rel="stylesheet">
+  }}
+/>
+
+{/* With custom fonts uploaded into the collection */}
+<FontPicker
+  mode="dialog"
+  showCustomFonts
+  scope={{ collectionId: 'abc123' }}
+  onSelect={(font) => /* ... */}
+/>
+```
+
+**What it does:**
+- Full **Google Fonts** catalogue plus any **custom fonts** uploaded for the brand (stored via `appConfiguration` under `customFonts`)
+- Upload zone auto-detects weight/style from the filename (e.g. `MyFont-BoldItalic.woff2`)
+- Returns a `FontSelection` with `family`, `cssFontFamily`, and a ready-to-inject `loadSnippet` (`<link>` for Google fonts, `@font-face` CSS for custom uploads)
+- Lazy-loads previews via `IntersectionObserver`; includes a management UI for editing custom font definitions
+
+---
+
+## Conditions Editor
+
+```tsx
+import { ConditionsEditor } from '@proveanything/smartlinks-utils-ui/conditions-editor';
+
+<ConditionsEditor
+  value={rules}
+  onChange={setRules}
+  collectionId={collectionId}     // auto-loads facet definitions
+  versions={[{ title: 'Default', value: '' }]}
+  tags={['featured', 'new']}
+/>
+```
+
+**What it does:**
+- Recursive AND / OR group builder — nest conditions to any depth
+- **12 condition types:** Version, Country, Value, User, Date, Device, Tag, Facet, Geofence, Product, Item Status, Condition Reference
+- **Facet condition** auto-fetches definitions from `facets.publicList(collectionId, { includeValues: true })` when only `collectionId` is passed (SDK ≥ 1.9.20)
+- **Country picker** is a searchable multi-select with removable ISO 3166-1 chips and a "Use regions" toggle
+- Renders correctly inside iframe contexts — avoids `overflow-hidden` so dropdowns escape their cards
+
+---
+
+## Tree shaking
+
+Each component has its own subpath export:
+
+```tsx
+// Bundles only the Asset Picker
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+// Barrel import — bundler tree-shakes the rest
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui';
+```
+
+If you use subpath imports, import `styles.css` separately — subpaths do not pull it in automatically.
+
+---
+
+## Relationship to the core SDK
+
+```
+@proveanything/smartlinks            ← data layer (records, config, interactions, …)
+        ↑
+@proveanything/smartlinks-utils-ui   ← UI layer (components, hooks, admin shells)
+        ↑
+your microapp                        ← domain logic and custom forms
+```
+
+---
+
+## Further reading
+
+- [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
+- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all components
+- [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/openapi.yaml

@@ -17134,6 +17134,10 @@ components:
           type: string
         allowAutoGenerateClaims:
           type: boolean
+        variants:
+          type: boolean
+        batches:
+          type: boolean
         defaultAuthKitId:
           type: string
       required:
@@ -17159,6 +17163,8 @@ components:
         - supported
         - roles
         - shortId
+        - variants
+        - batches
         - defaultAuthKitId
     AppConfig:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.9.20",
+  "version": "1.9.22",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",