[TT-10187] Add AGENTS.md file to javascript/react components packages

packages/components/javascript/AGENTS.md

@@ -0,0 +1,182 @@
+# what3words — Autosuggest component (no map) Agent Guide (CDN‑only)
+
+Goal: Minimal POC where selecting a suggestion from the what3words autosuggest converts to `{lat,lng}` and displays it. No bundler edits, no extra packages.
+
+Rules:
+
+- Use CDN web‑component only. Do not install `@what3words/*` or edit Vite config.
+- Convert only after a selection (`"selected_suggestion"` event), never while typing.
+- Expose the API key as `VITE_W3W_API_KEY` (works with default Vite).
+
+## 1) Set the what3words API key
+
+- Key: `VITE_W3W_API_KEY`
+
+## 2) Add the component (no npm)
+
+Open `client/index.html` and paste these **two** lines just before `</head>`:
+
+```html
+<script
+  async
+  type="module"
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.esm.js"
+></script>
+<script
+  nomodule
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.js"
+></script>
+```
+
+This defines the `<what3words-autosuggest>` element at runtime — no Vite changes needed.
+
+## 3) Minimal `client/src/App.tsx`
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+
+// allow the custom element without extra .d.ts files
+declare global { namespace JSX { interface IntrinsicElements { "what3words-autosuggest": any } } }
+
+const API_KEY = import.meta.env.VITE_W3W_API_KEY as string | undefined;
+
+export default function App() {
+  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);
+  const ref = useRef<any>(null);
+
+  if (!API_KEY) return <p>Set <code>VITE_W3W_API_KEY</code> and rerun.</p>;
+
+  useEffect(() => {
+    const el = ref.current;
+    const onSelect = (e: any) => {
+      const w = e.detail?.suggestion?.words as string;
+      fetch(
+        \`https://api.what3words.com/v3/convert-to-coordinates?words=\${encodeURIComponent(w)}&key=\${API_KEY}\`
+      )
+        .then((r) => r.json())
+        .then((d) => setCoords(d.coordinates ?? null));
+    };
+    el?.addEventListener("selected_suggestion", onSelect);
+    return () => el?.removeEventListener("selected_suggestion", onSelect);
+  }, [API_KEY]);
+
+  return (
+    <>
+      <what3words-autosuggest api_key={API_KEY} ref={ref}>
+        <input placeholder="///filled.count.soap" />
+      </what3words-autosuggest>
+      <pre>{coords ? \`\${coords.lat}, \${coords.lng}\` : "Pick a suggestion"}</pre>
+    </>
+  );
+}
+```
+
+# what3words — Autosuggest component (with map) Agent Guide (CDN‑only)
+
+Goal: Minimal POC that shows a full‑viewport map and a what3words search. Picking a suggestion recentres the map to that 3‑word address. No bundler edits, no extra packages.
+
+Rules (for humans & agents):
+
+- Use CDN web‑components only. Do not install `@what3words/*` or edit Vite config.
+- Secrets: `VITE_W3W_API_KEY` (what3words) and `VITE_GOOGLE_MAP_API_KEY` (Google Maps).
+- Wire selection → map: listen for `"selected_suggestion"` and set the map’s `words` property. No manual API calls required.
+
+---
+
+## 1) Set the API keys
+
+- `VITE_W3W_API_KEY` → what3words key
+- `VITE_GOOGLE_MAP_API_KEY` → Google Maps JavaScript API key
+
+---
+
+## 2) Load the components (no npm)
+
+Open `client/index.html` and paste these two lines just before `</head>`:
+
+```html
+<script
+  async
+  type="module"
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.esm.js"
+></script>
+<script
+  nomodule
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.js"
+></script>
+```
+
+This defines `<what3words-map>` and `<what3words-autosuggest>` at runtime — no Vite changes needed.
+
+---
+
+## 3) Minimal `client/src/App.tsx`
+
+```tsx
+import { useEffect, useRef } from "react";
+
+// allow the custom elements without extra .d.ts files
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "what3words-map": any;
+      "what3words-autosuggest": any;
+    }
+  }
+}
+
+const W3W_KEY = import.meta.env.VITE_W3W_API_KEY as string | undefined;
+const GMAPS_KEY = import.meta.env.VITE_GOOGLE_MAP_API_KEY as string | undefined;
+
+export default function App() {
+  const mapRef = useRef<any>(null);
+  const autoRef = useRef<any>(null);
+
+  if (!W3W_KEY || !GMAPS_KEY) {
+    return (
+      <p>
+        Set <code>VITE_W3W_API_KEY</code> and{" "}
+        <code>VITE_GOOGLE_MAP_API_KEY</code> then rerun.
+      </p>
+    );
+  }
+
+  useEffect(() => {
+    const el = autoRef.current;
+    const onSelect = (e: any) => {
+      const words = e.detail?.suggestion?.words as string;
+      if (words && mapRef.current) mapRef.current.words = words; // recentre map
+    };
+    el?.addEventListener("selected_suggestion", onSelect);
+    return () => el?.removeEventListener("selected_suggestion", onSelect);
+  }, []);
+
+  return (
+    <what3words-map
+      ref={mapRef}
+      api_key={W3W_KEY}
+      map_api_key={GMAPS_KEY}
+      words="filled.count.soap"
+    >
+      {/* map canvas fills the visible viewport */}
+      <div slot="map" style={{ width: "100vw", height: "100dvh" }} />
+
+      {/* centred search bar overlay */}
+      <div
+        slot="search-control"
+        style={{
+          position: "absolute",
+          top: 16,
+          left: "50%",
+          transform: "translateX(-50%)",
+          zIndex: 1000,
+        }}
+      >
+        <what3words-autosuggest api_key={W3W_KEY} ref={autoRef}>
+          <input placeholder="Search what3words address" autoComplete="off" />
+        </what3words-autosuggest>
+      </div>
+    </what3words-map>
+  );
+}
+```

packages/components/javascript/package.json

@@ -57,7 +57,8 @@
   "files": [
     "dist/",
     "loader/",
-    "hydrate/"
+    "hydrate/",
+    "AGENTS.md"
   ],
   "config": {
     "root": "../../.."

packages/components/react/AGENTS.md

@@ -0,0 +1,182 @@
+# what3words — Autosuggest component (no map) Agent Guide (CDN‑only)
+
+Goal: Minimal POC where selecting a suggestion from the what3words autosuggest converts to `{lat,lng}` and displays it. No bundler edits, no extra packages.
+
+Rules:
+
+- Use CDN web‑component only. Do not install `@what3words/*` or edit Vite config.
+- Convert only after a selection (`"selected_suggestion"` event), never while typing.
+- Expose the API key as `VITE_W3W_API_KEY` (works with default Vite).
+
+## 1) Set the what3words API key
+
+- Key: `VITE_W3W_API_KEY`
+
+## 2) Add the component (no npm)
+
+Open `client/index.html` and paste these **two** lines just before `</head>`:
+
+```html
+<script
+  async
+  type="module"
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.esm.js"
+></script>
+<script
+  nomodule
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.js"
+></script>
+```
+
+This defines the `<what3words-autosuggest>` element at runtime — no Vite changes needed.
+
+## 3) Minimal `client/src/App.tsx`
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+
+// allow the custom element without extra .d.ts files
+declare global { namespace JSX { interface IntrinsicElements { "what3words-autosuggest": any } } }
+
+const API_KEY = import.meta.env.VITE_W3W_API_KEY as string | undefined;
+
+export default function App() {
+  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);
+  const ref = useRef<any>(null);
+
+  if (!API_KEY) return <p>Set <code>VITE_W3W_API_KEY</code> and rerun.</p>;
+
+  useEffect(() => {
+    const el = ref.current;
+    const onSelect = (e: any) => {
+      const w = e.detail?.suggestion?.words as string;
+      fetch(
+        \`https://api.what3words.com/v3/convert-to-coordinates?words=\${encodeURIComponent(w)}&key=\${API_KEY}\`
+      )
+        .then((r) => r.json())
+        .then((d) => setCoords(d.coordinates ?? null));
+    };
+    el?.addEventListener("selected_suggestion", onSelect);
+    return () => el?.removeEventListener("selected_suggestion", onSelect);
+  }, [API_KEY]);
+
+  return (
+    <>
+      <what3words-autosuggest api_key={API_KEY} ref={ref}>
+        <input placeholder="///filled.count.soap" />
+      </what3words-autosuggest>
+      <pre>{coords ? \`\${coords.lat}, \${coords.lng}\` : "Pick a suggestion"}</pre>
+    </>
+  );
+}
+```
+
+# what3words — Autosuggest component (with map) Agent Guide (CDN‑only)
+
+Goal: Minimal POC that shows a full‑viewport map and a what3words search. Picking a suggestion recentres the map to that 3‑word address. No bundler edits, no extra packages.
+
+Rules (for humans & agents):
+
+- Use CDN web‑components only. Do not install `@what3words/*` or edit Vite config.
+- Secrets: `VITE_W3W_API_KEY` (what3words) and `VITE_GOOGLE_MAP_API_KEY` (Google Maps).
+- Wire selection → map: listen for `"selected_suggestion"` and set the map’s `words` property. No manual API calls required.
+
+---
+
+## 1) Set the API keys
+
+- `VITE_W3W_API_KEY` → what3words key
+- `VITE_GOOGLE_MAP_API_KEY` → Google Maps JavaScript API key
+
+---
+
+## 2) Load the components (no npm)
+
+Open `client/index.html` and paste these two lines just before `</head>`:
+
+```html
+<script
+  async
+  type="module"
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.esm.js"
+></script>
+<script
+  nomodule
+  src="https://cdn.what3words.com/javascript-components@5.0.0/dist/what3words/what3words.js"
+></script>
+```
+
+This defines `<what3words-map>` and `<what3words-autosuggest>` at runtime — no Vite changes needed.
+
+---
+
+## 3) Minimal `client/src/App.tsx`
+
+```tsx
+import { useEffect, useRef } from "react";
+
+// allow the custom elements without extra .d.ts files
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "what3words-map": any;
+      "what3words-autosuggest": any;
+    }
+  }
+}
+
+const W3W_KEY = import.meta.env.VITE_W3W_API_KEY as string | undefined;
+const GMAPS_KEY = import.meta.env.VITE_GOOGLE_MAP_API_KEY as string | undefined;
+
+export default function App() {
+  const mapRef = useRef<any>(null);
+  const autoRef = useRef<any>(null);
+
+  if (!W3W_KEY || !GMAPS_KEY) {
+    return (
+      <p>
+        Set <code>VITE_W3W_API_KEY</code> and{" "}
+        <code>VITE_GOOGLE_MAP_API_KEY</code> then rerun.
+      </p>
+    );
+  }
+
+  useEffect(() => {
+    const el = autoRef.current;
+    const onSelect = (e: any) => {
+      const words = e.detail?.suggestion?.words as string;
+      if (words && mapRef.current) mapRef.current.words = words; // recentre map
+    };
+    el?.addEventListener("selected_suggestion", onSelect);
+    return () => el?.removeEventListener("selected_suggestion", onSelect);
+  }, []);
+
+  return (
+    <what3words-map
+      ref={mapRef}
+      api_key={W3W_KEY}
+      map_api_key={GMAPS_KEY}
+      words="filled.count.soap"
+    >
+      {/* map canvas fills the visible viewport */}
+      <div slot="map" style={{ width: "100vw", height: "100dvh" }} />
+
+      {/* centred search bar overlay */}
+      <div
+        slot="search-control"
+        style={{
+          position: "absolute",
+          top: 16,
+          left: "50%",
+          transform: "translateX(-50%)",
+          zIndex: 1000,
+        }}
+      >
+        <what3words-autosuggest api_key={W3W_KEY} ref={autoRef}>
+          <input placeholder="Search what3words address" autoComplete="off" />
+        </what3words-autosuggest>
+      </div>
+    </what3words-map>
+  );
+}
+```

packages/components/react/package.json

@@ -6,7 +6,8 @@
   "module": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
   "scripts": {
     "prepublishOnly": "npx --package-path=$PWD --strict=false publint-lint-package",