playhtml 2.0.2 → 2.0.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
 
+## 2.0.4 - 2023-09-07
+
+- added @playhtml/react library
+- added `firstSetup` export from playhtml for raising error if it hasn't been initialized.
+- cleaned up exports
+
 ## 2.0.2 - 2023-08-23
 
 - handle deprecated import version by using a timeout. This adds a significant delay to the initialization of any client using the old method and logs a warning.

package/README.md

@@ -1,8 +1,8 @@
-# playhtml 🛝🌐
+# <a href="https://playhtml.fun">playhtml</a> 🛝🌐 [![npm release](https://img.shields.io/npm/v/playhtml?color=%23ff980c)](https://www.npmjs.com/package/playhtml) [![Downloads](https://img.shields.io/npm/dm/playhtml)](https://www.npmjs.com/package/spencerc99/playhtml) [![Size](https://img.shields.io/bundlephobia/min/playhtml?color=%23c6e1ea)](https://www.npmjs.com/package/spencerc99/playhtml)
 
 _interactive, collaborative html elements with a single data attribute_
 
-playhtml is a library for magically creating collaborative interactive HTML elements that persist their state across sessions. For example, you can create a movable piece of HTML "furniture" by adding the `can-move` attribute:
+playhtml is a fast, small (~300KB), and expressive library for magically creating collaborative interactive HTML elements that persist their state across sessions. For example, you can create a movable piece of HTML "furniture" by adding the `can-move` attribute:
 
 ```html
 <div id="couch" can-move style="font-size: 80px">🛋</div>
@@ -114,13 +114,16 @@ The only required properties are `defaultData`, `updateElement` and some kind of
 
 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.
 
+### Advanced
+
+IDs are recommended on all elements to uniquely identify them. If you are applying the same capability to several elements, you can also use the `selector-id` attribute to specify a selector to the elements that distinguishes them. The ID will be the index of the element in that selector query.
+
 ## 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.
 
 ### `can-move`
-
-https://github.com/spencerc99/playhtml/assets/14796580/9c2b9bf6-142c-41e2-8c8f-93a3b121a73e
+https://github.com/spencerc99/playhtml/assets/14796580/215c7631-d71f-40e6-bdda-bd8146a88006
 
 Creates a movable element using 2D `translate` on the element. Dragging the element around will move it
 
@@ -130,12 +133,16 @@ Creates a movable element using 2D `translate` on the element. Dragging the elem
 - This currently doesn't work on touch screens.
 
 ### `can-toggle`
+https://github.com/spencerc99/playhtml/assets/14796580/7e667c06-c32e-4369-b250-c9ca321de163
 
-<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>
+_from https://twitter.com/spencerc99/status/1681048824884895744_
 
 Creates an element that can be switched on and off. Clicking the element will toggle the `clicked` class on the element.
 
 ### `can-duplicate`
+https://github.com/spencerc99/playhtml/assets/14796580/6d9f1228-08cf-45a7-987a-8bebfaaefd83
+
+_used to programmatically and dynamically create new playhtml elements that aren't included in the initial HTML_
 
 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).
 

package/dist/main.d.ts

@@ -1,30 +1,13 @@
 /// <reference lib="dom" />
 
+import { ElementAwarenessEventHandlerData } from '../../common/src';
+import { ElementData } from '../../common/src';
+import { ElementEventHandlerData } from '../../common/src';
+import { ElementSetupData } from '../../common/src';
+import { ModifierKey } from '../../common/src';
+import { TagType } from '@playhtml/common';
 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;
-}
+import YPartyKitProvider from 'y-partykit/provider';
 
 declare class ElementHandler<T = any, U = any, V = any> {
     defaultData: T;
@@ -67,63 +50,29 @@ declare class ElementHandler<T = any, U = any, V = any> {
     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";
+declare function initPlayHTML({ room, host, }?: InitOptions): YPartyKitProvider | undefined;
 
 export declare const playhtml: PlayHTMLComponents;
 
 declare interface PlayHTMLComponents {
     init: typeof initPlayHTML;
     setupPlayElement: typeof setupPlayElement;
+    setupPlayElementForTag: typeof setupPlayElementForTag;
     globalData: Y.Map<any> | undefined;
     elementHandlers: Map<string, Map<string, ElementHandler>> | undefined;
+    firstSetup: boolean;
 }
 
-export declare function setupPlayElement(element: Element): void;
+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"
-}
+declare function setupPlayElementForTag<T extends TagType>(element: HTMLElement, tag: T): void;
 
 export { }