docs(example): add item detail panel demonstrating useItem hook

Adds an ItemDetails component to the example app, showing how to use the
useItem hook to fetch and display STAC item details.
Improves documentation for consumers of stac-react.

Author: AliceR

example/src/pages/Main/ItemDetails.jsx

@@ -0,0 +1,57 @@
+import { useItem } from 'stac-react';
+
+import { H2 } from '../../components/headers';
+import Panel from '../../layout/Panel';
+import { Button } from '../../components/buttons';
+
+function ItemDetails({ item, onClose }) {
+  const itemUrl = item.links.find((r) => r.rel === 'self')?.href;
+  const { item: newItem, state, error, reload } = useItem(itemUrl);
+
+  const isLoading = state === 'LOADING';
+
+  return (
+    <Panel className="grid grid-rows-[1fr_min-content] p-4 h-[calc(100vh_-_90px)] overflow-y-scroll w-full overflow-hidden">
+      <div className="w-full overflow-hidden">
+        <div className="flex flex-wrap items-start gap-2">
+          <H2 className="whitespace-normal break-words flex-1">Selected Item</H2>
+          <Button
+            type="button"
+            onClick={onClose}
+            aria-label="Close selected item panel"
+            title="Close"
+            className="p-2 rounded hover:bg-gray-200 focus:outline-none focus:ring-2 focus:ring-gray-300"
+          >
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              className="w-5 h-5"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+            >
+              <path
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M6 18L18 6M6 6l12 12"
+              />
+            </svg>
+          </Button>
+        </div>
+        {isLoading && <p className="whitespace-normal break-words">Loading...</p>}
+        {error && <p className="whitespace-normal break-words">{error}</p>}
+        {newItem && (
+          <pre className="bg-gray-100 p-2 rounded  w-full whitespace-pre-wrap break-words overflow-x-auto text-xs">
+            {JSON.stringify(newItem, null, 2)}
+          </pre>
+        )}
+      </div>
+      <div className="grid grid-cols-2 gap-4">
+        <Button type="button" onClick={reload}>
+          Reload
+        </Button>
+      </div>
+    </Panel>
+  );
+}
+export default ItemDetails;

example/src/pages/Main/ItemList.jsx

@@ -19,17 +19,21 @@ PaginationButton.propTypes = {
   children: T.node.isRequired,
 };
 
-function ItemList({ items, isLoading, error, nextPage, previousPage }) {
+function ItemList({ items, isLoading, error, nextPage, previousPage, onSelect }) {
   return (
     <Panel className="grid grid-rows-[1fr_min-content] p-4">
       <div className="overflow-x-clip">
         <H2>Item List</H2>
         {isLoading && <p>Loading...</p>}
         {error && <p>{error}</p>}
         {items && (
-          <ul>
-            {items.features.map(({ id }) => (
-              <li key={id}>{id}</li>
+          <ul className="space-y-2">
+            {items.features.map((item) => (
+              <li key={item.id}>
+                <button onClick={onSelect(item)} className="text-pretty">
+                  {item.id}
+                </button>
+              </li>
             ))}
           </ul>
         )}
@@ -52,6 +56,7 @@ ItemList.propTypes = {
   error: T.string,
   previousPage: T.func,
   nextPage: T.func,
+  onSelect: T.func,
 };
 
 export default ItemList;

example/src/pages/Main/index.jsx

@@ -5,6 +5,7 @@ import { useStacSearch, useCollections, useStacApi, StacApiProvider } from 'stac
 import ItemList from './ItemList';
 import Map from './Map';
 import QueryBuilder from './QueryBuilder';
+import ItemDetails from './ItemDetails';
 
 // eslint-disable-next-line no-unused-vars
 const options = {
@@ -43,6 +44,18 @@ function Main() {
     [setBbox]
   );
 
+  const [selectedItem, setSelectedItem] = useState(null);
+
+  const onSelect = useCallback(
+    (item) => () => {
+      setSelectedItem(item);
+    },
+    []
+  );
+  const onClose = useCallback(() => {
+    setSelectedItem(null);
+  }, []);
+
   return (
     <div className="grid grid-cols-4 gap-4 m-4">
       <QueryBuilder
@@ -56,13 +69,18 @@ function Main() {
         dateRangeTo={dateRangeTo}
         setDateRangeTo={setDateRangeTo}
       />
-      <ItemList
-        items={results}
-        isLoading={state === 'LOADING'}
-        error={error && 'Error loading results'}
-        nextPage={nextPage}
-        previousPage={previousPage}
-      />
+      {selectedItem ? (
+        <ItemDetails item={selectedItem} onClose={onClose} />
+      ) : (
+        <ItemList
+          items={results}
+          isLoading={state === 'LOADING'}
+          error={error && 'Error loading results'}
+          nextPage={nextPage}
+          previousPage={previousPage}
+          onSelect={onSelect}
+        />
+      )}
       <Map
         className="col-span-2"
         isBboxDrawEnabled={isBboxDrawEnabled}