@videojs/html 10.0.0-beta.22 → 10.0.0-beta.24

package/docs/reference/snapshot-controller.md

@@ -0,0 +1,208 @@
+# SnapshotController
+
+Reactive controller for subscribing to a State container in HTML custom elements
+
+`SnapshotController` subscribes to a `State` container and triggers host updates when state changes. It has two overloads:
+
+**Full state** — returns the entire state object. Re-renders on any state change.
+
+ts
+
+```
+class Display extends HTMLElement {
+  #state = new SnapshotController(this, sliderState);
+
+  render() {
+    const value = this.#state.value;
+    // Full state object
+  }
+}
+```
+
+**With selector** — returns a derived value from state. Re-renders only when the selected value changes (using shallow equality).
+
+ts
+
+```
+class SliderValue extends HTMLElement {
+  #value = new SnapshotController(this, sliderState, (s) => s.value);
+
+  render() {
+    return this.#value.value; // Only the selected slice
+  }
+}
+```
+
+Use `.track(state)` to switch to a different `State` container at runtime.
+
+### SnapshotController vs StoreController
+
+Both are reactive controllers, but they operate at different levels:
+
+`SnapshotController`
+
+[`StoreController`](./store-controller.md)
+
+**Input**
+
+`State` container
+
+Store instance or context
+
+**Subscribes**
+
+Always
+
+Only with a selector
+
+**Use case**
+
+Subscribe to raw state changes
+
+Access store actions and optionally subscribe
+
+`SnapshotController` is lower-level. It works with `State` containers directly — the reactive primitives that back a store. Use it when building custom controllers or working outside the player store system.
+
+[`StoreController`](./store-controller.md) is higher-level. It resolves a store from a context or direct reference and internally creates a `SnapshotController` when you pass a selector. Use it for player UI elements.
+
+### Lifecycle
+
+`SnapshotController` subscribes on `hostConnected()` and unsubscribes on `hostDisconnected()`. The React equivalent is [`useSnapshot`](/docs/framework/react/reference/use-snapshot).
+
+## API Reference
+
+### Without Selector
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`host*`
+
+`ReactiveControllerHost`
+
+`—`
+
+▸
+
+Description
+
+The host element that owns this controller.
+
+`state*`
+
+`State<T>`
+
+`—`
+
+▸
+
+Description
+
+The State container to subscribe to.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`R`
+
+`track`
+
+`function`
+
+▸
+
+Description
+
+Switch to tracking a different state container.
+
+Type
+
+`(state: State<T>) => void`
+
+### With Selector
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`host*`
+
+`ReactiveControllerHost`
+
+`—`
+
+▸
+
+Description
+
+The host element that owns this controller.
+
+`state*`
+
+`State<T>`
+
+`—`
+
+▸
+
+Description
+
+The State container to subscribe to.
+
+`selector*`
+
+`Selector<T, R>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the state.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`R`
+
+`track`
+
+`function`
+
+▸
+
+Description
+
+Switch to tracking a different state container.
+
+Type
+
+`(state: State<T>) => void`

package/docs/reference/store-controller.md

@@ -0,0 +1,180 @@
+# StoreController
+
+Reactive controller for subscribing to store state in HTML custom elements
+
+`StoreController` is a reactive controller for accessing store state and actions in custom elements. It accepts a store instance or a context, resolving the store automatically.
+
+**Without selector** — returns the store instance directly. Does NOT subscribe to changes. Use this to access store actions.
+
+ts
+
+```
+class VolumeControl extends HTMLElement {
+  #store = new StoreController(this, storeSource);
+
+  handleClick() {
+    this.#store.value.setVolume(0.5);
+  }
+}
+```
+
+**With selector** — returns the selected value and subscribes to changes. Triggers a host update when the selected value changes (using shallow equality).
+
+ts
+
+```
+class PlayButton extends HTMLElement {
+  #playback = new StoreController(this, storeSource, selectPlayback);
+
+  render() {
+    const playback = this.#playback.value;
+    // Re-renders when playback state changes
+  }
+}
+```
+
+### StoreController vs PlayerController vs SnapshotController
+
+`StoreController`
+
+[`PlayerController`](./player-controller.md)
+
+[`SnapshotController`](./snapshot-controller.md)
+
+**Input**
+
+Any store or context
+
+Player store context
+
+`State` container
+
+**Typed to**
+
+Generic store
+
+Player features
+
+Raw state
+
+**Use case**
+
+General-purpose store access
+
+Player UI elements
+
+Low-level state subscription
+
+[`PlayerController`](./player-controller.md) is a typed wrapper around `StoreController` scoped to the player store. For player UI, prefer `PlayerController`. Use `StoreController` when working with a custom store outside the player system.
+
+When you pass a selector, `StoreController` internally creates a [`SnapshotController`](./snapshot-controller.md) on the store’s `$state` container. Without a selector, no subscription is created — you get the store instance for imperative access to actions.
+
+## API Reference
+
+### Without Selector
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`host*`
+
+`StoreControllerHost`
+
+`—`
+
+▸
+
+Description
+
+The host element that owns this controller.
+
+`source*`
+
+`StoreSource<Store>`
+
+`—`
+
+▸
+
+Description
+
+Store instance or context to resolve the store from.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`Result`
+
+### With Selector
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`host*`
+
+`StoreControllerHost`
+
+`—`
+
+▸
+
+Description
+
+The host element that owns this controller.
+
+`source*`
+
+`StoreSource<Store>`
+
+`—`
+
+▸
+
+Description
+
+Store instance or context to resolve the store from.
+
+`selector*`
+
+`Selector<InferStoreState<Store>, Result>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the store state.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`Result`