playhtml 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change Log
+
+The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
+
+## 1.2.0 - 2023-08-03
+
+- Added support for yjs's `awareness` protocol to handle synced data that shouldn't be persisted.

package/README.md

@@ -42,6 +42,12 @@ If you have dynamic elements that are hydrated after the initial load, you can c
 </script>
 ```
 
+To create your own custom element, refer to the [can-play](#can-play) section.
+
+## Examples
+
+Check out the [full gallery of community examples](https://gallery.playhtml.fun/) 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
 
 A full list can be found in `types.ts` under `TagType`.

package/dist/elements.d.ts

@@ -1,48 +1,65 @@
 /// <reference lib="dom" />
 import { TagType } from "./types";
 type ModifierKey = "ctrlKey" | "altKey" | "shiftKey" | "metaKey";
-export interface ElementInitializer<T = any, U = any> {
+export interface ElementInitializer<T = any, U = any, V = any> {
     defaultData: T | ((element: HTMLElement) => T);
     defaultLocalData?: U | ((element: HTMLElement) => U);
-    updateElement: (data: ElementEventHandlerData<T, U>) => void;
-    onDrag?: (e: MouseEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    onClick?: (e: MouseEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    onDragStart?: (e: MouseEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    additionalSetup?: (eventData: ElementSetupData<T, U>) => void;
+    myDefaultAwareness?: V | ((element: HTMLElement) => V);
+    updateElement: (data: ElementEventHandlerData<T, U, V>) => void;
+    updateElementAwareness?: (data: ElementAwarenessEventHandlerData<T, U, V>) => void;
+    onDrag?: (e: MouseEvent | TouchEvent, eventData: ElementEventHandlerData<T, U, V>) => void;
+    onClick?: (e: MouseEvent, eventData: ElementEventHandlerData<T, U, V>) => void;
+    onDragStart?: (e: MouseEvent | TouchEvent, eventData: ElementEventHandlerData<T, U, V>) => void;
+    additionalSetup?: (eventData: ElementSetupData<T, U, V>) => void;
     resetShortcut?: ModifierKey;
     debounceMs?: number;
 }
-export interface ElementData<T = any, U = any> extends ElementInitializer<T> {
+export interface ElementData<T = any, U = any, V = any> extends ElementInitializer<T> {
     data?: T;
     localData?: U;
+    awareness?: V;
     element: HTMLElement;
     onChange: (data: T) => void;
+    onAwarenessChange: (data: V) => void;
+    triggerAwarenessUpdate: () => void;
 }
-interface ElementEventHandlerData<T = any, U = any> {
+interface ElementEventHandlerData<T = any, U = any, V = any> {
     data: T;
     localData: U;
+    awareness: V[];
     element: HTMLElement;
     setData: (data: T) => void;
     setLocalData: (data: U) => void;
+    setLocalAwareness: (data: V) => void;
 }
-interface ElementSetupData<T = any, U = any> {
+interface ElementAwarenessEventHandlerData<T = any, U = any, V = any> extends ElementEventHandlerData<T, U, V> {
+    myAwareness?: V;
+}
+interface ElementSetupData<T = any, U = any, V = any> {
     getData: () => T;
     getLocalData: () => U;
+    getAwareness: () => V[];
     getElement: () => HTMLElement;
     setData: (data: T) => void;
     setLocalData: (data: U) => void;
+    setLocalAwareness: (data: V) => void;
 }
 export declare const TagTypeToElement: Record<Exclude<TagType, "can-play">, ElementInitializer>;
-export declare class ElementHandler<T = any, U = any> {
+export declare class ElementHandler<T = any, U = any, V = any> {
     defaultData: T;
     localData: U;
+    awareness: V[];
+    selfAwareness?: V;
     element: HTMLElement;
     _data: T;
     onChange: (data: T) => void;
+    onAwarenessChange: (data: V) => void;
     debouncedOnChange: (data: T) => void;
     resetShortcut?: ModifierKey;
-    updateElement: (data: ElementEventHandlerData<T, U>) => void;
-    constructor({ element, onChange, defaultData, defaultLocalData, data, updateElement, onClick, onDrag, onDragStart, additionalSetup, resetShortcut, debounceMs, }: ElementData<T>);
+    updateElement: (data: ElementEventHandlerData<T, U, V>) => void;
+    updateElementAwareness?: (data: ElementAwarenessEventHandlerData<T, U, V>) => void;
+    triggerAwarenessUpdate?: () => void;
+    constructor({ element, onChange, onAwarenessChange, defaultData, defaultLocalData, myDefaultAwareness, data, awareness: awarenessData, updateElement, updateElementAwareness, onClick, onDrag, onDragStart, additionalSetup, resetShortcut, debounceMs, triggerAwarenessUpdate, }: ElementData<T>);
     get data(): T;
     setLocalData(localData: U): void;
     /**
@@ -53,12 +70,15 @@ export declare class ElementHandler<T = any, U = any> {
      * (e.g. calling `updateElement` and `onChange`)
      */
     set __data(data: T);
-    getEventHandlerData(): ElementEventHandlerData<T, U>;
+    set __awareness(data: V[]);
+    getEventHandlerData(): ElementEventHandlerData<T, U, V>;
+    getAwarenessEventHandlerData(): ElementAwarenessEventHandlerData<T, U, V>;
     getSetupData(): ElementSetupData<T, U>;
     /**
      * Public-use setter for data that makes the change to all clients.
      */
     setData(data: T): void;
+    setLocalAwareness(data: V): void;
     setDataDebounced(data: T): void;
     /**
      * Resets the element to its default state.

package/dist/main.d.ts

@@ -3,7 +3,7 @@ import * as Y from "yjs";
 import { ElementHandler } from "./elements";
 export declare const globalData: Y.Map<Y.Map<any>>;
 export declare function getElementFromId(id: string): HTMLElement | null;
-export declare const elementHandlers: Map<string, Map<string, ElementHandler<any, any>>>;
+export declare const elementHandlers: Map<string, Map<string, ElementHandler<any, any, any>>>;
 /**
  * Sets up any playhtml elements that are currently on the page.
  * Can be repeatedly called to set up new elements without affecting existing ones.