@mosaicajs/react 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/components.d.ts

@@ -1,40 +1,55 @@
 /**
- * Every `mosaica-*` element as a React component with typed props and event handlers, made with
- * `@lit/react`. `MosaicaMap` wraps `<mosaica-map>`, and so on. A prop that names an element
- * property is set as that property, so an object such as `store` reaches the element under React
- * 18, which sets a custom element's props as attributes. Each element's events are handler props, such as `onPick` for
- * `mosaica-pick`. The element classes are exported as types with an `Element` suffix, such as
- * `MapElement`, for typing a ref. Each element's attributes, properties, events, slots and parts
- * are on its page in the Components reference, which each wrapper's type links to.
+ * `@mosaicajs/react/components` is every element of `@mosaicajs/components` as a React component,
+ * such as `MosaicaMap` for `<mosaica-map>`. Each component takes the element's properties as props,
+ * including objects such as `store` that React 18 would otherwise set as attributes. Each event
+ * the element fires is a handler prop, such as `onPick` for `mosaica-pick`. The element's
+ * attributes, properties, events, slots and parts are on its page in the Components reference,
+ * which each component's type below links to.
  *
- * `MosaicaStore`, `MosaicaMap` and `MosaicaExplorer` read their `authorise` prop through a ref, so
- * an inline function does not build a new store on every render. To show the map to another
- * viewer, change `token` or `viewerUrl`, or give the component a new `key`.
+ * A component draws from the store you pass as `store`, such as one from `useMosaicaStore` in
+ * `@mosaicajs/react`, or else from an enclosing `MosaicaStore` or `MosaicaExplorer`. Those two and
+ * `MosaicaMap` can also make their own store from `viewerUrl` and `token` or `authorise`. You can
+ * pass an inline `authorise` function: the component calls the latest one and does not create a
+ * new store when it changes.
+ * To show the map to another viewer, change `token` or `viewerUrl`, or give the component a new
+ * `key`.
  *
- * This entry imports `@mosaicajs/components`, and with it Lit and deck.gl. The hooks are in the
- * package root, `@mosaicajs/react`, which imports neither.
+ * The element classes are exported as types with an `Element` suffix, such as `MapElement`, for
+ * typing a ref. This entry imports `@mosaicajs/components`, and with it Lit and deck.gl.
+ *
+ * @example
+ * ```tsx
+ * import {useMosaicaStore} from '@mosaicajs/react';
+ * import {MosaicaMap, MosaicaItemCard} from '@mosaicajs/react/components';
+ *
+ * function Map({token}: {token: string}) {
+ *   const store = useMosaicaStore({viewerUrl: 'http://localhost:8080', token});
+ *   return (
+ *     <>
+ *       <MosaicaMap store={store} onPick={(e) => console.log(e.detail.id)} />
+ *       <MosaicaItemCard store={store} />
+ *     </>
+ *   );
+ * }
+ * ```
  *
  * @module @mosaicajs/react/components
  */
 import { type EventName } from '@lit/react';
 import { MosaicaArtifactCard as ArtifactCardElement, MosaicaClusterFilter as ClusterFilterElement, MosaicaColourEditor as ColourEditorElement, MosaicaCount as CountElement, MosaicaExplorer as ExplorerElement, MosaicaFieldCard as FieldCardElement, MosaicaFilter as FilterElement, MosaicaFilterPanel as FilterPanelElement, MosaicaHierarchy as HierarchyElement, MosaicaItemCard as ItemCardElement, MosaicaKeyPicker as KeyPickerElement, MosaicaLayerPicker as LayerPickerElement, MosaicaMap as MapElement, MosaicaSelection as SelectionElement, MosaicaStatus as StatusElement, MosaicaStore as StoreElement, MosaicaViewPicker as ViewPickerElement, type MosaicaEventMap } from '@mosaicajs/components';
 /**
- * The events the elements emit, by name, each a `CustomEvent` with its detail: `MosaicaEventMap`
- * from `@mosaicajs/components`.
+ * The events the elements fire, by name, each a `CustomEvent` with its `detail`. The same type as
+ * `MosaicaEventMap` in `@mosaicajs/components`.
  */
 export type MosaicaEvents = MosaicaEventMap;
 /** `<mosaica-store>` as a React component. It has no event props. */
 export declare const MosaicaStore: import("@lit/react").ReactWebComponent<StoreElement, {}>;
 /**
- * `<mosaica-explorer>` as a React component. It has a handler prop for every event, since the
- * elements inside it emit them and each event bubbles out of it: `onPick`, `onItemOpen`, `onMiss`, `onHover`,
- * `onViewChange`, `onSelectChange`, `onArtifactOpen`, `onLayerChange`, `onArtifactFit`,
- * `onColourChange`, `onLevelChange`, `onValueColour`, `onClusterColour`, `onPaletteChange`, `onClusterPaletteChange`,
- * `onDisplayChange`, `onSizeChange`, `onBudgetChange`, `onClusterBudgetChange`, `onFold`,
- * `onFilterChange`, `onStateChange`, `onExpired`, `onOpen`, `onClose`, `onClauseChange`,
- * `onViewSwitch` and `onViewFollow`, each for the `mosaica-` event of the same name in lower case.
- * The `open` prop is the function the item card's Open calls, and `openUrl` the address it goes
- * to; `onOpen` hears every press.
+ * `<mosaica-explorer>` as a React component. The events of the elements inside it bubble out, so
+ * it has a handler prop for each of them: `onPick` for `mosaica-pick`, and so on for every event
+ * in {@link MosaicaEvents} except `mosaica-chipopen`, which it does not fire. The `open` prop
+ * is the function the item card's Open button calls, and `openUrl` the address it goes to.
+ * `onOpen` is called on every press.
  */
 export declare const MosaicaExplorer: import("@lit/react").ReactWebComponent<ExplorerElement, {
     onArtifactFit: EventName<CustomEvent<{
@@ -168,13 +183,17 @@ export declare const MosaicaExplorer: import("@lit/react").ReactWebComponent<Exp
     onLayerChange: EventName<CustomEvent<{
         layers: string[];
     }>>;
+    onBasemapChange: EventName<CustomEvent<{
+        refusal: string | null;
+        note: string | null;
+    }>>;
 }>;
 /**
  * `<mosaica-map>` as a React component. Event props: `onPick` (`mosaica-pick`), `onItemOpen`
- * (`mosaica-itemopen`), `onMiss`
- * (`mosaica-miss`), `onHover` (`mosaica-hover`), `onViewChange` (`mosaica-viewchange`), `onSelectChange`
- * (`mosaica-selectchange`), `onArtifactOpen` (`mosaica-artifactopen`) and `onLayerChange`
- * (`mosaica-layerchange`).
+ * (`mosaica-itemopen`), `onMiss` (`mosaica-miss`), `onHover` (`mosaica-hover`), `onViewChange`
+ * (`mosaica-viewchange`), `onSelectChange` (`mosaica-selectchange`), `onArtifactOpen`
+ * (`mosaica-artifactopen`), `onLayerChange` (`mosaica-layerchange`) and `onBasemapChange`
+ * (`mosaica-basemapchange`).
  */
 export declare const MosaicaMap: import("@lit/react").ReactWebComponent<MapElement, {
     onPick: EventName<CustomEvent<{
@@ -213,8 +232,15 @@ export declare const MosaicaMap: import("@lit/react").ReactWebComponent<MapEleme
     onLayerChange: EventName<CustomEvent<{
         layers: string[];
     }>>;
+    onBasemapChange: EventName<CustomEvent<{
+        refusal: string | null;
+        note: string | null;
+    }>>;
 }>;
-/** `<mosaica-status>` as a React component. Event props: `onStateChange` (`mosaica-statechange`) and `onExpired` (`mosaica-expired`). */
+/**
+ * `<mosaica-status>` as a React component. Event props: `onStateChange` (`mosaica-statechange`)
+ * and `onExpired` (`mosaica-expired`).
+ */
 export declare const MosaicaStatus: import("@lit/react").ReactWebComponent<StatusElement, {
     onStateChange: EventName<CustomEvent<{
         from: import("@mosaicajs/components").PanelState | null;
@@ -229,8 +255,8 @@ export declare const MosaicaStatus: import("@lit/react").ReactWebComponent<Statu
 export declare const MosaicaCount: import("@lit/react").ReactWebComponent<CountElement, {}>;
 /**
  * `<mosaica-item-card>` as a React component. Event props: `onOpen` (`mosaica-open`), `onClose`
- * (`mosaica-close`) and `onViewFollow` (`mosaica-viewfollow`). The `open` prop is the function
- * Open calls, and `openUrl` the address it goes to; `onOpen` hears every press.
+ * (`mosaica-close`) and `onViewFollow` (`mosaica-viewfollow`). The `open` prop is the function the
+ * Open button calls, and `openUrl` the address it goes to. `onOpen` is called on every press.
  */
 export declare const MosaicaItemCard: import("@lit/react").ReactWebComponent<ItemCardElement, {
     onOpen: EventName<CustomEvent<{

package/dist/components.js

@@ -1,18 +1,37 @@
 /**
- * Every `mosaica-*` element as a React component with typed props and event handlers, made with
- * `@lit/react`. `MosaicaMap` wraps `<mosaica-map>`, and so on. A prop that names an element
- * property is set as that property, so an object such as `store` reaches the element under React
- * 18, which sets a custom element's props as attributes. Each element's events are handler props, such as `onPick` for
- * `mosaica-pick`. The element classes are exported as types with an `Element` suffix, such as
- * `MapElement`, for typing a ref. Each element's attributes, properties, events, slots and parts
- * are on its page in the Components reference, which each wrapper's type links to.
+ * `@mosaicajs/react/components` is every element of `@mosaicajs/components` as a React component,
+ * such as `MosaicaMap` for `<mosaica-map>`. Each component takes the element's properties as props,
+ * including objects such as `store` that React 18 would otherwise set as attributes. Each event
+ * the element fires is a handler prop, such as `onPick` for `mosaica-pick`. The element's
+ * attributes, properties, events, slots and parts are on its page in the Components reference,
+ * which each component's type below links to.
  *
- * `MosaicaStore`, `MosaicaMap` and `MosaicaExplorer` read their `authorise` prop through a ref, so
- * an inline function does not build a new store on every render. To show the map to another
- * viewer, change `token` or `viewerUrl`, or give the component a new `key`.
+ * A component draws from the store you pass as `store`, such as one from `useMosaicaStore` in
+ * `@mosaicajs/react`, or else from an enclosing `MosaicaStore` or `MosaicaExplorer`. Those two and
+ * `MosaicaMap` can also make their own store from `viewerUrl` and `token` or `authorise`. You can
+ * pass an inline `authorise` function: the component calls the latest one and does not create a
+ * new store when it changes.
+ * To show the map to another viewer, change `token` or `viewerUrl`, or give the component a new
+ * `key`.
  *
- * This entry imports `@mosaicajs/components`, and with it Lit and deck.gl. The hooks are in the
- * package root, `@mosaicajs/react`, which imports neither.
+ * The element classes are exported as types with an `Element` suffix, such as `MapElement`, for
+ * typing a ref. This entry imports `@mosaicajs/components`, and with it Lit and deck.gl.
+ *
+ * @example
+ * ```tsx
+ * import {useMosaicaStore} from '@mosaicajs/react';
+ * import {MosaicaMap, MosaicaItemCard} from '@mosaicajs/react/components';
+ *
+ * function Map({token}: {token: string}) {
+ *   const store = useMosaicaStore({viewerUrl: 'http://localhost:8080', token});
+ *   return (
+ *     <>
+ *       <MosaicaMap store={store} onPick={(e) => console.log(e.detail.id)} />
+ *       <MosaicaItemCard store={store} />
+ *     </>
+ *   );
+ * }
+ * ```
  *
  * @module @mosaicajs/react/components
  */
@@ -50,20 +69,17 @@ const mapEvents = {
     onViewChange: ev('mosaica-viewchange'),
     onSelectChange: ev('mosaica-selectchange'),
     onArtifactOpen: ev('mosaica-artifactopen'),
-    onLayerChange: ev('mosaica-layerchange')
+    onLayerChange: ev('mosaica-layerchange'),
+    onBasemapChange: ev('mosaica-basemapchange')
 };
 /** `<mosaica-store>` as a React component. It has no event props. */
 export const MosaicaStore = withStableAuthorise(wrap('mosaica-store', StoreElement, {}));
 /**
- * `<mosaica-explorer>` as a React component. It has a handler prop for every event, since the
- * elements inside it emit them and each event bubbles out of it: `onPick`, `onItemOpen`, `onMiss`, `onHover`,
- * `onViewChange`, `onSelectChange`, `onArtifactOpen`, `onLayerChange`, `onArtifactFit`,
- * `onColourChange`, `onLevelChange`, `onValueColour`, `onClusterColour`, `onPaletteChange`, `onClusterPaletteChange`,
- * `onDisplayChange`, `onSizeChange`, `onBudgetChange`, `onClusterBudgetChange`, `onFold`,
- * `onFilterChange`, `onStateChange`, `onExpired`, `onOpen`, `onClose`, `onClauseChange`,
- * `onViewSwitch` and `onViewFollow`, each for the `mosaica-` event of the same name in lower case.
- * The `open` prop is the function the item card's Open calls, and `openUrl` the address it goes
- * to; `onOpen` hears every press.
+ * `<mosaica-explorer>` as a React component. The events of the elements inside it bubble out, so
+ * it has a handler prop for each of them: `onPick` for `mosaica-pick`, and so on for every event
+ * in {@link MosaicaEvents} except `mosaica-chipopen`, which it does not fire. The `open` prop
+ * is the function the item card's Open button calls, and `openUrl` the address it goes to.
+ * `onOpen` is called on every press.
  */
 export const MosaicaExplorer = withStableAuthorise(wrap('mosaica-explorer', ExplorerElement, {
     ...mapEvents,
@@ -90,20 +106,23 @@ export const MosaicaExplorer = withStableAuthorise(wrap('mosaica-explorer', Expl
 }));
 /**
  * `<mosaica-map>` as a React component. Event props: `onPick` (`mosaica-pick`), `onItemOpen`
- * (`mosaica-itemopen`), `onMiss`
- * (`mosaica-miss`), `onHover` (`mosaica-hover`), `onViewChange` (`mosaica-viewchange`), `onSelectChange`
- * (`mosaica-selectchange`), `onArtifactOpen` (`mosaica-artifactopen`) and `onLayerChange`
- * (`mosaica-layerchange`).
+ * (`mosaica-itemopen`), `onMiss` (`mosaica-miss`), `onHover` (`mosaica-hover`), `onViewChange`
+ * (`mosaica-viewchange`), `onSelectChange` (`mosaica-selectchange`), `onArtifactOpen`
+ * (`mosaica-artifactopen`), `onLayerChange` (`mosaica-layerchange`) and `onBasemapChange`
+ * (`mosaica-basemapchange`).
  */
 export const MosaicaMap = withStableAuthorise(wrap('mosaica-map', MapElement, mapEvents));
-/** `<mosaica-status>` as a React component. Event props: `onStateChange` (`mosaica-statechange`) and `onExpired` (`mosaica-expired`). */
+/**
+ * `<mosaica-status>` as a React component. Event props: `onStateChange` (`mosaica-statechange`)
+ * and `onExpired` (`mosaica-expired`).
+ */
 export const MosaicaStatus = wrap('mosaica-status', StatusElement, { onStateChange: ev('mosaica-statechange'), onExpired: ev('mosaica-expired') });
 /** `<mosaica-count>` as a React component. It has no event props. */
 export const MosaicaCount = wrap('mosaica-count', CountElement, {});
 /**
  * `<mosaica-item-card>` as a React component. Event props: `onOpen` (`mosaica-open`), `onClose`
- * (`mosaica-close`) and `onViewFollow` (`mosaica-viewfollow`). The `open` prop is the function
- * Open calls, and `openUrl` the address it goes to; `onOpen` hears every press.
+ * (`mosaica-close`) and `onViewFollow` (`mosaica-viewfollow`). The `open` prop is the function the
+ * Open button calls, and `openUrl` the address it goes to. `onOpen` is called on every press.
  */
 export const MosaicaItemCard = wrap('mosaica-item-card', ItemCardElement, { onOpen: ev('mosaica-open'), onClose: ev('mosaica-close'), onViewFollow: ev('mosaica-viewfollow') });
 /**

package/dist/index.d.ts

@@ -1,32 +1,32 @@
 import { type ProjectionName, type Projections, type Store, type StoreOptions, type TokenSupplier } from '@mosaicajs/client';
-/** The options of {@link useMosaicaStore}: the options of {@link createStore}, with `authorise` read through a ref. */
+/** The options of {@link useMosaicaStore}, which are those of {@link createStore}. */
 export type UseMosaicaStoreOptions = Omit<StoreOptions, 'authorise'> & {
     /**
-     * A function the store calls for a new token before the current one expires. The hook reads it
-     * through a ref, so an inline function neither rebuilds the store nor goes stale. A store serves
-     * one viewer: to show another, call `clear()` on the store or give the component a new `key`.
+     * A function that returns a viewer token, which the store calls at the start and before each
+     * token expires. You can pass an inline function: the hook calls the latest one and does not
+     * create a new store when it changes. A store serves one viewer. To show the map to another, call the
+     * store's `clear()` or give the component a new `key`.
      */
     authorise?: TokenSupplier;
 };
 /**
- * Creates a store with {@link createStore} for the component's lifetime, and disposes of it on
- * unmount. The store is rebuilt when `viewerUrl`, `client`, `token` or `view` changes, or when
- * `authorise` is given or removed. A change to any other option takes effect at the next rebuild.
- * With a `client`, `viewerUrl` may be left out, as `createStore` allows. Keep the `client` the
- * same object across renders, such as with `useMemo`: a new client each render rebuilds the store
- * each render.
+ * Creates a store with {@link createStore} for the lifetime of the component, and disposes of it on
+ * unmount. The store is created in an effect, so the first render returns `null`.
  *
- * The store is built in an effect, so the first render returns `null`. Options `createStore`
- * refuses, such as neither `viewerUrl` nor `client`, throw from that effect.
+ * The store is created again when `viewerUrl`, `client`, `token` or `view` changes, or when
+ * `authorise` is added or removed. Other options take effect the next time it is created. If you
+ * pass a `client`, keep it the same object across renders, for example with `useMemo`, or every
+ * render creates a new store. Options that `createStore` refuses, such as neither `viewerUrl` nor
+ * `client`, throw from the effect.
  */
 export declare function useMosaicaStore(options: UseMosaicaStoreOptions): Store | null;
 /**
- * Reads one projection of `store` through `useSyncExternalStore`, and re-renders the component
- * when that projection is replaced. A change to another projection does not re-render it.
+ * Returns one of the store's projections, and re-renders the component whenever that projection
+ * changes. Changes to other projections do not re-render it.
  *
  * @param store - The store, such as the one {@link useMosaicaStore} returns.
  * @param name - The projection to read, such as `marks` or `legend`.
- * @returns The projection, or `null` while `store` is `null`.
+ * @returns The projection, or `null` while `store` is `null`, as it is on the first render.
  */
 export declare function useProjection<K extends ProjectionName>(store: Store, name: K): Projections[K];
 export declare function useProjection<K extends ProjectionName>(store: Store | null, name: K): Projections[K] | null;

package/dist/index.js

@@ -1,23 +1,43 @@
 /**
- * React hooks for the headless store. {@link useMosaicaStore} creates a store for a component's
- * lifetime, and {@link useProjection} reads one of its projections and re-renders when it changes.
- * The React components for the elements are in the `@mosaicajs/react/components` entry. This
- * entry imports neither Lit nor deck.gl.
+ * `@mosaicajs/react` connects the store from `@mosaicajs/client` to React. {@link useMosaicaStore}
+ * creates a store that lives as long as your component. {@link useProjection} reads one of the
+ * store's projections, the read-only snapshots it publishes of the map's state, and re-renders
+ * your component when that projection changes.
+ *
+ * The elements of `@mosaicajs/components`, such as the map, are React components in the
+ * `@mosaicajs/react/components` entry, and you can pass them a store as the `store` prop. This
+ * entry imports neither Lit nor deck.gl, so a page that uses only the hooks does not load them.
+ *
+ * @example
+ * ```tsx
+ * import {useMosaicaStore, useProjection} from '@mosaicajs/react';
+ * import {MosaicaMap} from '@mosaicajs/react/components';
+ *
+ * function Map({token}: {token: string}) {
+ *   const store = useMosaicaStore({viewerUrl: 'http://localhost:8080', token});
+ *   const status = useProjection(store, 'status');
+ *   return (
+ *     <>
+ *       <MosaicaMap store={store} />
+ *       <p>{status?.status}</p>
+ *     </>
+ *   );
+ * }
+ * ```
  *
  * @module @mosaicajs/react
  */
 import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
 import { createStore } from '@mosaicajs/client';
 /**
- * Creates a store with {@link createStore} for the component's lifetime, and disposes of it on
- * unmount. The store is rebuilt when `viewerUrl`, `client`, `token` or `view` changes, or when
- * `authorise` is given or removed. A change to any other option takes effect at the next rebuild.
- * With a `client`, `viewerUrl` may be left out, as `createStore` allows. Keep the `client` the
- * same object across renders, such as with `useMemo`: a new client each render rebuilds the store
- * each render.
+ * Creates a store with {@link createStore} for the lifetime of the component, and disposes of it on
+ * unmount. The store is created in an effect, so the first render returns `null`.
  *
- * The store is built in an effect, so the first render returns `null`. Options `createStore`
- * refuses, such as neither `viewerUrl` nor `client`, throw from that effect.
+ * The store is created again when `viewerUrl`, `client`, `token` or `view` changes, or when
+ * `authorise` is added or removed. Other options take effect the next time it is created. If you
+ * pass a `client`, keep it the same object across renders, for example with `useMemo`, or every
+ * render creates a new store. Options that `createStore` refuses, such as neither `viewerUrl` nor
+ * `client`, throw from the effect.
  */
 export function useMosaicaStore(options) {
     const [store, setStore] = useState(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicajs/react",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.5",
   "description": "React hooks over the headless store, and typed wrappers for the mosaica-* elements behind a separate entry.",
   "keywords": [
     "mosaica",
@@ -19,7 +19,7 @@
     "directory": "clients/ts/react"
   },
   "license": "Apache-2.0",
-  "author": "Joe Ennis",
+  "author": "mosaicadb",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -45,11 +45,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@mosaicajs/client": "^0.1.0-rc.4"
+    "@mosaicajs/client": "^0.1.0-rc.5"
   },
   "peerDependencies": {
     "@lit/react": "^1.0.0",
-    "@mosaicajs/components": "^0.1.0-rc.4",
+    "@mosaicajs/components": "^0.1.0-rc.5",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -62,14 +62,14 @@
   },
   "devDependencies": {
     "@lit/react": "^1.0.8",
-    "@mosaicajs/components": "^0.1.0-rc.4",
+    "@mosaicajs/components": "^0.1.0-rc.5",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
-    "happy-dom": "^20.0.0",
+    "happy-dom": "^21.0.4",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "typescript": "^5.9.0",
-    "vitest": "^3.2.0"
+    "vitest": "^4.1.12"
   },
   "publishConfig": {
     "access": "public"