@proveanything/smartlinks-utils-ui 0.10.8 → 0.11.0

package/dist/index.d.ts

@@ -66,7 +66,57 @@ interface AdminPageHeaderProps {
 }
 declare function AdminPageHeader({ title, subtitle, icon, helpUrl, helpLabel, actions, aside, intro, className, }: AdminPageHeaderProps): react_jsx_runtime.JSX.Element;
 
+declare const HINTS_PREFS_APP_ID = "prefs";
+declare const HINTS_PREFS_KEY = "showHints";
+interface UseHintsPreferenceResult {
+    /** Whether inline hints / intro cards should be shown by default. */
+    showHints: boolean;
+    /** True until the first read from `userAppData` resolves. */
+    isLoading: boolean;
+    /** Persist a new value on the user record. */
+    setShowHints: (next: boolean) => Promise<void>;
+}
+/**
+ * Subscribe to the user's global `showHints` preference. Optimistic; defaults
+ * to `true` while loading so admins coming in fresh always see the help.
+ */
+declare function useHintsPreference(SL: any): UseHintsPreferenceResult;
+
+interface UseIntroStateArgs {
+    /** SmartLinks SDK namespace (`* as SL from '@proveanything/smartlinks'`). */
+    SL: any;
+    /**
+     * Stable per-app key used for the browser-level dismiss. Usually the
+     * app's `appId`. Pass a more specific value (e.g. `${appId}:rules`) if
+     * you have multiple intros within one app.
+     */
+    persistKey: string;
+}
+interface UseIntroStateResult {
+    /** Whether the intro card is currently dismissed/collapsed. */
+    dismissed: boolean;
+    /** Wire to AdminPageHeader's `intro.onDismiss`. */
+    onDismiss: () => void;
+    /** Wire to AdminPageHeader's `intro.onReopen`. Always available. */
+    onReopen: () => void;
+    /** True until the user preference has finished loading. */
+    isLoading: boolean;
+}
+/** Resolve dismiss state from global pref + per-browser flag. */
+declare function useIntroState({ SL, persistKey }: UseIntroStateArgs): UseIntroStateResult;
+
+interface HintsPreferenceToggleProps {
+    /** SmartLinks SDK namespace (`* as SL from '@proveanything/smartlinks'`). */
+    SL: any;
+    /** Visible label. Default: "Show inline help". */
+    label?: string;
+    /** Optional helper line under the label. */
+    description?: string;
+    className?: string;
+}
+declare function HintsPreferenceToggle({ SL, label, description, className, }: HintsPreferenceToggleProps): react_jsx_runtime.JSX.Element;
+
 /** Merge Tailwind classes with clsx — same pattern as shadcn/ui */
 declare function cn(...inputs: ClassValue[]): string;
 
-export { AdminPageHeader, type AdminPageHeaderIntro, type AdminPageHeaderIntroTone, type AdminPageHeaderProps, cn };
+export { AdminPageHeader, type AdminPageHeaderIntro, type AdminPageHeaderIntroTone, type AdminPageHeaderProps, HINTS_PREFS_APP_ID, HINTS_PREFS_KEY, HintsPreferenceToggle, type HintsPreferenceToggleProps, type UseHintsPreferenceResult, type UseIntroStateArgs, type UseIntroStateResult, cn, useHintsPreference, useIntroState };

package/dist/index.js

@@ -2,15 +2,46 @@ export { ASSET_MIME_FILTERS, AssetPicker, useAssets } from './chunk-2IQEDRSZ.js'
 export { ConditionsEditor } from './chunk-7UBXTFZQ.js';
 export { IconPicker } from './chunk-JQPS5XPJ.js';
 export { CATEGORY_FALLBACKS, CATEGORY_LABELS, FontPicker, GOOGLE_FONTS_CATALOG, getGoogleFontUrl } from './chunk-OTJV62XV.js';
-export { AdminPageHeader } from './chunk-2MW54ZVG.js';
+import { useHintsPreference } from './chunk-BNC6Z6WB.js';
+export { AdminPageHeader, HINTS_PREFS_APP_ID, HINTS_PREFS_KEY, useHintsPreference, useIntroState } from './chunk-BNC6Z6WB.js';
 import { assertStylesLoaded } from './chunk-OLYC54YT.js';
 import './chunk-5UQQYXCX.js';
 import './chunk-S27GIYV7.js';
 export { FacetRuleEditor } from './chunk-JMCV6FOW.js';
 import './chunk-4LHF5JB7.js';
 export { cn } from './chunk-L7FQ52F5.js';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+function HintsPreferenceToggle({
+  SL,
+  label = "Show inline help",
+  description,
+  className
+}) {
+  const { showHints, setShowHints, isLoading } = useHintsPreference(SL);
+  return /* @__PURE__ */ jsxs("label", { className, style: { display: "flex", alignItems: "flex-start", gap: "0.5rem", cursor: "pointer" }, children: [
+    /* @__PURE__ */ jsx(
+      "input",
+      {
+        type: "checkbox",
+        checked: showHints,
+        disabled: isLoading,
+        onChange: (e) => {
+          void setShowHints(e.target.checked);
+        },
+        style: { marginTop: "0.2rem" }
+      }
+    ),
+    /* @__PURE__ */ jsxs("span", { children: [
+      /* @__PURE__ */ jsx("span", { style: { fontWeight: 500 }, children: label }),
+      description ? /* @__PURE__ */ jsx("span", { style: { display: "block", fontSize: "0.85em", opacity: 0.7 }, children: description }) : null
+    ] })
+  ] });
+}
 
 // src/index.ts
 assertStylesLoaded();
+
+export { HintsPreferenceToggle };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAOA,kBAAA,EAAmB","file":"index.js","sourcesContent":["// =============================================================================\r\n// @proveanything/smartlinks-ui\r\n// =============================================================================\r\n\r\n// Pre-compiled Tailwind utilities — tsup processes this through PostCSS\r\nimport './styles.css';\r\nimport { assertStylesLoaded } from './utils/assertStylesLoaded';\r\nassertStylesLoaded();\r\n\r\n// --- Asset Picker ---\r\nexport { AssetPicker, useAssets } from './components/AssetPicker';\r\nexport type {\r\n  AssetPickerProps,\r\n  AssetPickerMode,\r\n  AssetScope,\r\n  AssetPickerSelection,\r\n  AssetItem,\r\n  AssetViewMode,\r\n  AssetMimeFilter,\r\n} from './components/AssetPicker/types';\r\nexport { ASSET_MIME_FILTERS } from './components/AssetPicker/types';\r\n\r\n// --- Admin Page Header ---\r\nexport { AdminPageHeader } from './components/AdminPageHeader';\r\nexport type {\r\n  AdminPageHeaderProps,\r\n  AdminPageHeaderIntro,\r\n  AdminPageHeaderIntroTone,\r\n} from './components/AdminPageHeader';\r\n\r\n// --- Conditions Editor ---\r\nexport { ConditionsEditor } from './components/ConditionsEditor';\r\nexport type {\r\n  ConditionsEditorProps,\r\n  Condition,\r\n  ConditionGroup,\r\n  ConditionType,\r\n  ConditionTypeMeta,\r\n  SelectOption,\r\n  VersionOption,\r\n} from './components/ConditionsEditor/types';\r\n\r\n// --- Facet Rule Editor (records targeting) ---\r\nexport { FacetRuleEditor } from './components/FacetRuleEditor';\r\nexport type {\r\n  FacetRuleEditorProps,\r\n  FacetRule,\r\n  FacetRuleClause,\r\n} from './components/FacetRuleEditor/types';\r\n\r\n// --- Icon Picker ---\r\nexport { IconPicker } from './components/IconPicker';\r\nexport type {\r\n  IconPickerProps,\r\n  IconSelection,\r\n} from './components/IconPicker/types';\r\n\r\n// --- Font Picker ---\r\nexport { FontPicker } from './components/FontPicker';\r\nexport type {\r\n  FontPickerProps,\r\n  FontSelection,\r\n  FontSource,\r\n  FontCategory,\r\n  FontWeight,\r\n  FontEntry,\r\n  FontScope,\r\n} from './components/FontPicker/types';\r\nexport { GOOGLE_FONTS_CATALOG, getGoogleFontUrl, CATEGORY_LABELS, CATEGORY_FALLBACKS } from './components/FontPicker/google-fonts';\r\n\r\n// --- Shared utilities ---\r\nexport { cn } from './utils/cn';\r\n"]}
+{"version":3,"sources":["../src/hints/HintsPreferenceToggle.tsx","../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAmBO,SAAS,qBAAA,CAAsB;AAAA,EACpC,EAAA;AAAA,EAAI,KAAA,GAAQ,kBAAA;AAAA,EAAoB,WAAA;AAAA,EAAa;AAC/C,CAAA,EAA+B;AAC7B,EAAA,MAAM,EAAE,SAAA,EAAW,YAAA,EAAc,SAAA,EAAU,GAAI,mBAAmB,EAAE,CAAA;AACpE,EAAA,uBACE,IAAA,CAAC,OAAA,EAAA,EAAM,SAAA,EAAsB,KAAA,EAAO,EAAE,OAAA,EAAS,MAAA,EAAQ,UAAA,EAAY,YAAA,EAAc,GAAA,EAAK,QAAA,EAAU,MAAA,EAAQ,WAAU,EAChH,QAAA,EAAA;AAAA,oBAAA,GAAA;AAAA,MAAC,OAAA;AAAA,MAAA;AAAA,QACC,IAAA,EAAK,UAAA;AAAA,QACL,OAAA,EAAS,SAAA;AAAA,QACT,QAAA,EAAU,SAAA;AAAA,QACV,QAAA,EAAU,CAAC,CAAA,KAAM;AAAE,UAAA,KAAK,YAAA,CAAa,CAAA,CAAE,MAAA,CAAO,OAAO,CAAA;AAAA,QAAG,CAAA;AAAA,QACxD,KAAA,EAAO,EAAE,SAAA,EAAW,QAAA;AAAS;AAAA,KAC/B;AAAA,yBACC,MAAA,EAAA,EACC,QAAA,EAAA;AAAA,sBAAA,GAAA,CAAC,UAAK,KAAA,EAAO,EAAE,UAAA,EAAY,GAAA,IAAQ,QAAA,EAAA,KAAA,EAAM,CAAA;AAAA,MACxC,WAAA,mBACC,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAO,EAAE,OAAA,EAAS,OAAA,EAAS,QAAA,EAAU,QAAA,EAAU,OAAA,EAAS,GAAA,EAAI,EAAI,uBAAY,CAAA,GAChF;AAAA,KAAA,EACN;AAAA,GAAA,EACF,CAAA;AAEJ;;;ACjCA,kBAAA,EAAmB","file":"index.js","sourcesContent":["// =============================================================================\r\n// HintsPreferenceToggle\r\n//\r\n// Tiny opt-in component that flips the global `prefs.showHints` flag on the\r\n// user record. Drop into any settings/account surface — the value affects\r\n// every SmartLinks admin app the user opens, no per-app wiring required.\r\n// =============================================================================\r\nimport { useHintsPreference } from './useHintsPreference';\r\n\r\nexport interface HintsPreferenceToggleProps {\r\n  /** SmartLinks SDK namespace (`* as SL from '@proveanything/smartlinks'`). */\r\n  SL: any;\r\n  /** Visible label. Default: \"Show inline help\". */\r\n  label?: string;\r\n  /** Optional helper line under the label. */\r\n  description?: string;\r\n  className?: string;\r\n}\r\n\r\nexport function HintsPreferenceToggle({\r\n  SL, label = 'Show inline help', description, className,\r\n}: HintsPreferenceToggleProps) {\r\n  const { showHints, setShowHints, isLoading } = useHintsPreference(SL);\r\n  return (\r\n    <label className={className} style={{ display: 'flex', alignItems: 'flex-start', gap: '0.5rem', cursor: 'pointer' }}>\r\n      <input\r\n        type=\"checkbox\"\r\n        checked={showHints}\r\n        disabled={isLoading}\r\n        onChange={(e) => { void setShowHints(e.target.checked); }}\r\n        style={{ marginTop: '0.2rem' }}\r\n      />\r\n      <span>\r\n        <span style={{ fontWeight: 500 }}>{label}</span>\r\n        {description ? (\r\n          <span style={{ display: 'block', fontSize: '0.85em', opacity: 0.7 }}>{description}</span>\r\n        ) : null}\r\n      </span>\r\n    </label>\r\n  );\r\n}\r\n","// =============================================================================\r\n// @proveanything/smartlinks-ui\r\n// =============================================================================\r\n\r\n// Pre-compiled Tailwind utilities — tsup processes this through PostCSS\r\nimport './styles.css';\r\nimport { assertStylesLoaded } from './utils/assertStylesLoaded';\r\nassertStylesLoaded();\r\n\r\n// --- Asset Picker ---\r\nexport { AssetPicker, useAssets } from './components/AssetPicker';\r\nexport type {\r\n  AssetPickerProps,\r\n  AssetPickerMode,\r\n  AssetScope,\r\n  AssetPickerSelection,\r\n  AssetItem,\r\n  AssetViewMode,\r\n  AssetMimeFilter,\r\n} from './components/AssetPicker/types';\r\nexport { ASSET_MIME_FILTERS } from './components/AssetPicker/types';\r\n\r\n// --- Admin Page Header ---\r\nexport { AdminPageHeader } from './components/AdminPageHeader';\r\nexport type {\r\n  AdminPageHeaderProps,\r\n  AdminPageHeaderIntro,\r\n  AdminPageHeaderIntroTone,\r\n} from './components/AdminPageHeader';\r\n\r\n// --- Hints (global user preference + per-browser dismiss) ---\r\nexport {\r\n  useHintsPreference, useIntroState, HintsPreferenceToggle,\r\n  HINTS_PREFS_APP_ID, HINTS_PREFS_KEY,\r\n} from './hints';\r\nexport type {\r\n  UseHintsPreferenceResult, UseIntroStateArgs, UseIntroStateResult,\r\n  HintsPreferenceToggleProps,\r\n} from './hints';\r\n\r\n// --- Conditions Editor ---\r\nexport { ConditionsEditor } from './components/ConditionsEditor';\r\nexport type {\r\n  ConditionsEditorProps,\r\n  Condition,\r\n  ConditionGroup,\r\n  ConditionType,\r\n  ConditionTypeMeta,\r\n  SelectOption,\r\n  VersionOption,\r\n} from './components/ConditionsEditor/types';\r\n\r\n// --- Facet Rule Editor (records targeting) ---\r\nexport { FacetRuleEditor } from './components/FacetRuleEditor';\r\nexport type {\r\n  FacetRuleEditorProps,\r\n  FacetRule,\r\n  FacetRuleClause,\r\n} from './components/FacetRuleEditor/types';\r\n\r\n// --- Icon Picker ---\r\nexport { IconPicker } from './components/IconPicker';\r\nexport type {\r\n  IconPickerProps,\r\n  IconSelection,\r\n} from './components/IconPicker/types';\r\n\r\n// --- Font Picker ---\r\nexport { FontPicker } from './components/FontPicker';\r\nexport type {\r\n  FontPickerProps,\r\n  FontSelection,\r\n  FontSource,\r\n  FontCategory,\r\n  FontWeight,\r\n  FontEntry,\r\n  FontScope,\r\n} from './components/FontPicker/types';\r\nexport { GOOGLE_FONTS_CATALOG, getGoogleFontUrl, CATEGORY_LABELS, CATEGORY_FALLBACKS } from './components/FontPicker/google-fonts';\r\n\r\n// --- Shared utilities ---\r\nexport { cn } from './utils/cn';\r\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks-utils-ui",
-  "version": "0.10.8",
+  "version": "0.11.0",
   "description": "Reusable React components for SmartLinks microapps — Asset Picker, Conditions Editor, Icon Picker, and more.",
   "type": "module",
   "main": "dist/index.js",

package/dist/chunk-2MW54ZVG.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/AdminPageHeader/AdminPageHeader.tsx"],"names":[],"mappings":"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","file":"chunk-2MW54ZVG.js","sourcesContent":["// =============================================================================\r\n// AdminPageHeader\r\n//\r\n// A standardised page header for any SmartLinks admin surface. Designed to be\r\n// used standalone (lightweight apps that don't need the full RecordsAdminShell)\r\n// or composed inside other shells. Supports:\r\n//\r\n//   • Inline icon + title + full-width subtitle\r\n//   • Right-aligned slot for app-specific actions (e.g. \"+ New\" button)\r\n//   • External help link (icon-button that opens docs in a new tab)\r\n//   • Optional dismissible intro card with `?` reopen affordance\r\n//   • Optional `aside` slot for extra header content (stats strips, etc.)\r\n//\r\n// Styling is self-contained under `.sl-aph` and reuses the shared `--ra-*`\r\n// design tokens with sensible fallbacks, so it themes correctly whether the\r\n// host has loaded the records-admin token sheet or not.\r\n// =============================================================================\r\nimport { type ReactNode, useId } from 'react';\r\nimport { BookOpen, HelpCircle, X, Lightbulb, CheckCircle2, AlertTriangle, Info } from 'lucide-react';\r\nimport './admin-page-header.css';\r\n\r\nexport type AdminPageHeaderIntroTone = 'info' | 'success' | 'warning';\r\n\r\nexport interface AdminPageHeaderIntro {\r\n  /** Short headline shown in bold at the start of the intro card. */\r\n  title: string;\r\n  /** Body content — plain text or rich nodes. */\r\n  body: ReactNode;\r\n  /** Visual tone — controls icon and surface tint. Default `'info'`. */\r\n  tone?: AdminPageHeaderIntroTone;\r\n  /** Optional action node rendered inline after the body (e.g. a Learn-more link). */\r\n  action?: ReactNode;\r\n  /** Whether the intro is currently dismissed. Controlled. */\r\n  dismissed: boolean;\r\n  /** Called when the user clicks the dismiss `X`. */\r\n  onDismiss: () => void;\r\n  /**\r\n   * Called when the user clicks the reopen `?` button (only rendered when\r\n   * dismissed is true). Omit to hide the reopen affordance entirely.\r\n   */\r\n  onReopen?: () => void;\r\n  /** Tooltip / aria-label for the reopen button. Default \"How it works\". */\r\n  reopenLabel?: string;\r\n}\r\n\r\nexport interface AdminPageHeaderProps {\r\n  /** Page title — required. */\r\n  title: string;\r\n  /** Single-line muted subtitle under the title. */\r\n  subtitle?: string;\r\n  /** Icon rendered inline before the title. Pass a Lucide element or any node. */\r\n  icon?: ReactNode;\r\n  /**\r\n   * External help / documentation URL. When set, renders a small icon-button\r\n   * that opens the URL in a new tab. Use this to point at app-specific docs.\r\n   */\r\n  helpUrl?: string;\r\n  /** Tooltip / aria-label for the help link. Default \"Help & documentation\". */\r\n  helpLabel?: string;\r\n  /**\r\n   * Right-aligned action slot — typically a primary \"+ New\" button and/or\r\n   * secondary controls. Rendered before the help / intro-reopen icon-buttons.\r\n   */\r\n  actions?: ReactNode;\r\n  /**\r\n   * Extra header content rendered between `actions` and the trailing\r\n   * help / reopen icon-buttons. Used by RecordsAdminShell for its stats strip;\r\n   * standalone apps rarely need it.\r\n   */\r\n  aside?: ReactNode;\r\n  /**\r\n   * Optional dismissible intro card rendered below the header row.\r\n   * See {@link AdminPageHeaderIntro}.\r\n   */\r\n  intro?: AdminPageHeaderIntro;\r\n  /** Extra class on the root container for layout overrides. */\r\n  className?: string;\r\n}\r\n\r\nconst TONE_ICON = {\r\n  info: Lightbulb,\r\n  success: CheckCircle2,\r\n  warning: AlertTriangle,\r\n} as const;\r\n\r\nexport function AdminPageHeader({\r\n  title, subtitle, icon, helpUrl, helpLabel,\r\n  actions, aside, intro, className,\r\n}: AdminPageHeaderProps) {\r\n  const titleId = useId();\r\n  const resolvedHelpLabel = helpLabel ?? 'Help & documentation';\r\n  const resolvedReopenLabel = intro?.reopenLabel ?? 'How it works';\r\n  const showReopen = !!intro && intro.dismissed && !!intro.onReopen;\r\n  const showIntro = !!intro && !intro.dismissed;\r\n\r\n  return (\r\n    <header className={`sl-aph${className ? ` ${className}` : ''}`} aria-labelledby={titleId}>\r\n      <div className=\"sl-aph__row\">\r\n        <div className=\"sl-aph__main\">\r\n          <div className=\"sl-aph__text\">\r\n            <h1 className=\"sl-aph__title\" id={titleId}>\r\n              {icon ? (\r\n                <span className=\"sl-aph__icon\" aria-hidden=\"true\">{icon}</span>\r\n              ) : null}\r\n              <span>{title}</span>\r\n            </h1>\r\n            {subtitle ? <p className=\"sl-aph__subtitle\">{subtitle}</p> : null}\r\n          </div>\r\n        </div>\r\n        {(actions || aside || helpUrl || showReopen) ? (\r\n          <div className=\"sl-aph__aside\">\r\n            {actions}\r\n            {aside}\r\n            {helpUrl ? (\r\n              <a\r\n                href={helpUrl}\r\n                target=\"_blank\"\r\n                rel=\"noopener noreferrer\"\r\n                className=\"sl-aph__icon-btn\"\r\n                aria-label={resolvedHelpLabel}\r\n                title={resolvedHelpLabel}\r\n              >\r\n                <BookOpen aria-hidden=\"true\" />\r\n              </a>\r\n            ) : null}\r\n            {showReopen ? (\r\n              <button\r\n                type=\"button\"\r\n                onClick={intro!.onReopen}\r\n                className=\"sl-aph__icon-btn\"\r\n                aria-label={resolvedReopenLabel}\r\n                title={resolvedReopenLabel}\r\n              >\r\n                <HelpCircle aria-hidden=\"true\" />\r\n              </button>\r\n            ) : null}\r\n          </div>\r\n        ) : null}\r\n      </div>\r\n      {showIntro ? <AdminPageHeaderIntroCard intro={intro!} /> : null}\r\n    </header>\r\n  );\r\n}\r\n\r\nfunction AdminPageHeaderIntroCard({ intro }: { intro: AdminPageHeaderIntro }) {\r\n  const tone = intro.tone ?? 'info';\r\n  const Icon = TONE_ICON[tone] ?? Info;\r\n  return (\r\n    <div className=\"sl-aph__intro\" data-tone={tone} role=\"note\">\r\n      <div className=\"sl-aph__intro-icon\">\r\n        <Icon aria-hidden=\"true\" style={{ width: '0.95rem', height: '0.95rem' }} />\r\n      </div>\r\n      <div className=\"sl-aph__intro-body\">\r\n        <h4 className=\"sl-aph__intro-title\">{intro.title}</h4>\r\n        <span className=\"sl-aph__intro-text\">{intro.body}</span>\r\n        {intro.action ? <span className=\"sl-aph__intro-action\">{intro.action}</span> : null}\r\n      </div>\r\n      <button\r\n        type=\"button\"\r\n        onClick={intro.onDismiss}\r\n        aria-label=\"Dismiss\"\r\n        className=\"sl-aph__intro-dismiss\"\r\n      >\r\n        <X aria-hidden=\"true\" style={{ width: '0.875rem', height: '0.875rem' }} />\r\n      </button>\r\n    </div>\r\n  );\r\n}"]}