playhtml 0.1.8 → 1.0.0

package/README.md

@@ -46,8 +46,67 @@ If you have dynamic elements that are hydrated after the initial load, you can c
 
 A full list can be found in `types.ts` under `TagType`.
 
+## Custom Capabilities
+
+### `can-play`
+
+`can-play` is the fully customizable experience of `playhtml`. You can create anything using simple HTML, CSS, and Javascript by simply adding on the functionality needed to the element itself. The library will handle magically syncing and persisting any data that you store.
+
+Here's the simple example included on the playhtml website:
+
+https://github.com/spencerc99/playhtml/assets/14796580/fae669b1-b3e2-404e-bd7a-3d36b81c572d
+
+```html
+<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`...
+  customCandle.defaultData = true;
+  customCandle.onClick = (_e, { data, setData }) => {
+    setData(!data);
+  };
+  // The above statement could also be done using the `additionalSetup`
+  // which can initialize several different event listeners and custom logic.
+  // customCandle.additionalSetup = ({ getData, setData }) => {
+  //   customCandle.addEventListener("click", (_e) => {
+  //     const data = getData();
+  //     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 -->
+<script type="module" src="https://unpkg.com/playhtml"></script>
+<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`.
+
+## 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
 
 **troubleshooting**
@@ -61,6 +120,8 @@ Creates a rotatable object using a `rotate` `transform` on the element. Dragging
 
 ### `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.
 
 ### `can-grow`
@@ -69,6 +130,8 @@ Creates an object that can be resized using a `scale` `transform`. Clicking the
 
 ### `can-post`
 
+![image](https://github.com/spencerc99/playhtml/assets/14796580/6de3fcab-2372-4080-b46f-cd768f1ed44e)
+
 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
 
 ---

package/dist/elements.d.ts

@@ -1,17 +1,14 @@
 /// <reference lib="dom" />
 import { TagType } from "./types";
 type ModifierKey = "ctrlKey" | "altKey" | "shiftKey" | "metaKey";
-interface ElementInitializer<T = any, U = any> {
-    defaultData: T;
-    defaultLocalData?: U;
+export interface ElementInitializer<T = any, U = any> {
+    defaultData: T | ((element: HTMLElement) => T);
+    defaultLocalData?: U | ((element: HTMLElement) => U);
     updateElement: (data: ElementEventHandlerData<T, U>) => void;
-    onClick?: (e: MouseEvent, eventData: 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;
-    onMouseEnter?: (e: MouseEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    onKeyDown?: (e: KeyboardEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    onKeyUp?: (e: KeyboardEvent, eventData: ElementEventHandlerData<T, U>) => void;
-    onSubmit?: (e: SubmitEvent, eventData: ElementEventHandlerData<T, U>) => void;
+    additionalSetup?: (eventData: ElementSetupData<T, U>) => void;
     resetShortcut?: ModifierKey;
     debounceMs?: number;
 }
@@ -28,7 +25,14 @@ interface ElementEventHandlerData<T = any, U = any> {
     setData: (data: T) => void;
     setLocalData: (data: U) => void;
 }
-export declare const TagTypeToElement: Record<TagType, ElementInitializer>;
+interface ElementSetupData<T = any, U = any> {
+    getData: () => T;
+    getLocalData: () => U;
+    getElement: () => HTMLElement;
+    setData: (data: T) => void;
+    setLocalData: (data: U) => void;
+}
+export declare const TagTypeToElement: Record<Exclude<TagType, "can-play">, ElementInitializer>;
 export declare class ElementHandler<T = any, U = any> {
     defaultData: T;
     localData: U;
@@ -38,7 +42,7 @@ export declare class ElementHandler<T = any, U = any> {
     debouncedOnChange: (data: T) => void;
     resetShortcut?: ModifierKey;
     updateElement: (data: ElementEventHandlerData<T, U>) => void;
-    constructor({ element, onChange, defaultData, defaultLocalData, data, updateElement, onClick, onDrag, onDragStart, onMouseEnter, onKeyDown, onKeyUp, onSubmit, resetShortcut, debounceMs, }: ElementData<T>);
+    constructor({ element, onChange, defaultData, defaultLocalData, data, updateElement, onClick, onDrag, onDragStart, additionalSetup, resetShortcut, debounceMs, }: ElementData<T>);
     get data(): T;
     setLocalData(localData: U): void;
     /**
@@ -50,6 +54,7 @@ export declare class ElementHandler<T = any, U = any> {
      */
     set __data(data: T);
     getEventHandlerData(): ElementEventHandlerData<T, U>;
+    getSetupData(): ElementSetupData<T, U>;
     /**
      * Public-use setter for data that makes the change to all clients.
      */

package/dist/main.d.ts

@@ -1,7 +1,9 @@
 /// <reference lib="dom" />
 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.