playhtml 2.0.18 → 2.1.0

package/CHANGELOG.md

@@ -2,9 +2,10 @@
 
 The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
 
-## [Unreleased]
+## 2.1.0 - 2024-01-27
 
-- **BREAKING CHANGE**Changed the hash function used to generate element ids. This will cause all elements without an `id` to be re-created to lose any persistent historical data. This was done to avoid duplicates and to swap to using a standard-length hash function (SHA-1). We still recommend you setting a unique `id` for each element to avoid any potential duplicates in the future, and using `selectorId` will not be affected by this change.
+- **NEW FEATURE** Added eventing support for imperative logic like showing confetti whenever someone clicks a button which don't depend on a reacting to a data value changing. See the README under "eventing" for more details on how to set this up.
+- **BREAKING CHANGE** Changed the hash function used to generate element ids to be a stable length for long-term scalability. This will cause all elements without an `id` to be re-created to lose any persistent historical data. This was done to avoid duplicates and to swap to using a standard-length hash function (SHA-1). We still recommend you setting a unique `id` for each element to avoid any potential duplicates in the future, and using `selectorId` will not be affected by this change.
 
 ## 2.0.16 - 2024-01-04
 

package/README.md

@@ -2,17 +2,29 @@
 
 _interactive, collaborative html elements with a single data attribute_
 
-playhtml is a fast, small (~300KB), and expressive library for magically creating collaborative interactive HTML elements that persist their state across sessions. For example, you can create a movable piece of HTML "furniture" by adding the `can-move` attribute:
+playhtml is a fast, small (~300KB), library-agnostic, and expressive library for magically creating collaborative interactive HTML elements that persist their state across sessions.
+
+The simplest example is creating a shared, movable piece of HTML "furniture":
 
 ```html
 <div id="couch" can-move style="font-size: 80px">🛋</div>
 ```
 
-https://github.com/spencerc99/playhtml/assets/14796580/00e84e15-2c1c-4b4b-8e15-2af22f39db7a
+At a glance, playhtml supports:
 
-If you enjoy this, please consider [sponsoring the project or sending a small donation](https://github.com/sponsors/spencerc99). This helps ensure that the library is maintained and improved over time and funds the hosting costs for the syncing and persistence services.
+- reactive data scoped at a per-element level
+- sync and data persistence behavior customization (locally persisted, real-time synced, or globally persisted)
+- custom events for imperative logic
+- a range of magical plug-and-play and full customization
+- _(coming soon)_ a web component library for "plug-and-play" collaborative elements
+- _(coming soon)_ sharing state across domains
+- _(coming soon)_ permissioning for behaviors
+- _(coming soon)_ triggering behavior on a schedule (think cron)
+- _(coming soon)_ custom data sources for long-term persistence
 
-Join our [Discord community](https://discord.gg/h7sABTv8) to get help and show off what you've built!
+https://github.com/spencerc99/playhtml/assets/14796580/00e84e15-2c1c-4b4b-8e15-2af22f39db7a
+
+playhtml is still in beta and active development. Join our [Discord community](https://discord.gg/h7sABTv8) to get help and show off what you've built!
 
 ## Usage
 
@@ -23,7 +35,7 @@ Head to the proper section depending on your technology preference:
 
 ### vanilla html / simple browser usage
 
-To use this library, you can import the library and the associated styles from a CDN (in this case we will use [unpkg.com](https://unpkg.com)). Please make sure to do this after all the HTML elements on the page and ensure that the HTML elements you are "magic-ifying" have an `id` set.
+To use this library, you can import the library from a CDN (in this case we will use [unpkg.com](https://unpkg.com)). Please make sure to do this after all the HTML elements on the page and ensure that the HTML elements you are "magic-ifying" have an `id` set.
 
 ```html
 <body>
@@ -65,74 +77,52 @@ If you have dynamic elements that are hydrated after the initial load, you can c
 </script>
 ```
 
-### react / next.js / other frameworks
+#### eventing
 
-**react**
-`@playhtml/react` provides components out of the box corresponding to each of the capabilities. It manages all the state syncing for you, so you can reactively render your component based on whatever data is coming in.
+You can set up imperative logic that doesn't depend on a data value changing (like triggering confetti when someone clicks in an area) by registering events with playhtml. You can either pass in a list of events when you call `playhtml.init` or you can call `playhtml.registerPlayEventListener` to register an event at any time.
 
-Install by using your preferred package manager
+https://github.com/spencerc99/playhtml/assets/14796580/bd8ecfaf-73ab-4aa2-9312-8917809f52a2
 
-```bash
-npm install @playhtml/react # or
-# yarn add @playhtml/react
-```
-
-The callback handlers are slightly different to match the reactive patterns of React. For example, instead of `updateElement`, which is a vanilla javascript recreation of a reactive state management system, you can simply use your own state hooks or call `setData` to modify the shared state.
-
-You must import `playhtml` from the package and call `playhtml.init` somewhere before your components are rendered. This can be done anywhere in the code (unless you are using a framework with Server-Side Rendering, SSR, like with Next.JS, see below for how to handle this).
-
-```tsx
-// candle
-playhtml.init();
-export function Candle() {
-  return (
-    <CanPlayElement
-      defaultData={{ on: false }}
-      onClick={(_e, { data, setData }) => {
-        setData({ on: !data.on });
-      }}
-    >
-      {({ data }) => (
-        <img
-          src={data.on ? "/candle-gif.gif" : "/candle-off.png"}
-          selector-id=".candle"
-          className="candle"
-        />
-      )}
-    </CanPlayElement>
-  );
-}
+```html
+<div
+  style="width: 400px; height: 400px; border: 1px red solid"
+  id="confettiZone"
+>
+  <h1>CONFETTI ZONE</h1>
+</div>
+<!-- Import confetti library -->
+<script src="https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.2/dist/confetti.browser.min.js"></script>
+<script>
+  confettiZone.addEventListener("click", onClickConfettiZone);
+  function onClickConfettiZone(e) {
+    playhtml.dispatchPlayEvent({ type: "confetti" });
+  }
+</script>
+<script type="module">
+  import "https://unpkg.com/playhtml@latest";
+  playhtml.init({
+    events: {
+      confetti: {
+        type: "confetti",
+        onEvent: (data) => {
+          window.confetti({
+            particleCount: 100,
+            spread: 70,
+            origin: { y: 0.6 },
+          });
+        },
+      },
+    },
+  });
+</script>
 ```
 
-Refer to `packages/react/example.tsx` for a full list of examples.
-
-**next.js**
-Handling Next is more difficult due to the browser-first nature of `playhtml` and how you have to handle the same code running server-side with Next.
-
-To initialize `playhtml`, you'll need to dynamically import `playhtml` and call init in a `useEffect` in the top-level component.
-
-```tsx
-async function initPlayhtml() {
-  const playhtml = (await import("@playhtml/react")).playhtml;
-
-  playhtml.init();
-}
-// ... my component
-useEffect(() => {
-  void initPlayhtml();
-});
-```
+### react-based frameworks
 
-Then, in your components, you'll need to turn off `ssr` for dynamically importing the `playhtml` elements.
+**react**
+`@playhtml/react` provides components out of the box corresponding to each of the capabilities. It manages all the state syncing for you, so you can reactively render your component based on whatever data is coming in.
 
-```tsx
-import type { CanPlayElement as CanPlayElementType } from "@playhtml/react";
-import dynamic from "next/dynamic";
-const CanPlayElement = dynamic(
-  () => import("@playhtml/react").then((c) => c.CanPlayElement),
-  { ssr: false }
-) as typeof CanPlayElementType;
-```
+Refer to the [@playhtml/react README](https://github.com/spencerc99/playhtml/tree/main/packages/react) for the getting started guide.
 
 ---
 
@@ -142,11 +132,9 @@ If you're trying this out and having trouble, please message me ([email](mailto:
 
 ## Examples
 
-Check out the [full gallery of community examples](https://coda.io/@spencer/playhtml) for more inspiration on what you can do! And [submit your own](https://coda.io/form/playhtml-example_dnUR7xNE7wz) once you've made one.
-
-## Capabilities
+To get started, you can find examples under the `example` folder or React examples under `packages/react/examples`.
 
-A full list can be found in `types.ts` under `TagType`.
+For full-fledged examples, check out our [community gallery](https://coda.io/@spencer/playhtml) for more inspiration on what you can do! And [submit your own](https://coda.io/form/playhtml-example_dnUR7xNE7wz) once you've made one.
 
 ## Custom Capabilities
 
@@ -172,9 +160,9 @@ https://github.com/spencerc99/playhtml/assets/14796580/fae669b1-b3e2-404e-bd7a-3
   };
   candle.resetShortcut = "shiftKey";
 
-  // If you wanted to trigger this on hover, you could use `additionalSetup`
+  // If you wanted to trigger this on hover, you could use `onMount`
   // which can initialize several different event listeners and custom logic.
-  // customCandle.additionalSetup = ({ getData, setData }) => {
+  // customCandle.onMount = ({ getData, setData }) => {
   //   customCandle.addEventListener("mouseover", (_e) => {
   //     const data = getData();
   //     setData({on: !data.on}});
@@ -191,7 +179,7 @@ https://github.com/spencerc99/playhtml/assets/14796580/fae669b1-b3e2-404e-bd7a-3
 
 See all supported properties in the `ElementInitializer` [object in `types.ts`](https://github.com/spencerc99/playhtml/blob/main/src/types.ts#L13).
 
-The only required properties are `defaultData`, `updateElement` and some kind of setup to trigger those functions (in this case, `onClick`, but you can add custom event listeners and logic using the `additionalSetup` property). See more examples based on the definitions for the included capabilities in [`elements.ts`](https://github.com/spencerc99/playhtml/blob/main/src/elements.ts#L72).
+The only required properties are `defaultData`, `updateElement` and some kind of setup to trigger those functions (in this case, `onClick`, but you can add custom event listeners and logic using the `onMount` property). See more examples based on the definitions for the included capabilities in [`elements.ts`](https://github.com/spencerc99/playhtml/blob/main/src/elements.ts#L72).
 
 If you make something fun, please show me! This is designed as an open library for anyone to add on new interactions and capabilities, so we [welcome contributions](https://github.com/spencerc99/playhtml/blob/main/CONTRIBUTING.md) for new built-in capabilities.
 

package/dist/main.d.ts

@@ -3,13 +3,18 @@
 import { ElementAwarenessEventHandlerData } from '@playhtml/common';
 import { ElementData } from '@playhtml/common';
 import { ElementEventHandlerData } from '@playhtml/common';
-import { ElementInitializer } from '../../common/src/index';
+import { ElementInitializer } from '@playhtml/common';
 import { ElementSetupData } from '@playhtml/common';
+import { EventMessage } from '@playhtml/common';
 import { ModifierKey } from '@playhtml/common';
-import { TagType } from '../../common/src/index';
+import { PlayEvent } from '@playhtml/common';
+import { RegisteredPlayEvent } from '@playhtml/common';
+import { TagType } from '@playhtml/common';
 import * as Y from 'yjs';
 import YPartyKitProvider from 'y-partykit/provider';
 
+declare function dispatchPlayEvent(message: EventMessage): void;
+
 declare class ElementHandler<T = any, U = any, V = any> {
     defaultData: T;
     localData: U;
@@ -55,13 +60,34 @@ declare class ElementHandler<T = any, U = any, V = any> {
     reset(): void;
 }
 
-export declare interface InitOptions {
+export declare interface InitOptions<T = any> {
+    /**
+     * The room to connect users to (this should be a string that matches the other users
+     * that you want a given user to connect with).
+     *
+     * All rooms are automatically prefixed with their host (`window.location.hostname`) to prevent
+     * conflicting with other people's sites.
+     * Defaults to `window.location.pathname + window.location.search. You can customize this by
+     * passing in your own room dynamically
+     */
     room?: string;
+    /**
+     * Provide your own partykit host if you'd like to run your own server and customize the logic.
+     */
     host?: string;
+    /**
+     * Optionally provide your own map of capabilities
+     */
     extraCapabilities?: Record<string, ElementInitializer>;
+    /**
+     * A mapping of event types to PlayEvents. Allows specifying of imperative logic to trigger when a
+     * client triggers some event. Automatically listens to native DOM events to trigger these.
+     *
+     */
+    events?: Record<string, PlayEvent<T>>;
 }
 
-declare function initPlayHTML({ room: inputRoom, host, extraCapabilities, }?: InitOptions): YPartyKitProvider | undefined;
+declare function initPlayHTML({ room: inputRoom, host, extraCapabilities, events, }?: InitOptions): YPartyKitProvider | undefined;
 
 export declare const playhtml: PlayHTMLComponents;
 
@@ -73,10 +99,25 @@ declare interface PlayHTMLComponents {
     setupPlayElementForTag: typeof setupPlayElementForTag;
     globalData: Y.Map<any> | undefined;
     elementHandlers: Map<string, Map<string, ElementHandler>> | undefined;
+    eventHandlers: Map<string, Array<RegisteredPlayEvent>> | undefined;
+    dispatchPlayEvent: typeof dispatchPlayEvent;
+    registerPlayEventListener: typeof registerPlayEventListener;
+    removePlayEventListener: typeof removePlayEventListener;
 }
 
+/**
+ * Registers the given event listener.
+ * Returns a unique ID corresponding to the listener.
+ */
+declare function registerPlayEventListener(type: string, event: Omit<PlayEvent, "type">): string;
+
 declare function removePlayElement(element: Element | null): void;
 
+/**
+ * Removes the event listener with the given type and id.
+ */
+declare function removePlayEventListener(type: string, id: string): void;
+
 /**
  * Sets up any playhtml elements that are currently on the page.
  *