playhtml 0.1.3 → 0.1.5
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.
- package/README.md +49 -0
- package/dist/elements.d.ts +31 -41
- package/dist/main.d.ts +2 -2
- package/dist/noguchi-hanging-lamp.png +0 -0
- package/dist/playhtml.es.js +2286 -2163
- package/dist/playhtml.umd.js +5 -5
- package/dist/style.css +1 -1
- package/dist/types.d.ts +14 -8
- 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,60 +1,50 @@
|
|
|
1
1
|
/// <reference lib="dom" />
|
|
2
|
-
import {
|
|
2
|
+
import { TagType } from "./types";
|
|
3
3
|
type ModifierKey = "ctrlKey" | "altKey" | "shiftKey" | "metaKey";
|
|
4
|
-
|
|
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;
|
|
5
24
|
element: HTMLElement;
|
|
6
|
-
abstract initialData: T;
|
|
7
25
|
_data: T;
|
|
8
26
|
onChange: (data: T) => void;
|
|
9
27
|
debouncedOnChange: (data: T) => void;
|
|
10
28
|
resetShortcut?: ModifierKey;
|
|
11
|
-
|
|
29
|
+
updateElement: (element: HTMLElement, data: T) => void;
|
|
30
|
+
constructor({ element, onChange, defaultData, data, updateElement, onClick, onDrag, onDragStart, onMouseEnter, onKeyDown, onKeyUp, resetShortcut, debounceMs, }: ElementData<T>);
|
|
12
31
|
get data(): T;
|
|
13
32
|
/**
|
|
14
|
-
*
|
|
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.
|
|
15
37
|
* (e.g. calling `updateElement` and `onChange`)
|
|
16
38
|
*/
|
|
17
|
-
set
|
|
39
|
+
set __data(data: T);
|
|
18
40
|
/**
|
|
19
|
-
*
|
|
41
|
+
* Public-use setter for data that makes the change to all clients.
|
|
20
42
|
*/
|
|
21
|
-
|
|
43
|
+
set data(data: T);
|
|
44
|
+
setDataDebounced(data: T): void;
|
|
22
45
|
/**
|
|
23
46
|
* Resets the element to its default state.
|
|
24
47
|
*/
|
|
25
48
|
reset(): void;
|
|
26
49
|
}
|
|
27
|
-
export declare class SpinElement extends BaseElement<number> {
|
|
28
|
-
isDown: boolean;
|
|
29
|
-
startX: number;
|
|
30
|
-
initialData: number;
|
|
31
|
-
constructor(element: HTMLElement, rotation: number | undefined, onChange: (rotation: number) => void);
|
|
32
|
-
updateElement(rotation: number): void;
|
|
33
|
-
mouseDownHandler(e: MouseEvent): void;
|
|
34
|
-
mouseMoveHandler(e: MouseEvent): void;
|
|
35
|
-
mouseUpHandler(_e: MouseEvent): void;
|
|
36
|
-
}
|
|
37
|
-
export declare class MoveElement extends BaseElement<Position> {
|
|
38
|
-
initialData: Position;
|
|
39
|
-
isDown: boolean;
|
|
40
|
-
startMouseX: number;
|
|
41
|
-
startMouseY: number;
|
|
42
|
-
constructor(element: HTMLElement, position: Position | undefined, onChange: (position: Position) => void);
|
|
43
|
-
updateDisplay(): void;
|
|
44
|
-
updateElement({ x, y }: Position): void;
|
|
45
|
-
mouseDownHandler(e: MouseEvent): void;
|
|
46
|
-
mouseMoveHandler(e: MouseEvent): void;
|
|
47
|
-
mouseUpHandler(_e: MouseEvent): void;
|
|
48
|
-
}
|
|
49
|
-
export declare class GrowElement extends BaseElement<number> {
|
|
50
|
-
initialData: number;
|
|
51
|
-
maxScale: number;
|
|
52
|
-
readonly originalCursor: string;
|
|
53
|
-
readonly cutCursor: string;
|
|
54
|
-
isHovering: boolean;
|
|
55
|
-
constructor(element: HTMLElement, scale: number | undefined, onChange: (scale: number) => void, maxScale?: number);
|
|
56
|
-
updateElement(data: number): void;
|
|
57
|
-
mouseOverHandler(e: MouseEvent | KeyboardEvent): void;
|
|
58
|
-
clickHandler(e: MouseEvent): void;
|
|
59
|
-
}
|
|
60
50
|
export {};
|
package/dist/main.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/// <reference lib="dom" />
|
|
2
|
-
import
|
|
3
|
-
export declare const
|
|
2
|
+
import * as Y from "yjs";
|
|
3
|
+
export declare const globalData: Y.Map<Y.Map<any>>;
|
|
4
4
|
/**
|
|
5
5
|
* Sets up any playhtml elements that are currently on the page.
|
|
6
6
|
* Can be repeatedly called to set up new elements without affecting existing ones.
|
|
Binary file
|