playhtml 0.1.9 → 1.0.0

package/README.md

@@ -46,6 +46,63 @@ 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

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.