@proveanything/smartlinks-utils-ui 0.1.13 → 0.3.0

package/README.md

@@ -1,146 +1,182 @@
-# @proveanything/smartlinks-ui
+# @proveanything/smartlinks-utils-ui
 
-Reusable React components for [SmartLinks](https://smartlinks.app) microapps.
+Reusable React components for [SmartLinks](https://smartlinks.app) microapps —
+the headline module is **RecordsAdminShell**, a complete admin UI for the
+`app.records` pattern (per-product / per-variant / per-batch / per-facet data
+with scope inheritance). Also ships an Asset Picker, Icon Picker, Font Picker,
+and Conditions Editor.
+
+- Package: `@proveanything/smartlinks-utils-ui`
+- Tracks: `@proveanything/smartlinks ≥ 1.9`
+- See also: SDK docs [`ui-utils.md`](https://github.com/proveanything/smartlinks-sdk/blob/main/docs/ui-utils.md) and [`records-admin-pattern.md`](https://github.com/proveanything/smartlinks-sdk/blob/main/docs/records-admin-pattern.md)
 
 ## Installation
 
 ```bash
-npm install @proveanything/smartlinks-ui
+npm install @proveanything/smartlinks-utils-ui
 ```
 
-### Peer Dependencies
-
-This package requires the following peer dependencies in your app:
+### Peer dependencies
 
 ```bash
-npm install react react-dom @proveanything/smartlinks
+npm install react react-dom @proveanything/smartlinks @tanstack/react-query
 ```
 
+`@tanstack/react-query` is required by `RecordsAdminShell` (caching, pagination,
+optimistic save). Wrap your app in a `<QueryClientProvider>` somewhere up the
+tree.
+
 ## Setup
 
-Import the pre-compiled styles in your app's entry point:
+Import the pre-compiled styles **once** in your app entry (e.g. `main.tsx`):
 
 ```tsx
-import '@proveanything/smartlinks-ui/styles.css';
-// — OR, if you import the main barrel, CSS is included automatically:
-import { AssetPicker } from '@proveanything/smartlinks-ui';
+import '@proveanything/smartlinks-utils-ui/styles.css';
 ```
 
-This provides all the Tailwind utility classes used by the components. Your app still needs to define the CSS variables (e.g., `--primary`, `--border`) — these come from your own design system (shadcn, custom theme, etc.).
+Components inherit your shadcn-compatible CSS variables (`--primary`,
+`--background`, `--border`, …) and pick up your theme automatically.
 
-**Note:** If you use sub-path imports (e.g., `@proveanything/smartlinks-ui/asset-picker`), you must also import the styles separately since sub-path entry points don't include the CSS.
+## Modules
 
-## Components
+| Subpath | Module | Use when |
+|---------|--------|----------|
+| `/records-admin` | **RecordsAdminShell** + hooks (`useResolvedRecord`, `useRecordEditor`, …) | Building any per-product / per-variant / per-batch / per-facet admin |
+| `/asset-picker` | AssetPicker | Pick / upload / paste / URL-import media assets |
+| `/icon-picker` | IconPicker | Searchable Font Awesome 7 Pro picker |
+| `/font-picker` | FontPicker | Google Fonts + custom uploaded fonts |
+| `/conditions-editor` | ConditionsEditor | Recursive AND/OR rule builder (12 condition types) |
 
-### Asset Picker
+### Records Admin Shell
+
+```tsx
+import {
+  RecordsAdminShell,
+  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 }} // optional, from iframe URL
+  defaultData={() => ({})}
+  renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
+  renderPreview={({ resolved }) => <pre>{JSON.stringify(resolved, null, 2)}</pre>}
+/>
+```
 
-Browse, upload, and select media assets scoped to a collection, product, or proof.
+The shell renders the browser pane (scope tabs, search, status pills), the
+editor pane (sticky save / discard / delete footer with optimistic save), and
+the inheritance markers — you only provide the form for one record.
+
+On the **public widget** side, read the resolved value with `useResolvedRecord`:
 
 ```tsx
-import { AssetPicker } from '@proveanything/smartlinks-ui/asset-picker';
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { data, source, isLoading } = useResolvedRecord({
+  SL, appId, recordType: 'nutrition',
+  collectionId, productId, variantId, batchId,
+});
+// source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'universal' | null
+```
+
+### Asset Picker
+
+```tsx
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
 
 <AssetPicker
   scope={{ type: 'collection', collectionId: 'abc123' }}
   mode="dialog"
   allowUpload
-  onSelect={(asset) => console.log('Selected:', asset)}
-  trigger={<button>Choose Image</button>}
+  accept={['image/*']}
+  onSelect={(asset) => setHeroUrl(asset.url)}
+  trigger={<button>Choose image</button>}
 />
 ```
 
 ### Conditions Editor
 
-Visual editor for building condition rules with AND/OR logic groups.
-
 ```tsx
-import { ConditionsEditor } from '@proveanything/smartlinks-ui/conditions-editor';
+import { ConditionsEditor } from '@proveanything/smartlinks-utils-ui/conditions-editor';
 
 <ConditionsEditor
-  value={conditionGroup}
-  onChange={setConditionGroup}
-  // Optional: auto-loads facet definitions from SL.facets.publicList(collectionId)
-  collectionId={collectionId}
-  // …or pass them explicitly:
-  // facets={[{ key: 'colour', name: 'Colour', cardinality: 'multi',
-  //   values: [{ key: 'red', name: 'Red' }] }]}
+  value={rules}
+  onChange={setRules}
+  collectionId={collectionId} // auto-loads facet definitions
   versions={[{ title: 'Default', value: '' }]}
   tags={['featured', 'new']}
 />
 ```
 
-Supported condition types include **facet** (match against product facet
-definitions), version, country, value, user, date, device, label, geofence,
-product id, item status and condition reference.
-
 ### Icon Picker
 
-Searchable Font Awesome icon picker with lazy-loaded icon index for tree shaking.
-
 ```tsx
-import { IconPicker } from '@proveanything/smartlinks-ui/icon-picker';
+import { IconPicker } from '@proveanything/smartlinks-utils-ui/icon-picker';
 
 <IconPicker
   mode="dialog"
   value="fa-solid fa-heart"
-  onSelect={(icon) => console.log(icon.name)}
-  trigger={<button>Pick Icon</button>}
+  onSelect={(icon) => setIcon(icon.name)}
+  trigger={<button>Pick icon</button>}
 />
 ```
 
-### Font Picker
+Requires the Font Awesome 7 Pro kit script on the host page.
 
-Searchable font picker with Google Fonts catalog and support for custom uploaded fonts. Returns full loading metadata (CSS URLs, `@font-face` blocks, `cssFontFamily` strings) so the consumer knows exactly how to load the selected font.
+### Font Picker
 
 ```tsx
-import { FontPicker } from '@proveanything/smartlinks-ui/font-picker';
+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">
+    console.log(font.cssFontFamily); // ready for `font-family:` CSS
+    console.log(font.loadSnippet);   // <link> or @font-face block to inject
   }}
-  trigger={<button>Pick Font</button>}
-/>
-
-{/* With custom uploaded fonts from SmartLinks */}
-<FontPicker
-  mode="dialog"
-  showCustomFonts
-  scope={{ collectionId: 'abc123' }}
-  admin
-  onSelect={(font) => console.log(font)}
 />
 ```
 
 ## Prerequisites
 
-All components assume `@proveanything/smartlinks` is already initialized in your app via `SL.initializeApi()`. Components that interact with the SmartLinks API (Asset Picker) will use the global SDK import directly.
+All components assume `@proveanything/smartlinks` is initialised in your app
+via `SL.initializeApi()`. Admin components (RecordsAdminShell, AssetPicker
+upload, etc.) call the SDK with `admin: true` — do not render them in
+public-facing views.
 
-## Tree Shaking
+## Tree shaking
 
-Each component is a separate entry point. If you only import `AssetPicker`, the Icon Picker's Font Awesome index won't be bundled.
+Each component has its own subpath export — bundle only what you use:
 
 ```tsx
-// ✅ Only loads AssetPicker code
-import { AssetPicker } from '@proveanything/smartlinks-ui/asset-picker';
+// Bundles only RecordsAdmin
+import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
 
-// ✅ Also works — barrel import, bundler tree-shakes unused
-import { AssetPicker } from '@proveanything/smartlinks-ui';
+// Barrel import — bundler tree-shakes the rest
+import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui';
 ```
 
+If you use subpath imports, import `styles.css` separately — subpaths do not
+pull it in automatically.
+
 ## Development
 
 ```bash
 cd packages/smartlinks-ui
 npm install
-npm run build    # Build with tsup
-npm run dev      # Watch mode
+npm run build    # tsup
+npm run dev      # watch mode
 ```
 
 ## License
 
-MIT
+MIT