playhtml 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +49 -0
  2. package/dist/elements.d.ts +42 -33
  3. package/dist/icon.png +0 -0
  4. package/dist/main.d.ts +7 -2
  5. package/dist/noguchi-hanging-lamp.png +0 -0
  6. package/dist/playhtml.es.js +1997 -1833
  7. package/dist/playhtml.umd.js +5 -5
  8. package/dist/style.css +1 -1
  9. package/dist/types.d.ts +14 -8
  10. package/package.json +3 -1
package/README.md ADDED
@@ -0,0 +1,49 @@
1
+ # playhtml 🛝🌐
2
+
3
+ _interactive, collaborative html elements with a single data attribute_
4
+
5
+ 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:
6
+
7
+ ```html
8
+ <div can-move style="font-size: 80px">🛋</div>
9
+ ```
10
+
11
+ 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).
12
+
13
+ https://github.com/spencerc99/playhtml/assets/14796580/00e84e15-2c1c-4b4b-8e15-2af22f39db7a
14
+
15
+ ## Usage
16
+
17
+ To use this library, you can import the library and the associated styles from a CDN (in this case we will use [unpkg.com](https://unpkg.com)). Please make sure to do this after all the HTML elements on the page.
18
+
19
+ ```html
20
+ <body>
21
+ <!-- ... html elements here -->
22
+ <script type="module" src="https://unpkg.com/playhtml"></script>
23
+ <link rel="stylesheet" href="https://unpkg.com/playhtml/dist/style.css" />
24
+ </body>
25
+ ```
26
+
27
+ If you have dynamic elements that are hydrated after the initial load, you can call `playhtml.setupElements()` whenever needed to have the library look for elements that haven't been marked.
28
+
29
+ ```js
30
+ <script type="module">
31
+ import {setupElements} from "https://unpkg.com/playhtml"; setupElements();
32
+ </script>
33
+ ```
34
+
35
+ TODO: add import for React.
36
+
37
+ ## New Capabilities
38
+
39
+ `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.
40
+
41
+ To contribute your capability, see sample PR (TODO: LINK).
42
+
43
+ ## Contributing
44
+
45
+ Outside of contributing new capabilities, feel free to submit any issues or PRs for bugs or improvements to the core of the library.
46
+
47
+ ## Support & Maintenance
48
+
49
+ If you enjoy the idea of this library or like using it, please consider [sponsoring the project](https://github.com/sponsors/spencerc99). This will help ensure that the library is maintained and improved over time.
package/dist/elements.d.ts CHANGED
@@ -1,41 +1,50 @@
1
1
  /// <reference lib="dom" />
2
- import { Position } from "./types";
3
- export declare abstract class BaseElement<T> {
2
+ import { TagType } from "./types";
3
+ type ModifierKey = "ctrlKey" | "altKey" | "shiftKey" | "metaKey";
4
+ interface ElementInitializer<T = any> {
5
+ defaultData: T;
6
+ updateElement: (element: HTMLElement, data: T) => void;
7
+ onClick?: (e: MouseEvent, data: T, element: HTMLElement) => T;
8
+ onDrag?: (e: MouseEvent, data: T, element: HTMLElement) => T;
9
+ onDragStart?: (e: MouseEvent, data: T, element: HTMLElement) => T;
10
+ onMouseEnter?: (e: MouseEvent, data: T, element: HTMLElement) => T;
11
+ onKeyDown?: (e: KeyboardEvent, data: T, element: HTMLElement) => T;
12
+ onKeyUp?: (e: KeyboardEvent, data: T, element: HTMLElement) => T;
13
+ resetShortcut?: ModifierKey;
14
+ debounceMs?: number;
15
+ }
16
+ export interface ElementData<T = any> extends ElementInitializer<T> {
17
+ data?: T;
18
+ element: HTMLElement;
19
+ onChange: (data: T) => void;
20
+ }
21
+ export declare const TagTypeToElement: Record<TagType, ElementInitializer>;
22
+ export declare class ElementHandler<T = any> {
23
+ defaultData: T;
4
24
  element: HTMLElement;
5
25
  _data: T;
6
26
  onChange: (data: T) => void;
7
27
  debouncedOnChange: (data: T) => void;
8
- constructor(element: HTMLElement, data: T, onChange: (data: T) => void);
28
+ resetShortcut?: ModifierKey;
29
+ updateElement: (element: HTMLElement, data: T) => void;
30
+ constructor({ element, onChange, defaultData, data, updateElement, onClick, onDrag, onDragStart, onMouseEnter, onKeyDown, onKeyUp, resetShortcut, debounceMs, }: ElementData<T>);
9
31
  get data(): T;
32
+ /**
33
+ * // PRIVATE USE ONLY \\
34
+ *
35
+ * 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
36
+ * reactivity.
37
+ * (e.g. calling `updateElement` and `onChange`)
38
+ */
39
+ set __data(data: T);
40
+ /**
41
+ * Public-use setter for data that makes the change to all clients.
42
+ */
10
43
  set data(data: T);
11
- abstract updateElement(data: T): void;
12
- }
13
- export declare class SpinElement extends BaseElement<number> {
14
- isDown: boolean;
15
- startX: number;
16
- constructor(element: HTMLElement, rotation: number | undefined, onChange: (rotation: number) => void);
17
- updateElement(rotation: number): void;
18
- mouseDownHandler(e: MouseEvent): void;
19
- mouseMoveHandler(e: MouseEvent): void;
20
- mouseUpHandler(_e: MouseEvent): void;
21
- }
22
- export declare class MoveElement extends BaseElement<Position> {
23
- isDown: boolean;
24
- startMouseX: number;
25
- startMouseY: number;
26
- constructor(element: HTMLElement, position: Position | undefined, onChange: (position: Position) => void);
27
- updateElement({ x, y }: Position): void;
28
- mouseDownHandler(e: MouseEvent): void;
29
- mouseMoveHandler(e: MouseEvent): void;
30
- mouseUpHandler(_e: MouseEvent): void;
31
- }
32
- export declare class GrowElement extends BaseElement<number> {
33
- maxScale: number;
34
- readonly originalCursor: string;
35
- readonly cutCursor: string;
36
- isHovering: boolean;
37
- constructor(element: HTMLElement, scale: number | undefined, onChange: (scale: number) => void, maxScale?: number);
38
- updateElement(data: number): void;
39
- mouseOverHandler(e: MouseEvent | KeyboardEvent): void;
40
- clickHandler(e: MouseEvent): void;
44
+ setDataDebounced(data: T): void;
45
+ /**
46
+ * Resets the element to its default state.
47
+ */
48
+ reset(): void;
41
49
  }
50
+ export {};
package/dist/icon.png ADDED
Binary file
package/dist/main.d.ts CHANGED
@@ -1,3 +1,8 @@
1
1
  /// <reference lib="dom" />
2
- import { TagType } from "./types";
3
- export declare const TagData: Record<TagType, (eles: HTMLElement[]) => void>;
2
+ import * as Y from "yjs";
3
+ export declare const globalData: Y.Map<Y.Map<any>>;
4
+ /**
5
+ * Sets up any playhtml elements that are currently on the page.
6
+ * Can be repeatedly called to set up new elements without affecting existing ones.
7
+ */
8
+ export declare function setupElements(): void;
package/dist/noguchi-hanging-lamp.png ADDED
Binary file