@seamapi/react 1.63.1 → 1.65.0

package/README.md

@@ -87,13 +87,58 @@ export function App() {
   <seam-device-table publishable-key="your_publishable_key"></seam-device-table>
   <script
     type="module"
-    src="https://react.seam.co/v/1.63.1/dist/elements.js"
+    src="https://react.seam.co/v/1.65.0/dist/elements.js"
   ></script>
 </body>
 ```
 
 > Update the version in the script tag above with the exact version of this package you would like to use.
 
+#### Web component attributes and properties
+
+Each React component is defined as a custom element:
+
+- The element name is in in kebab-case,
+  e.g., `<DeviceTable>` becomes `<seam-device-table>`.
+- Each element is wrapped in a `<SeamProvider />`.
+- An attribute and custom property is defined for each `<SeamProvider />` prop and component prop.
+- Attributes are in kebab-case and properties are in snakeCase.
+
+Attributes map directly to component props.
+All attributes are passed as strings, thus non-string props have some limitations:
+
+- Number props will be parsed using `parseFloat`.
+- Boolean props should be passed as `true` or `false`, e.g., `disable-css-injection="true"` or `disable-css-injection="false"`.
+- Array props may be passed as JSON, e.g., `device-ids="["foo", "bar"]"`,
+  or CSV, e.g., `device-ids="foo,bar"`.
+- Function and object props should not be passed as attributes.
+  Set them as properties instead.
+
+Use custom properties to work directly with JavaScript objects and primitives.
+
+- This will avoid any issues with string parsing and serialization.
+- Use the `onSessionUpdate` prop to maintain a reference to the internal Seam client.
+
+For example,
+
+```js
+globalThis.customElements.whenDefined('seam-device-table').then(() => {
+  const elements = globalThis.document.getElementsByTagName('seam-device-table')
+  const element = elements[0]
+  if (element == null) {
+    throw new Error('Cannot find seam-device-table in document')
+  }
+  let seam
+  element.onSessionUpdate = (client) => {
+    seam = client
+  }
+  element.onDeviceClick = (deviceId) => {
+    if (seam == null) return
+    seam.devices.get({ device_id: deviceId }).then(console.log)
+  }
+})
+```
+
 [Seam Console]: https://console.seam.co/
 
 ### React Hooks
@@ -433,10 +478,22 @@ This is the same storybook published on [react.seam.co](https://react.seam.co).
 This project uses a [fake version of Seam Connect](https://github.com/seamapi/fake-seam-connect)
 to have deterministic responses for rendering views and running tests.
 
-Edit the seed data for the fake or find relevant ids for testing components here:
+The tests use the [default seed](https://github.com/seamapi/fake-seam-connect/blob/main/src/lib/database/seed.ts).
+
+Edit the Storybook seed data for the fake or find relevant ids for testing components here:
+[Storybook fake seed](./.storybook/seed-fake.js).
+
+### Fake Devicedb
 
-- [Storybook fake seed](./.storybook/seed-fake.js).
-- [Vitest fake seed](./test/fixtures/seed-fake.ts).
+Fake Seam Connect optionally depends on a [fake version of the Seam Devicedb](https://github.com/seamapi/fake-devicedb).
+This is required by some components and hooks in this project.
+
+The seed data for the fake is generated by pulling data from the real API.
+Update this seed data with
+
+```
+$ npm run storybook:update-devicedb-seed
+```
 
 ### Tests