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

package/docs/reference/tooltip.md

@@ -0,0 +1,547 @@
+# media-tooltip
+
+A tooltip component for displaying contextual labels on hover and focus
+
+## Anatomy
+
+html
+
+```
+<media-tooltip-group>
+  <button commandfor="my-tooltip">Hover me</button>
+  <media-tooltip id="my-tooltip">Label text</media-tooltip>
+</media-tooltip-group>
+```
+
+## Behavior
+
+Displays a short label anchored to a trigger element. Opens after a configurable `delay` (default 600ms) on hover or immediately on focus. Closes when the pointer leaves or focus moves away, with an optional `closeDelay`.
+
+The `side` and `align` props control placement relative to the trigger. Positioning uses CSS Anchor Positioning where supported, with a JavaScript measurement fallback.
+
+The `<media-tooltip>` element is the popup itself. Link it to a trigger using the `commandfor` attribute on any button, pointing to the tooltip’s `id`. The element discovers its trigger automatically and manages open/close state, ARIA attributes, and positioning. Wrap tooltip trigger/popup pairs in `<media-tooltip-group>` to coordinate timing — the group’s `delay`, `close-delay`, and `timeout` attributes control shared timing for all contained tooltips.
+
+## Styling
+
+Use [CSS custom properties](#root-css-custom-properties) for positioning offsets:
+
+css
+
+```
+media-tooltip {
+  --media-tooltip-side-offset: 8px;
+  --media-tooltip-align-offset: 0px;
+}
+```
+
+Style based on open state and transition phases:
+
+css
+
+```
+media-tooltip[data-open] {
+  display: block;
+}
+media-tooltip[data-starting-style] {
+  opacity: 0;
+}
+media-tooltip[data-ending-style] {
+  opacity: 0;
+}
+media-tooltip[data-side="top"] {
+  transform-origin: bottom center;
+}
+media-tooltip[data-side="bottom"] {
+  transform-origin: top center;
+}
+```
+
+## Accessibility
+
+The trigger receives `aria-describedby` pointing to the popup when open. The popup renders with `role="tooltip"` and `popover="manual"`. Tooltips open on focus and close when focus leaves, ensuring keyboard-only users can access the label.
+
+## Examples
+
+### Basic Usage
+
+Hover me Tooltip content
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<div class="demo">
+    <button type="button" commandfor="tooltip-demo" class="trigger">Hover me</button>
+    <media-tooltip id="tooltip-demo" class="media-tooltip">
+        Tooltip content
+    </media-tooltip>
+</div>
+```
+```
+.demo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 24px;
+}
+
+.trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.media-tooltip {
+  --media-tooltip-side-offset: 8px;
+  padding: 4px 10px;
+  font-size: 13px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 6px;
+  backdrop-filter: blur(10px);
+}
+```
+```
+import '@videojs/html/ui/tooltip';
+```
+
+### Grouping
+
+Wrap tooltip trigger/popup pairs in `<media-tooltip-group>` to coordinate timing. The group’s `delay`, `close-delay`, and `timeout` attributes control shared timing for all contained tooltips.
+
+Play Play video Mute Mute audio Fullscreen Enter fullscreen
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<media-tooltip-group class="demo">
+    <button type="button" commandfor="tooltip-play" class="trigger">Play</button>
+    <media-tooltip id="tooltip-play" class="media-tooltip">Play video</media-tooltip>
+
+    <button type="button" commandfor="tooltip-mute" class="trigger">Mute</button>
+    <media-tooltip id="tooltip-mute" class="media-tooltip">Mute audio</media-tooltip>
+
+    <button type="button" commandfor="tooltip-fullscreen" class="trigger">Fullscreen</button>
+    <media-tooltip id="tooltip-fullscreen" class="media-tooltip">Enter fullscreen</media-tooltip>
+</media-tooltip-group>
+```
+```
+.demo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 24px;
+}
+
+.trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  backdrop-filter: blur(10px);
+}
+
+.media-tooltip {
+  --media-tooltip-side-offset: 8px;
+  padding: 4px 10px;
+  font-size: 13px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 6px;
+  backdrop-filter: blur(10px);
+}
+```
+```
+import '@videojs/html/ui/tooltip';
+import '@videojs/html/ui/tooltip-group';
+```
+
+## API Reference
+
+### 
+
+media-tooltip-group
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`closeDelay`
+
+`number`
+
+`—`
+
+▸
+
+Attribute
+
+`close-delay`
+
+Description
+
+Default close delay in ms for tooltips in this group.
+
+`delay`
+
+`number`
+
+`—`
+
+▸
+
+Attribute
+
+`delay`
+
+Description
+
+Default open delay in ms for tooltips in this group.
+
+`timeout`
+
+`number`
+
+`—`
+
+▸
+
+Attribute
+
+`timeout`
+
+Description
+
+Duration in ms after a tooltip closes during which the next tooltip opens instantly.
+
+### 
+
+media-tooltip
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`align`
+
+`'start' | 'center' | 'end'`
+
+`'center'`
+
+▸
+
+Attribute
+
+`align`
+
+Description
+
+Alignment of the tooltip along the trigger's edge.
+
+`closeDelay`
+
+`number`
+
+`0`
+
+▸
+
+Attribute
+
+`close-delay`
+
+Description
+
+Delay in ms before closing after pointer leaves.
+
+`defaultOpen`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`default-open`
+
+Description
+
+Initial open state for uncontrolled usage.
+
+`delay`
+
+`number`
+
+`600`
+
+▸
+
+Attribute
+
+`delay`
+
+Description
+
+Delay in ms before opening on hover.
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`disabled`
+
+Description
+
+When true, the tooltip is disabled and will not open.
+
+`disableHoverablePopup`
+
+`boolean`
+
+`true`
+
+▸
+
+Attribute
+
+`disable-hoverable-popup`
+
+Description
+
+When true, hovering the popup does not keep it open.
+
+`open`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`open`
+
+Description
+
+Controlled open state.
+
+`side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+`'top'`
+
+▸
+
+Attribute
+
+`side`
+
+Description
+
+Which side of the trigger the tooltip appears on.
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`open`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the tooltip is currently visible.
+
+`status`
+
+`'idle' | 'starting' | 'ending'`
+
+▸
+
+Description
+
+Current phase of the transition lifecycle.
+
+`side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+▸
+
+Description
+
+Which side of the trigger the tooltip is positioned on.
+
+`align`
+
+`'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+How the tooltip is aligned relative to the specified side.
+
+`transitionStarting`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the open transition is in progress.
+
+`transitionEnding`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the close transition is in progress.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the tooltip is open.
+
+`data-side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+▸
+
+Description
+
+Indicates which side the tooltip is positioned relative to the trigger.
+
+`data-align`
+
+`'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Indicates how the tooltip is aligned relative to the specified side.
+
+#### CSS custom properties
+
+Variable
+
+Details
+
+`--media-tooltip-side-offset`
+
+▸
+
+Description
+
+Distance between the popup and the trigger along the side axis.
+
+`--media-tooltip-align-offset`
+
+▸
+
+Description
+
+Distance between the popup and the trigger along the alignment axis.
+
+`--media-tooltip-boundary-offset`
+
+▸
+
+Description
+
+Minimum distance between the popup and the positioning boundary.
+
+`--media-tooltip-anchor-width`
+
+▸
+
+Description
+
+The anchor element's width.
+
+`--media-tooltip-anchor-height`
+
+▸
+
+Description
+
+The anchor element's height.
+
+`--media-tooltip-available-width`
+
+▸
+
+Description
+
+Available width between the trigger and the boundary edge.
+
+`--media-tooltip-available-height`
+
+▸
+
+Description
+
+Available height between the trigger and the boundary edge.