@llmnative/react 1.5.0 → 1.6.0

package/dist/types/src/App.d.ts

@@ -8,6 +8,7 @@ import type { AuthProviderAdapter } from "./providers/auth/AuthProvider";
 import type { EmailProviderAdapter } from "./providers/email/EmailProvider";
 import type { CredentialsAdapter } from "./providers/credentials/CredentialsProvider";
 import { type AppIconProviderConfig } from "./providers/icon/IconProviderContext";
+import type { GoogleMapsConfig } from "./providers/googleMaps/loadGoogleMaps";
 import { type I18nConfig } from "./I18n";
 import { type ServicesConfig, type GoogleProviderConfig, type SupabaseProviderConfig, type MockProviderConfig } from "./providers/manifest";
 interface MenuItem {
@@ -81,6 +82,8 @@ export type AppProviderProps = {
     providers?: AppProvidersConfig;
     /** Icon provider registry config. String shorthand selects the default provider id. */
     iconProvider?: AppIconProviderConfig;
+    /** Google Maps/Places config consumed by `<AddressAutocomplete>`. Omit to leave it unconfigured. */
+    googleMaps?: GoogleMapsConfig;
     /** Theme registry config. String shorthand selects the active theme id. */
     themeProvider?: AppThemeProviderConfig;
     /** Internationalization config: locale and per-locale translation overrides. */
@@ -110,8 +113,8 @@ export declare const getContextMenu: () => string[];
  *
  * Wraps children with: ErrorBoundary → BrowserRouter → RuntimeProvider →
  * AuthProvider → CredentialsProvider → DataProvider → StorageProvider →
- * EmailProvider → AIProvider → IconProvider → HeadProvider → I18nProvider →
- * ThemeProvider → [contextProviders] → children.
+ * EmailProvider → AIProvider → IconProvider → GoogleMapsProvider → HeadProvider →
+ * I18nProvider → ThemeProvider → [contextProviders] → children.
  *
  * `contextProviders` runs inside DataProvider, so vertical-specific providers
  * mounted there can call `useDataProvider()`, `useI18n()`, etc. directly.
@@ -119,7 +122,7 @@ export declare const getContextMenu: () => string[];
  * `App` uses `AppProvider` internally. Use `AppProvider` directly only when
  * you need the provider stack without the routing layer (e.g. tests, Storybook).
  */
-export declare function AppProvider({ contextProviders, providers, appName, scrapeConfig, iconProvider, themeProvider, i18n, children, errorReportUrl, debug, basename, }: AppProviderProps): React.JSX.Element;
+export declare function AppProvider({ contextProviders, providers, appName, scrapeConfig, iconProvider, googleMaps, themeProvider, i18n, children, errorReportUrl, debug, basename, }: AppProviderProps): React.JSX.Element;
 declare function App({ importPage, LayoutDefault, menuConfig, children, ...providerProps }: AppProps): React.JSX.Element;
 export declare const useMenu: (type: string) => UseMenuItem[];
 export default App;

package/dist/types/src/I18n.d.ts

@@ -71,6 +71,9 @@ export interface I18nDict {
         removeFile: string;
         uploadAnother: string;
         dropToParse: string;
+        insertFromUrl: string;
+        urlPlaceholder: string;
+        invalidUrl: string;
     };
     notifications: {
         title: string;
@@ -156,6 +159,13 @@ export interface I18nDict {
         dragToResize: string;
         dragHere: string;
     };
+    addressAutocomplete: {
+        placeholder: string;
+        noResults: string;
+        searching: string;
+        notConfigured: string;
+        loadError: string;
+    };
 }
 type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];

package/dist/types/src/Theme.d.ts

@@ -271,6 +271,12 @@ export interface ThemeConfig {
         wrapperClassName?: string;
         className?: string;
     };
+    AddressAutocomplete?: {
+        wrapperClassName?: string;
+        className?: string;
+        menuClassName?: string;
+        itemClassName?: string;
+    };
     Form?: {
         wrapperClassName?: string;
         buttonSaveClass?: string;

package/dist/types/src/components/index.d.ts

@@ -43,6 +43,7 @@ export { default as Icon } from './ui/Icon';
 export { LayoutBuilder } from './ui/LayoutBuilder';
 export * from './ui/fields/Input';
 export * from './ui/fields/Select';
+export * from './ui/fields/AddressAutocomplete';
 export * from './ui/fields/Upload';
 export * from './ui/fields/Crop';
 export * from './ui/fields/UploadCSV';

package/dist/types/src/components/ui/Card.d.ts

@@ -12,8 +12,10 @@ export interface CardProps extends UIProps {
     footerClassName?: string;
     /** Show a loading skeleton instead of content. */
     loading?: boolean;
+    /** Minimum height reserved for the loading overlay. Defaults to `200px`. */
+    loaderMinHeight?: string | number;
     before?: React.ReactNode;
     after?: React.ReactNode;
 }
-declare const Card: ({ children, title, header, footer, loading, wrapperClassName, className, headerClassName, bodyClassName, footerClassName, before, after, }: CardProps) => React.JSX.Element;
+declare const Card: ({ children, title, header, footer, loading, loaderMinHeight, wrapperClassName, className, headerClassName, bodyClassName, footerClassName, before, after, }: CardProps) => React.JSX.Element;
 export default Card;

package/dist/types/src/components/ui/Loader.d.ts

@@ -8,6 +8,8 @@ interface LoaderProps extends UIProps {
     icon?: string;
     title?: string;
     description?: string;
+    /** Minimum height reserved for the overlay while there is no content to size against. Defaults to `200px`. */
+    minHeight?: string | number;
 }
-declare function Loader({ children, show, icon, title, description, before, after, wrapperClassName, className }: LoaderProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
+declare function Loader({ children, show, icon, title, description, minHeight, before, after, wrapperClassName, className }: LoaderProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 export default Loader;

package/dist/types/src/components/ui/fields/AddressAutocomplete.d.ts

@@ -0,0 +1,80 @@
+import React from 'react';
+import { FormFieldProps } from '../../widgets/Form';
+import type { FieldValue } from '../../../providers/data/DataProvider';
+export interface ParsedAddress {
+    street?: string;
+    city?: string;
+    /** Province (administrative_area_level_2), falling back to the region when a country has no province level. */
+    state?: string;
+    zip?: string;
+    country?: string;
+    countryCode?: string;
+    lat?: number;
+    lng?: number;
+    formatted?: string;
+}
+/**
+ * Overrides the default sub-field paths. Each key defaults to `${name}.<key>` (e.g. `name="address"`
+ * → `address.street`) — set any of these to an unrelated, absolute field path to write there instead.
+ */
+export interface AddressAutocompleteFieldNames {
+    street?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    country?: string;
+    countryCode?: string;
+    lat?: string;
+    lng?: string;
+    zoom?: string;
+    formatted?: string;
+}
+export interface AddressAutocompleteMapOptions {
+    /** Where the map renders relative to the search box. Defaults to `'below'`. */
+    position?: 'above' | 'below';
+    /** Zoom applied when a location is first placed (via search selection or map click) and no zoom is stored yet. Defaults to `15`. */
+    defaultZoom?: number;
+    /** Map height in pixels. Defaults to `240`. */
+    height?: number;
+}
+export interface AddressAutocompleteProps extends FormFieldProps {
+    /** Base field path; see {@link AddressAutocompleteFieldNames} for the default sub-field layout. */
+    name: string;
+    placeholder?: string;
+    disabled?: boolean;
+    feedback?: string;
+    /** Restrict suggestions to these ISO 3166-1 alpha-2 country codes, e.g. `['it']`. */
+    countries?: string[];
+    /** Overrides the provider-level language/region bias for this instance only. */
+    language?: string;
+    region?: string;
+    validator?: (value: FieldValue) => string | undefined | Promise<string | undefined>;
+    /** Called with the fully parsed address whenever it changes (search selection, pin drag/click)
+     *  — use this if the consumer needs fields beyond the ones auto-written. */
+    onSelect?: (address: ParsedAddress) => void;
+    /** Remaps the sub-field paths this component reads/writes. Omit to use `${name}.<field>`. */
+    fieldNames?: AddressAutocompleteFieldNames;
+    /**
+     * Shows an embeddable map with a draggable/clickable pin, so the user can fine-tune the exact
+     * location beyond what the address search resolves. Pass `true` for defaults or an options
+     * object. Requires the **Geocoding API** enabled in the same Google Cloud project, in addition
+     * to Places API (New) + Maps JavaScript API.
+     */
+    map?: boolean | AddressAutocompleteMapOptions;
+    id?: string;
+    labelClassName?: string;
+    menuClassName?: string;
+    itemClassName?: string;
+    mapClassName?: string;
+}
+/**
+ * Address search field backed by the Google Places Autocomplete (New) API. Selecting a
+ * suggestion fills the structured subfields below `name` — they stay independently editable
+ * afterward, same as every other CRM-override field in this app. Optionally pairs with an
+ * embeddable map (`map` prop) with a draggable/clickable pin for fine adjustment.
+ *
+ * Requires `<App googleMaps={{ apiKey }}>` (or `<GoogleMapsProvider config={...}>`) somewhere
+ * above in the tree; without it the field renders disabled with an explanatory message.
+ */
+export declare const AddressAutocomplete: ({ name, label, required, placeholder, disabled, feedback, countries, language, region, validator, onSelect, fieldNames, map, id, labelClassName, inheritWrapperClassName, wrapperClassName, className, menuClassName, itemClassName, mapClassName, }: AddressAutocompleteProps) => React.ReactElement;
+export default AddressAutocomplete;

package/dist/types/src/components/ui/fields/Upload.d.ts

@@ -67,7 +67,14 @@ export interface UploadImageProps extends UploadDocumentProps {
     feedback?: string;
     /** Pixel widths for responsive variants. Set with uploadPath to generate <name>_400w.jpg etc. and populate srcset/sizes in the Form record. */
     srcsetWidths?: number[];
+    /**
+     * Show a small link icon on the drop zone that opens a dialog for pasting an image URL
+     * instead of uploading a file. The confirmed URL is stored as a file entry (progress 100,
+     * no upload) — same shape and preview as a real upload, indistinguishable to the Form field.
+     * Default `false`.
+     */
+    allowUrl?: boolean;
 }
 export declare const getFileUrl: (file: FileProps, suffix?: string) => string;
 export declare const UploadDocument: ({ name, onChange, label, required, editable, multiple, max, accept, uploadPath, storageKey, storageProvider, before, after, wrapperClassName, className, }: UploadDocumentProps) => React.JSX.Element;
-export declare const UploadImage: ({ name, onChange, label, feedback, editable, multiple, accept, required, max, previewHeight, previewWidth, uploadPath, srcsetWidths, storageKey, storageProvider, before, after, wrapperClassName, className, }: UploadImageProps) => React.JSX.Element;
+export declare const UploadImage: ({ name, onChange, label, feedback, editable, multiple, accept, required, max, previewHeight, previewWidth, uploadPath, srcsetWidths, storageKey, storageProvider, allowUrl, before, after, wrapperClassName, className, }: UploadImageProps) => React.JSX.Element;

package/dist/types/src/index.d.ts

@@ -73,6 +73,9 @@ export { PhosphorIconProvider } from './providers/icon/PhosphorIconProvider';
 export type { PhosphorWeight } from './providers/icon/PhosphorIconProvider';
 export { IconProvider, useIconProvider, useIconController } from './providers/icon/IconProviderContext';
 export type { AppIconProviderConfig, IconController } from './providers/icon/IconProviderContext';
+export { GoogleMapsProvider, useGoogleMapsConfig } from './providers/googleMaps/GoogleMapsProviderContext';
+export { loadGoogleMaps } from './providers/googleMaps/loadGoogleMaps';
+export type { GoogleMapsConfig } from './providers/googleMaps/loadGoogleMaps';
 export { useEmailProvider, EmailProvider } from './providers/email/EmailProviderContext';
 export { GmailEmailProvider } from './providers/email/google/GmailEmailProvider';
 export type { AIRequestOptions, AIAttachment, AIProviderAdapter, AIKeyValidationResult, AIModelDescriptor, AIProviderCapabilities, AIModelCatalog, AIProviderDefinition, AICompleteRequest, AICompleteResult, AIConversationTurn, AIToolDefinition, AIToolCall, AIToolResult, } from './providers/ai';

package/dist/types/src/providers/googleMaps/GoogleMapsProviderContext.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { GoogleMapsConfig } from './loadGoogleMaps';
+export declare function GoogleMapsProvider({ config, children }: {
+    config?: GoogleMapsConfig;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** `undefined` when `<App>`/`<GoogleMapsProvider>` was not given a `googleMaps` config. */
+export declare function useGoogleMapsConfig(): GoogleMapsConfig | undefined;

package/dist/types/src/providers/googleMaps/loadGoogleMaps.d.ts

@@ -0,0 +1,20 @@
+export interface GoogleMapsConfig {
+    /** Google Cloud API key with the "Places API (New)" enabled. */
+    apiKey: string;
+    /** BCP-47 language for results, e.g. `'it'`. Defaults to the browser's language. */
+    language?: string;
+    /** Region bias (ccTLD), e.g. `'it'`. */
+    region?: string;
+}
+declare global {
+    interface Window {
+        [key: `__googleMapsLoader_${string}`]: (() => void) | undefined;
+    }
+}
+/**
+ * Loads the Google Maps JS API (places library) exactly once per page, regardless of how
+ * many `<AddressAutocomplete>` instances mount. Safe to call repeatedly with the same config;
+ * throws if called again with a *different* apiKey than the one already loading/loaded, since
+ * the script tag can't be swapped out once injected.
+ */
+export declare function loadGoogleMaps(config: GoogleMapsConfig): Promise<typeof google>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnative/react",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "LLM-native React framework for deterministic UI generation. Data-driven by default, schema-driven optional. Ultra-low token consumption — built for AI agents, not just humans.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -101,6 +101,7 @@
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
+    "@types/google.maps": "^3.65.4",
     "@types/papaparse": "^5.5.2",
     "@types/prismjs": "^1.26.6",
     "@types/react": "^19.2.17",

package/themes/cyber.ts

@@ -318,6 +318,12 @@ export const components: Theme = {
         wrapperClassName: '',
         className: '',
     },
+    AddressAutocomplete: {
+        wrapperClassName: '',
+        className: '',
+        menuClassName: 'rounded-none border-border/70 bg-popover/95 shadow-[0_0_0_1px_hsl(var(--border)/0.55),0_12px_32px_rgba(0,0,0,0.35)] supports-[backdrop-filter]:bg-popover/92',
+        itemClassName: '',
+    },
     Form: {
         wrapperClassName: '',
         buttonSaveClass: 'btn-outline-primary',

package/themes/default.ts

@@ -332,6 +332,12 @@ export const components: Theme = {
         wrapperClassName: '',
         className: '',
     },
+    AddressAutocomplete: {
+        wrapperClassName: '',
+        className: '',
+        menuClassName: 'border-border/60 bg-popover/95 shadow-xl shadow-black/5 backdrop-blur supports-[backdrop-filter]:bg-popover/90 dark:shadow-black/20',
+        itemClassName: '',
+    },
     Form: {
         wrapperClassName: '',
         buttonSaveClass: 'btn-outline-primary',

package/themes/flat.ts

@@ -318,6 +318,12 @@ export const components: Theme = {
         wrapperClassName: '',
         className: '',
     },
+    AddressAutocomplete: {
+        wrapperClassName: '',
+        className: '',
+        menuClassName: 'border-border/60 bg-popover/95 shadow-lg shadow-black/5 supports-[backdrop-filter]:bg-popover/92',
+        itemClassName: '',
+    },
     Form: {
         wrapperClassName: '',
         buttonSaveClass: 'btn-outline-primary',