# GoogleMapsLoader

The utility provider and hook responsible for the lazy-loading and initialization of the Google Maps JavaScript API. It is automatically managed by the `XerticaProvider`.

---

## Hook Usage

If you need to check the loading status or access the raw maps library in a custom component:

```tsx
import { useGoogleMapsLoader } from 'xertica-ui';

function MyCustomMap() {
  const { isLoaded, loadError } = useGoogleMapsLoader();

  if (loadError) return <div>Error loading maps</div>;
  if (!isLoaded) return <div>Loading maps...</div>;

  return <div>Maps API is ready!</div>;
}
```

---

## Integration

The loader is part of the `XerticaProvider` ecosystem. You do not need to wrap your components in it manually unless you are building a sub-application that doesn't use the full library provider.

```tsx
<XerticaProvider>
   {/* GoogleMapsLoader is already here */}
   <Map ... />
</XerticaProvider>
```

---

## AI Rules

> [!IMPORTANT]
>
> - **Conditional Rendering**: Always check `isLoaded` before attempting to render any component that requires `window.google`.
> - **Singleton**: Never instantiate multiple loaders. The `XerticaProvider` ensures only one instance manages the script injection.

---

## Why `VITE_GOOGLE_MAPS_API_KEY` is not read

The library ships pre-built. Vite resolves `import.meta.env.*` against **xertica-ui's own** build environment — where that variable never exists — and eliminates the branch from the published bundle, so it could never return the consuming app's key. Reading it only created the impression that env-var configuration worked.

Supply the key through one of the paths that resolve at runtime inside your own bundle:

```tsx
<XerticaProvider googleMapsApiKey={import.meta.env.VITE_GOOGLE_MAPS_API_KEY}>
```

or per component via `apiKey`, or from storage under `xertica-googlemaps-api-key`.