playhtml 2.1.12 → 2.2.1

package/README.md

@@ -181,6 +181,59 @@ 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.
 
+#### Data updates: mutator vs replacement
+
+playhtml supports two ways to update an element's `data` via `setData`, and they have different semantics:
+
+- **Mutator form**: pass a function that receives a draft and mutate it in place. This is merge-friendly (supports adding to a list without conflicts) and is the recommended way to update nested arrays/objects.
+- **Replacement form**: pass a full value. This replaces the entire snapshot and is useful for canonical state.
+
+Examples
+
+1. **Mutator (merge-friendly): append to a list**
+
+```tsx
+// data: { messages: string[] }
+setData((draft) => {
+  draft.messages.push("hello");
+});
+```
+
+Note: when working with the mutator forms, there are some limitations on how you can mutate the array properly.
+**✅ Supported Array Operations:**
+
+```tsx
+setData((draft) => {
+  // ✅ Adding elements
+  draft.items.push(newItem);
+
+  // ✅ Removing/inserting at specific positions
+  draft.items.splice(0, 1); // Remove first element
+  draft.items.splice(2, 0, newItem); // replace element at index 2
+
+  // ✅ Modifying existing objects in the array
+  draft.items[0].name = "updated";
+});
+```
+
+**❌ Unsupported Array Operations:**
+
+```tsx
+setData((draft) => {
+  // ❌ These will throw "array assignment is not implemented / supported"
+  draft.items.shift(); // Use splice(0, 1) instead
+  draft.items.pop(); // Use splice(-1, 1) instead
+  draft.items[index] = newItem; // Use splice(index, 1, newItem) instead
+});
+```
+
+2. **Replacement (overwrite snapshot): toggle boolean**
+
+```tsx
+// data: { on: boolean; ... }
+setData({ ...data, on: !data.on });
+```
+
 ### 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.
@@ -244,3 +297,7 @@ See [CONTRIBUTING.md](https://github.com/spencerc99/playhtml/blob/main/CONTRIBUT
 ## Support & Maintenance
 
 Thank you for considering reading this little README and browing this project! I'd love to see you share the library and what you've made with it to me and with your friends. And if you enjoy using this, please consider [sponsoring the project or sending a small donation](https://github.com/sponsors/spencerc99). This helps ensure that the library is maintained and improved over time and funds the hosting costs for the syncing and persistence services.
+
+```
+
+```

package/dist/main.d.ts

@@ -1,17 +1,16 @@
-/// <reference lib="dom" />
-
-import { ElementAwarenessEventHandlerData } from '@playhtml/common';
-import { ElementData } from '@playhtml/common';
-import { ElementEventHandlerData } from '@playhtml/common';
-import { ElementInitializer } from '@playhtml/common';
-import { ElementSetupData } from '@playhtml/common';
-import { EventMessage } from '@playhtml/common';
-import { ModifierKey } from '@playhtml/common';
-import { PlayEvent } from '@playhtml/common';
-import { RegisteredPlayEvent } from '@playhtml/common';
-import { TagType } from '@playhtml/common';
+import { default as default_2 } from 'y-partykit/provider';
+import { ElementAwarenessEventHandlerData } from '../../common/src';
+import { ElementData } from '../../common/src';
+import { ElementEventHandlerData } from '../../common/src';
+import { ElementInitializer } from '../../common/src';
+import { ElementSetupData } from '../../common/src';
+import { EventMessage } from '../../common/src';
+import { MappedTypeDescription } from '@syncedstore/core/types/doc';
+import { ModifierKey } from '../../common/src';
+import { PlayEvent } from '../../common/src';
+import { RegisteredPlayEvent } from '../../common/src';
+import { TagType } from '../../common/src';
 import * as Y from 'yjs';
-import YPartyKitProvider from 'y-partykit/provider';
 
 declare function dispatchPlayEvent(message: EventMessage): void;
 
@@ -49,9 +48,29 @@ declare class ElementHandler<T = any, U = any, V = any> {
     getAwarenessEventHandlerData(): ElementAwarenessEventHandlerData<T, U, V>;
     getSetupData(): ElementSetupData<T, U>;
     /**
-     * Public-use setter for data that makes the change to all clients.
+     * Public setter for element data.
+     *
+     * Semantics:
+     * - Mutator form: setData((draft) => { ... })
+     *   When data is backed by SyncedStore/Yjs (dataMode = "syncedstore"),
+     *   the draft is a live CRDT proxy. You can mutate nested arrays/objects
+     *   and the change will be merged across clients without conflicts.
+     *   Example:
+     *     setData(d => { d.list.push(item); });
+     *
+     * - Value form: setData(value)
+     *   Replaces the entire data snapshot. Use this when you need canonical
+     *   replacement semantics (e.g., snapshot from a mirror) or when running
+     *   in legacy plain mode. Example:
+     *     setData({ on: true });
+     *
+     * Notes:
+     * - In plain mode, only the value form results in a sync; mutating draft
+     *   is a no-op. Prefer the mutator form for merge-friendly edits.
+     * - Directly mutating eventData.data may work in SyncedStore mode, but the
+     *   recommended portable pattern is setData(draft => { ... }).
      */
-    setData(data: T): void;
+    setData(data: T | ((draft: T) => void)): void;
     setMyAwareness(data: V): void;
     setDataDebounced(data: T): void;
     /**
@@ -60,6 +79,8 @@ declare class ElementHandler<T = any, U = any, V = any> {
     reset(): void;
 }
 
+declare let globalData: Y.Map<any>;
+
 export declare interface InitOptions<T = any> {
     /**
      * The room to connect users to (this should be a string that matches the other users
@@ -98,9 +119,13 @@ export declare interface InitOptions<T = any> {
      * Runs if playhtml fails to connect. Useful to show error messages and debugging.
      */
     onError?: () => void;
+    /**
+     * If true, will render some helpful development UI.
+     */
+    developmentMode?: boolean;
 }
 
-declare function initPlayHTML({ host, extraCapabilities, events, defaultRoomOptions, room: inputRoom, onError, }?: InitOptions): Promise<YPartyKitProvider | undefined>;
+declare function initPlayHTML({ host, extraCapabilities, events, defaultRoomOptions, room: inputRoom, onError, developmentMode, }?: InitOptions): Promise<default_2 | undefined>;
 
 export declare const playhtml: PlayHTMLComponents;
 
@@ -110,7 +135,8 @@ declare interface PlayHTMLComponents {
     setupPlayElement: typeof setupPlayElement;
     removePlayElement: typeof removePlayElement;
     setupPlayElementForTag: typeof setupPlayElementForTag;
-    globalData: Y.Map<any> | undefined;
+    syncedStore: (typeof store)["play"];
+    globalData: typeof globalData;
     elementHandlers: Map<string, Map<string, ElementHandler>> | undefined;
     eventHandlers: Map<string, Array<RegisteredPlayEvent>> | undefined;
     dispatchPlayEvent: typeof dispatchPlayEvent;
@@ -148,4 +174,10 @@ declare function setupPlayElement(element: Element, { ignoreIfAlreadySetup }?: {
  */
 declare function setupPlayElementForTag<T extends TagType | string>(element: HTMLElement, tag: T): Promise<void>;
 
+declare const store: MappedTypeDescription<StoreShape>;
+
+declare type StoreShape = {
+    play: Record<string, Record<string, any>>;
+};
+
 export { }