playhtml 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.
@@ -44,9 +42,11 @@ If you have dynamic elements that are hydrated after the initial load, you can c
 
 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://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.
+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
 
@@ -66,8 +66,15 @@ https://github.com/spencerc99/playhtml/assets/14796580/fae669b1-b3e2-404e-bd7a-3
 <img can-play id="customCandle" src="/candle-gif.gif" />
 <!-- IMPORTANT: this data must be set _before_ importing the playhtml library. -->
 <script>
-  // Every HTML element with an ID has a variable corresponding to that ID name in the global context (see https://stackoverflow.com/questions/3434278/do-dom-tree-elements-with-ids-become-global-properties/3434388#3434388)
-  // This is fun, magical, and readable for small projects, but if you have a larger, complex project, I would advise using `document.getElementById` or `document.querySelector`...
+  let candle = document.getElementById("customCandle");
+  candle.defaultData = true;
+  candle.onClick = (_e, { data, setData }) => {
+    setData(!data);
+  };
+  candle.updateElement = ({ data }) => {
+    candle.src = data ? "/candle-gif.gif" : "/candle-off.png";
+  };
+  candle.resetShortcut = "shiftKey";
   customCandle.defaultData = true;
   customCandle.onClick = (_e, { data, setData }) => {
     setData(!data);
@@ -80,20 +87,6 @@ https://github.com/spencerc99/playhtml/assets/14796580/fae669b1-b3e2-404e-bd7a-3
   //     setData(!data);
   //   });
   // };
-  customCandle.updateElement = ({ data }) => {
-    customCandle.src = data ? "/candle-gif.gif" : "/candle-off.png";
-  };
-
-  // Alternatively
-  // let candle = document.getElementById('customCandle');
-  // candle.defaultData = true;
-  // candle.onClick = (_e, { data, setData }) => {
-  //   setData(!data);
-  // };
-  // candle.updateElement = ({ data }) => {
-  //   candle.src = data ? "/candle-gif.gif" : "/candle-off.png";
-  // };
-  // candle.resetShortcut = "shiftKey";
 </script>
 
 <!-- Import playhtml -->
@@ -101,38 +94,44 @@ https://github.com/spencerc99/playhtml/assets/14796580/fae669b1-b3e2-404e-bd7a-3
 <link rel="stylesheet" href="https://unpkg.com/playhtml/dist/style.css" />
 ```
 
-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`.
+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).
+
+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.
 
 ## 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.
 
-We welcome any contributions if you have custom `can-play` elements that you would like to add to the library! Please make a PR.
-
 ### `can-move`
 
 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`
 
@@ -140,21 +139,9 @@ Creates an object that can be resized using a `scale` `transform`. Clicking the
 
 Creates a communal forum from a `form` element. The form will sync any new submissions including all the `input` elements in the form, using their `name` property as the key and their value as the value. New messages will be currently prepended to the element with the `guestbookMessages` ID. TODO: make this generic and take user input
 
----
-
-To add new ones, please find contributor guidelines in [New Capabilities](#new-capabilities).
-
 ## Contributing
 
-### New Capabilities
-
-`playhtml` is designed to be a collective library of magical capabilities that anyone can attach to arbitrary HTML elements. If you have an idea for a new capability, please first ensure that there is not a duplicate existing one in the current library (see `TagType` in `types.ts`). Please make a proposal for the capability you would like to add by opening an issue with the `new-capability` label.
-
-To contribute your capability, see sample PR (TODO: LINK).
-
----
-
-Outside of contributing new capabilities, feel free to submit any issues or PRs for bugs or improvements to the core of the library.
+See [CONTRIBUTING.md](https://github.com/spencerc99/playhtml/blob/main/CONTRIBUTING.md).
 
 ## Support & Maintenance
 

package/dist/elements.d.ts

@@ -1,49 +1,5 @@
 /// <reference lib="dom" />
-import { TagType } from "./types";
-type ModifierKey = "ctrlKey" | "altKey" | "shiftKey" | "metaKey";
-export interface ElementInitializer<T = any, U = any, V = any> {
-    defaultData: T | ((element: HTMLElement) => T);
-    defaultLocalData?: U | ((element: HTMLElement) => U);
-    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, 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, V = any> {
-    data: T;
-    localData: U;
-    awareness: V[];
-    element: HTMLElement;
-    setData: (data: T) => void;
-    setLocalData: (data: U) => void;
-    setLocalAwareness: (data: V) => void;
-}
-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;
-}
+import { ElementAwarenessEventHandlerData, ElementData, ElementEventHandlerData, ElementInitializer, ElementSetupData, ModifierKey, TagType } from "./types";
 export declare const TagTypeToElement: Record<Exclude<TagType, "can-play">, ElementInitializer>;
 export declare class ElementHandler<T = any, U = any, V = any> {
     defaultData: T;
@@ -85,4 +41,3 @@ export declare class ElementHandler<T = any, U = any, V = any> {
      */
     reset(): void;
 }
-export {};

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, 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;