Add basemaps API

.changeset/cuddly-pumpkins-fetch.md

@@ -0,0 +1,5 @@
+---
+"@feltmaps/js-sdk": minor
+---
+
+Add basemaps API

docs/Basemaps/Basemap.md

@@ -0,0 +1,3 @@
+***
+
+> **Basemap**: [`FeltBasemap`](FeltBasemap.md) | [`ColorBasemap`](ColorBasemap.md) | [`CustomTileBasemap`](CustomTileBasemap.md)

docs/Basemaps/BasemapsController.md

@@ -0,0 +1,193 @@
+***
+
+The basemaps controller allows you to manage the map's basemap layer.
+
+You can get the current basemap, list available basemaps, change the basemap,
+and be notified when the basemap changes.
+
+# Extended by
+
+* [`FeltController`](../Main/FeltController.md)
+
+# Methods
+
+## getCurrentBasemap()
+
+> **getCurrentBasemap**(): `Promise`\<[`Basemap`](Basemap.md)>
+
+Gets the currently active basemap.
+
+Use this method to retrieve information about the current basemap, including
+its type (Felt, color, or custom tile), name, color scheme, and attribution.
+
+### Returns
+
+`Promise`\<[`Basemap`](Basemap.md)>
+
+A promise that resolves to the current basemap configuration.
+
+### Example
+
+```typescript
+// Get current basemap
+const basemap = await felt.getCurrentBasemap();
+console.log({
+  name: basemap.name,
+  type: basemap.type,
+  uiColorScheme: basemap.uiColorScheme,
+});
+```
+
+***
+
+## getBasemaps()
+
+> **getBasemaps**(): `Promise`\<[`Basemap`](Basemap.md)\[]>
+
+Gets all basemaps available on the map.
+
+Use this method to retrieve a list of all available basemaps that can be
+applied to the map.
+
+### Returns
+
+`Promise`\<[`Basemap`](Basemap.md)\[]>
+
+A promise that resolves to all basemaps available on the map.
+
+### Example
+
+```typescript
+// Get all available basemaps
+const basemaps = await felt.getBasemaps();
+const lightBasemaps = basemaps.filter(b => b.uiColorScheme === "light");
+```
+
+***
+
+## chooseBasemap()
+
+> **chooseBasemap**(`id`: `string`): `void`
+
+Chooses the basemap to use for the map.
+
+Use this method to change the current basemap. The basemap ID can be obtained
+from getBasemaps().
+
+### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+### Returns
+
+`void`
+
+A promise that resolves when the basemap has been set.
+
+### Example
+
+```typescript
+// Switch to a specific basemap
+const basemaps = await felt.getBasemaps();
+const darkBasemap = basemaps.find(b => b.uiColorScheme === "dark");
+if (darkBasemap) {
+  await felt.chooseBasemap(darkBasemap.id);
+}
+```
+
+***
+
+## addCustomBasemap()
+
+> **addCustomBasemap**(`args`: \{ `basemap`: [`ColorBasemapInput`](ColorBasemapInput.md) | [`CustomTileBasemapInput`](CustomTileBasemapInput.md); `select`: `boolean`; }): `Promise`\<[`Basemap`](Basemap.md)>
+
+Adds a custom basemap to the map. This can be either a solid color or a basemap
+from a custom tile URL.
+
+### Parameters
+
+| Parameter      | Type                                                                                                                                       | Description                                    |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
+| `args`         | \{ `basemap`: [`ColorBasemapInput`](ColorBasemapInput.md) \| [`CustomTileBasemapInput`](CustomTileBasemapInput.md); `select`: `boolean`; } | -                                              |
+| `args.basemap` | [`ColorBasemapInput`](ColorBasemapInput.md) \| [`CustomTileBasemapInput`](CustomTileBasemapInput.md)                                       | The basemap to add.                            |
+| `args.select`? | `boolean`                                                                                                                                  | Whether to select the basemap after adding it. |
+
+### Returns
+
+`Promise`\<[`Basemap`](Basemap.md)>
+
+A promise for the added basemap.
+
+### Example
+
+```typescript
+// Add a custom basemap and select it
+await felt.addCustomBasemap({
+  basemap: {
+    type: "xyz_tile",
+    tileUrl: "https://example.com/tile.png"
+  },
+  select: true,
+});
+```
+
+***
+
+## removeBasemap()
+
+> **removeBasemap**(`id`: `string`): `Promise`\<`void`>
+
+Removes a basemap from the list of available basemaps.
+
+### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+### Returns
+
+`Promise`\<`void`>
+
+A promise that resolves when the basemap has been removed.
+
+# Events
+
+## onBasemapChange()
+
+> **onBasemapChange**(`args`: \{ `handler`: (`basemap`: [`Basemap`](Basemap.md)) => `void`; }): `VoidFunction`
+
+Adds a listener for when the basemap changes.
+
+Use this to react to basemap changes, such as updating your UI or
+adjusting other map elements to match the new basemap's color scheme.
+
+### Parameters
+
+| Parameter      | Type                                                            |
+| -------------- | --------------------------------------------------------------- |
+| `args`         | \{ `handler`: (`basemap`: [`Basemap`](Basemap.md)) => `void`; } |
+| `args.handler` | (`basemap`: [`Basemap`](Basemap.md)) => `void`                  |
+
+### Returns
+
+`VoidFunction`
+
+A function to unsubscribe from the listener.
+
+### Example
+
+```typescript
+// Listen for basemap changes
+const unsubscribe = felt.onBasemapChange({
+  handler: basemap => {
+    console.log(`Switched to ${basemap.name}`);
+    updateUIColors(basemap.uiColorScheme);
+  },
+});
+
+// later on...
+unsubscribe();
+```

docs/Basemaps/ColorBasemap.md

@@ -0,0 +1,51 @@
+***
+
+# Properties
+
+## id
+
+> **id**: `string`
+
+A unique identifier for the basemap.
+
+### Remarks
+
+Do not rely on the stability of this ID for Felt basemaps, as they are
+subject to change.
+
+***
+
+## name
+
+> **name**: `string`
+
+The name of the basemap.
+
+***
+
+## uiColorScheme
+
+> **uiColorScheme**: `"light"` | `"dark"`
+
+The color scheme of the UI that goes with the basemap. It is best to set this to
+"light" if your basemap is broadly light, and "dark" if your basemap is broadly dark.
+
+***
+
+## type
+
+> **type**: `"color"`
+
+***
+
+## color
+
+> **color**: `string`
+
+***
+
+## attribution?
+
+> `optional` **attribution**: `string`
+
+The attribution of the basemap, which is shown in the map's UI.

docs/Basemaps/ColorBasemapInput.md

@@ -0,0 +1,3 @@
+***
+
+> **ColorBasemapInput**: `Omit`\<[`ColorBasemap`](ColorBasemap.md), `"id"`>

docs/Basemaps/CustomTileBasemap.md

@@ -0,0 +1,51 @@
+***
+
+# Properties
+
+## id
+
+> **id**: `string`
+
+A unique identifier for the basemap.
+
+### Remarks
+
+Do not rely on the stability of this ID for Felt basemaps, as they are
+subject to change.
+
+***
+
+## name
+
+> **name**: `string`
+
+The name of the basemap.
+
+***
+
+## uiColorScheme
+
+> **uiColorScheme**: `"light"` | `"dark"`
+
+The color scheme of the UI that goes with the basemap. It is best to set this to
+"light" if your basemap is broadly light, and "dark" if your basemap is broadly dark.
+
+***
+
+## type
+
+> **type**: `"xyz_tile"`
+
+***
+
+## tileUrl
+
+> **tileUrl**: `string`
+
+***
+
+## attribution?
+
+> `optional` **attribution**: `string`
+
+The attribution of the basemap, which is shown in the map's UI.

docs/Basemaps/CustomTileBasemapInput.md

@@ -0,0 +1,3 @@
+***
+
+> **CustomTileBasemapInput**: `Omit`\<[`CustomTileBasemap`](CustomTileBasemap.md), `"id"`>

docs/Basemaps/FeltBasemap.md

@@ -0,0 +1,51 @@
+***
+
+# Properties
+
+## id
+
+> **id**: `string`
+
+A unique identifier for the basemap.
+
+### Remarks
+
+Do not rely on the stability of this ID for Felt basemaps, as they are
+subject to change.
+
+***
+
+## name
+
+> **name**: `string`
+
+The name of the basemap.
+
+***
+
+## uiColorScheme
+
+> **uiColorScheme**: `"light"` | `"dark"`
+
+The color scheme of the UI that goes with the basemap. It is best to set this to
+"light" if your basemap is broadly light, and "dark" if your basemap is broadly dark.
+
+***
+
+## type
+
+> **type**: `"felt"`
+
+***
+
+## theme
+
+> **theme**: `"color_light"` | `"monochrome_dark"` | `"monochrome_light"` | `"satellite"`
+
+***
+
+## attribution?
+
+> `optional` **attribution**: `string`
+
+The attribution of the basemap, which is shown in the map's UI.

docs/Basemaps/README.md

@@ -0,0 +1,21 @@
+***
+
+The Basemaps module allows you to control the map's basemap layer, such as getting
+the current basemap, listing available basemaps, changing the basemap, and being
+notified when the basemap changes.
+
+# Controller
+
+* [BasemapsController](BasemapsController.md)
+
+# Interfaces
+
+* [FeltBasemap](FeltBasemap.md)
+* [ColorBasemap](ColorBasemap.md)
+* [CustomTileBasemap](CustomTileBasemap.md)
+
+# Type Aliases
+
+* [ColorBasemapInput](ColorBasemapInput.md)
+* [CustomTileBasemapInput](CustomTileBasemapInput.md)
+* [Basemap](Basemap.md)

docs/Elements/NoteElementCreate.md

@@ -151,7 +151,7 @@ The alignment of the text, either `left`, `center` or `right`.
 
 ## style?
 
-> `optional` **style**: `"italic"` | `"light"` | `"regular"` | `"caps"`
+> `optional` **style**: `"light"` | `"italic"` | `"regular"` | `"caps"`
 
 The style of the text, either `italic`, `light`, `regular` or `caps`.