@proveanything/smartlinks-utils-ui 0.2.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

package/dist/components/RecordsAdmin/index.css

@@ -0,0 +1,40 @@
+/* src/components/RecordsAdmin/shell/tokens.css */
+:root {
+  --ra-status-own: var(--ra-emerald, 142 71% 45%);
+  --ra-status-shared: var(--ra-amber, 38 92% 50%);
+  --ra-status-missing: var(--muted-foreground, 0 0% 50%);
+  --ra-accent: var(--primary, 222 47% 11%);
+  --ra-surface: var(--card, 0 0% 100%);
+  --ra-border: var(--border, 0 0% 90%);
+  --ra-text: var(--foreground, 0 0% 10%);
+  --ra-muted: var(--muted, 0 0% 96%);
+  --ra-muted-text: var(--muted-foreground, 0 0% 40%);
+  --ra-radius: 0.5rem;
+  --ra-dot-size: 0.5rem;
+}
+.ra-shell {
+  color: hsl(var(--ra-text));
+  background: hsl(var(--ra-surface));
+}
+.ra-status-dot {
+  display: inline-block;
+  width: var(--ra-dot-size);
+  height: var(--ra-dot-size);
+  border-radius: 9999px;
+  flex-shrink: 0;
+}
+.ra-status-own {
+  background: hsl(var(--ra-status-own));
+}
+.ra-status-shared {
+  background: hsl(var(--ra-status-shared));
+}
+.ra-status-missing {
+  background: hsl(var(--ra-status-missing) / 0.4);
+  border: 1px solid hsl(var(--ra-status-missing) / 0.6);
+}
+.ra-row-active {
+  background: hsl(var(--ra-accent) / 0.08);
+  border-color: hsl(var(--ra-accent) / 0.4) !important;
+}
+/*# sourceMappingURL=index.css.map */

package/dist/components/RecordsAdmin/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/RecordsAdmin/shell/tokens.css"],"sourcesContent":["/* Records Admin shell tokens — apps may override via :root */\r\n:root {\r\n  --ra-status-own: var(--ra-emerald, 142 71% 45%);\r\n  --ra-status-shared: var(--ra-amber, 38 92% 50%);\r\n  --ra-status-missing: var(--muted-foreground, 0 0% 50%);\r\n  --ra-accent: var(--primary, 222 47% 11%);\r\n  --ra-surface: var(--card, 0 0% 100%);\r\n  --ra-border: var(--border, 0 0% 90%);\r\n  --ra-text: var(--foreground, 0 0% 10%);\r\n  --ra-muted: var(--muted, 0 0% 96%);\r\n  --ra-muted-text: var(--muted-foreground, 0 0% 40%);\r\n  --ra-radius: 0.5rem;\r\n  --ra-dot-size: 0.5rem;\r\n}\r\n\r\n.ra-shell {\r\n  color: hsl(var(--ra-text));\r\n  background: hsl(var(--ra-surface));\r\n}\r\n\r\n.ra-status-dot {\r\n  display: inline-block;\r\n  width: var(--ra-dot-size);\r\n  height: var(--ra-dot-size);\r\n  border-radius: 9999px;\r\n  flex-shrink: 0;\r\n}\r\n.ra-status-own { background: hsl(var(--ra-status-own)); }\r\n.ra-status-shared { background: hsl(var(--ra-status-shared)); }\r\n.ra-status-missing { background: hsl(var(--ra-status-missing) / 0.4); border: 1px solid hsl(var(--ra-status-missing) / 0.6); }\r\n\r\n.ra-row-active {\r\n  background: hsl(var(--ra-accent) / 0.08);\r\n  border-color: hsl(var(--ra-accent) / 0.4) !important;\r\n}"],"mappings":";AACA;AACE,mBAAiB,IAAI,YAAY,EAAE,IAAI,IAAI;AAC3C,sBAAoB,IAAI,UAAU,EAAE,GAAG,IAAI;AAC3C,uBAAqB,IAAI,kBAAkB,EAAE,EAAE,GAAG;AAClD,eAAa,IAAI,SAAS,EAAE,IAAI,IAAI;AACpC,gBAAc,IAAI,MAAM,EAAE,EAAE,GAAG;AAC/B,eAAa,IAAI,QAAQ,EAAE,EAAE,GAAG;AAChC,aAAW,IAAI,YAAY,EAAE,EAAE,GAAG;AAClC,cAAY,IAAI,OAAO,EAAE,EAAE,GAAG;AAC9B,mBAAiB,IAAI,kBAAkB,EAAE,EAAE,GAAG;AAC9C,eAAa;AACb,iBAAe;AACjB;AAEA,CAAC;AACC,SAAO,IAAI,IAAI;AACf,cAAY,IAAI,IAAI;AACtB;AAEA,CAAC;AACC,WAAS;AACT,SAAO,IAAI;AACX,UAAQ,IAAI;AACZ,iBAAe;AACf,eAAa;AACf;AACA,CAAC;AAAgB,cAAY,IAAI,IAAI;AAAmB;AACxD,CAAC;AAAmB,cAAY,IAAI,IAAI;AAAsB;AAC9D,CAAC;AAAoB,cAAY,IAAI,IAAI,qBAAqB,EAAE;AAAM,UAAQ,IAAI,MAAM,IAAI,IAAI,qBAAqB,EAAE;AAAM;AAE7H,CAAC;AACC,cAAY,IAAI,IAAI,aAAa,EAAE;AACnC,gBAAc,IAAI,IAAI,aAAa,EAAE;AACvC;","names":[]}