playhtml 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
+
+## 1.3.0 - 2023-08-07
+
+- Added support for `can-duplicate` capability to duplicate elements. Make factories for playhtml elements!!
+
+## 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

@@ -8,8 +8,6 @@ playhtml is a library for magically creating collaborative interactive HTML elem
 <div id="couch" can-move style="font-size: 80px">🛋</div>
 ```
 
-This is designed as an open library for anyone to add on new interactions and capabilities. To get started, see the [New Capabilities](#new-capabilities).
-
 https://github.com/spencerc99/playhtml/assets/14796580/00e84e15-2c1c-4b4b-8e15-2af22f39db7a
 
 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.
@@ -42,6 +40,14 @@ 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.
+
+If you're trying this out and having trouble, please message me ([email](mailto:spencerc99@gmail.com), [twitter](https://twitter.com/spencerc99)) and I'm happy to help out!
+
+## 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
 
 A full list can be found in `types.ts` under `TagType`.
@@ -97,6 +103,8 @@ https://github.com/spencerc99/playhtml/assets/14796580/fae669b1-b3e2-404e-bd7a-3
 
 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`.
 
+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 I'd love to host your custom elements here as well.
+
 ## Plug-and-play Capabilities
 
 These capabilities are common ones that have been designed and created by the community. You should expect that they are relatively well-tested, and they simply build on top of the same API and constructs that `can-play` uses.
@@ -107,26 +115,30 @@ We welcome any contributions if you have custom `can-play` elements that you wou
 
 https://github.com/spencerc99/playhtml/assets/14796580/9c2b9bf6-142c-41e2-8c8f-93a3b121a73e
 
-Creates a movable object using 2D `translate` on the element. Dragging the element around will move it
+Creates a movable element using 2D `translate` on the element. Dragging the element around will move it
 
 **troubleshooting**
 
 - This currently doesn't work on `inline` display elements.
 - This currently doesn't work on touch screens.
 
-### `can-spin`
-
-Creates a rotatable object using a `rotate` `transform` on the element. Dragging the element to the left or right will rotate it counter-clockwise and clockwise respectively.
-
 ### `can-toggle`
 
 <blockquote class="twitter-tweet"><p lang="en" dir="ltr">today i installed some lamps on the demos-and-chill website<br><br>then <a href="https://twitter.com/_jzhao?ref_src=twsrc%5Etfw">@_jzhao</a> and i fought on whether to keep them on or not. <a href="https://t.co/sCspTwmRpS">pic.twitter.com/sCspTwmRpS</a></p>&mdash; spencer chang ☀️ (spencerchang.me @ bsky) (@spencerc99) <a href="https://twitter.com/spencerc99/status/1681048824884895744?ref_src=twsrc%5Etfw">July 17, 2023</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
 
-Creates an object that can be switched on and off. Clicking the element will toggle the `clicked` class on the element.
+Creates an element that can be switched on and off. Clicking the element will toggle the `clicked` class on the element.
+
+### `can-duplicate`
+
+Creates an element that duplicates a target element (specified by the value of the `can-duplicate` attribute, which can be an element's ID or custom CSS selector) when clicked. Optionally can specify where the duplicate element is inserted in the DOM via the `can-duplicate-to` setting (default is as a sibling to the original element).
 
 ### `can-grow`
 
-Creates an object that can be resized using a `scale` `transform`. Clicking the object will grow it, clicking with <kbd>ALT</kbd> will shrink it. Currently, the max size is 2x the original size and the min size is 1/2 the original size.
+Creates an element that can be resized using a `scale` `transform`. Clicking the element will grow it, clicking with <kbd>ALT</kbd> will shrink it. Currently, the max size is 2x the original size and the min size is 1/2 the original size.
+
+### `can-spin`
+
+Creates a rotatable element using a `rotate` `transform` on the element. Dragging the element to the left or right will rotate it counter-clockwise and clockwise respectively.
 
 ### `can-post`
 

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 | TouchEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    onClick?: (e: MouseEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    onDragStart?: (e: MouseEvent | TouchEvent, 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

@@ -1,11 +1,23 @@
 /// <reference lib="dom" />
+import { TagType } from "./types";
 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>>>;
 /**
  * Sets up any playhtml elements that are currently on the page.
- * Can be repeatedly called to set up new elements without affecting existing ones.
+ *
+ * Should be called only once. If you'd like to set up new elements, use `setupPlayElement`, which is exposed
+ * on the `playhtml` object on `window`.
  */
 export declare function setupElements(): void;
+export declare const playhtml: {
+    setupElements: typeof setupElements;
+    globalData: Y.Map<Y.Map<any>>;
+    elementHandlers: Map<string, Map<string, ElementHandler<any, any, any>>>;
+    setupPlayElement: typeof setupPlayElement;
+};
+/**
+ * Sets up a playhtml element to handle the given tag's capabilities.
+ */
+export declare function setupPlayElementForTag<T extends TagType>(element: HTMLElement, tag: T): void;
+export declare function setupPlayElement(element: Element): void;