playhtml 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
 
+## 2.0.0 - 2023-08-23
+
+- **BREAKING CHANGE**: Changed the initializing of playhtml to be an explicit call of `playhtml.init()` from just a normal import. You can still use the old code if you pin the import to any version 1.3.1 (e.g. use `https://unpkg.com/playhtml@1.3.1` as the import source).
+
+**OLD CODE:**
+
+```html
+<script type="module" src="https://unpkg.com/playhtml"></script>
+<link rel="stylesheet" href="https://unpkg.com/playhtml/dist/style.css" />
+```
+
+**NEW CODE:**
+
+```html
+<script type="module">
+  import "https://unpkg.com/playhtml";
+  playhtml.init();
+  // Optionally you could call
+  // playhtml.init({
+  //  room: window.location.pathname,
+  //  host: "mypartykit.user.partykit.dev"
+  // })
+</script>
+<link rel="stylesheet" href="https://unpkg.com/playhtml/dist/style.css" />
+```
+
+This change allows for more flexible use of the package, including specifying a partykit host and room.
+
+- was accidentally importing all my files for the website into the package, blowing it up to 4MB. I've fixed this and compressed down the `.d.ts` types file to just what is needed, so the package is down to 360KB. It should load much faster on websites now :)
+
+## 1.3.1 - 2023-08-09
+
+- Removed unused code and consolidated types in `types.ts`
+
 ## 1.3.0 - 2023-08-07
 
 - Added support for `can-duplicate` capability to duplicate elements. Make factories for playhtml elements!!

package/README.md

@@ -27,7 +27,15 @@ To use this library, you can import the library and the associated styles from a
   id="openSign"
   <!-- INVALID EXAMPLE <img src="https://media2.giphy.com/media/lL7A3Li0YtFHq/giphy.gif?cid=ecf05e47ah89o71gzz7ke7inrgb1ai1xcbrjnqdf7o890118&ep=v1_stickers_search&rid=giphy.gif" can-move /> -->
   <!-- import the script -->
-  <script type="module" src="https://unpkg.com/playhtml"></script>
+  <script type="module">
+    import "https://unpkg.com/playhtml";
+    playhtml.init();
+    // Optionally you could customize the room and host, like so:
+    // playhtml.init({
+    //  room: window.location.pathname,
+    //  host: "mypartykit.user.partykit.dev"
+    // })
+  </script>
   <link rel="stylesheet" href="https://unpkg.com/playhtml/dist/style.css" />
 </body>
 ```
@@ -66,8 +74,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,37 +95,26 @@ 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 -->
-<script type="module" src="https://unpkg.com/playhtml"></script>
+<script type="module">
+  import "https://unpkg.com/playhtml";
+  playhtml.init();
+</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`.
+See all supported properties in the `ElementInitializer` [object in `types.ts`](https://github.com/spencerc99/playhtml/blob/main/src/types.ts#L13).
 
-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.
+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
@@ -146,21 +150,9 @@ Creates a rotatable element using a `rotate` `transform` on the element. Draggin
 
 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/main.d.ts

@@ -1,23 +1,138 @@
-/// <reference lib="dom" />
-import { TagType } from "./types";
-import * as Y from "yjs";
-import { ElementHandler } from "./elements";
-export declare function getElementFromId(id: string): HTMLElement | null;
-/**
- * Sets up any playhtml elements that are currently on the page.
- *
- * 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;
+/// <reference lib="dom" />
+
+import * as Y from 'yjs';
+
+declare interface ElementAwarenessEventHandlerData<T = any, U = any, V = any> extends ElementEventHandlerData<T, U, V> {
+    myAwareness?: V;
+}
+
+declare 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;
+}
+
+declare 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;
+}
+
+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, 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;
+    /**
+     * // PRIVATE USE ONLY \\
+     *
+     * Updates the internal state with the given data and handles all the downstream effects. Should only be used by the sync code to ensure one-way
+     * reactivity.
+     * (e.g. calling `updateElement` and `onChange`)
+     */
+    set __data(data: T);
+    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.
+     */
+    reset(): void;
+}
+
+declare 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;
+}
+
+declare 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;
+}
+
+declare interface InitOptions {
+    room?: string;
+    host?: string;
+}
+
+export declare function initPlayHTML({ room, host, }?: InitOptions): void;
+
+declare type ModifierKey = "ctrlKey" | "altKey" | "shiftKey" | "metaKey";
+
+export declare const playhtml: PlayHTMLComponents;
+
+declare interface PlayHTMLComponents {
+    init: typeof initPlayHTML;
+    setupElements: typeof setupElements;
+    setupPlayElement: typeof setupPlayElement;
+    globalData: Y.Map<any> | undefined;
+    elementHandlers: Map<string, Map<string, ElementHandler>> | undefined;
+}
+
+/**
+ * Sets up any playhtml elements that are currently on the page.
+ *
+ * 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 function setupPlayElement(element: Element): void;
+
+/**
+ * Sets up a playhtml element to handle the given tag's capabilities.
+ */
+export declare function setupPlayElementForTag<T extends TagType>(element: HTMLElement, tag: T): void;
+
+declare enum TagType {
+    "CanPlay" = "can-play",
+    "CanMove" = "can-move",
+    "CanSpin" = "can-spin",
+    "CanGrow" = "can-grow",
+    "CanToggle" = "can-toggle",
+    "CanDuplicate" = "can-duplicate",
+    "CanPost" = "can-post"
+}
+
+export { }