@fusion.dev/helix-headless 0.211.0 → 0.212.0

package/types/svelte.d.ts

@@ -66,6 +66,7 @@ declare module 'svelte/elements' {
     'helix-headless-date-picker': Helix<'helix-headless-date-picker'>
     'helix-headless-description-list-item': Helix<'helix-headless-description-list-item'>
     'helix-headless-description-list': Helix<'helix-headless-description-list'>
+    'helix-headless-device-screen': Helix<'helix-headless-device-screen'>
     'helix-headless-dialog': Helix<'helix-headless-dialog'>
     'helix-headless-divider': Helix<'helix-headless-divider'>
     'helix-headless-donut-chart': Helix<'helix-headless-donut-chart'>

package/types/vue.d.ts

@@ -26,6 +26,14 @@ import type {
   HelixCopyErrorEvent,
   HelixCopyEvent,
   HelixCreateEvent,
+  HelixDeviceButtonEvent,
+  HelixDeviceKeyEvent,
+  HelixDeviceScreenshotEvent,
+  HelixDeviceScrollEvent,
+  HelixDeviceSwipeEvent,
+  HelixDeviceTapEvent,
+  HelixDeviceTextEvent,
+  HelixDeviceTouchEvent,
   HelixDismissEvent,
   HelixEndEvent,
   HelixExpandEvent,
@@ -76,6 +84,7 @@ import type {
   HelixHeadlessDatePicker,
   HelixHeadlessDescriptionList,
   HelixHeadlessDescriptionListItem,
+  HelixHeadlessDeviceScreen,
   HelixHeadlessDialog,
   HelixHeadlessDivider,
   HelixHeadlessDonutChart,
@@ -6240,6 +6249,192 @@ makes the list a named group. */
 
 export type HelixHeadlessDescriptionListVueEvents = {};
 
+/** `HelixHeadlessDeviceScreen` component event */
+export type HelixHeadlessDeviceScreenElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessDeviceScreen,
+  E
+>;
+/** `helix-device-button` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceButtonElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceButtonEvent>;
+/** `helix-device-key` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceKeyElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceKeyEvent>;
+/** `helix-device-screenshot` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceScreenshotElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceScreenshotEvent>;
+/** `helix-device-scroll` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceScrollElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceScrollEvent>;
+/** `helix-device-swipe` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceSwipeElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceSwipeEvent>;
+/** `helix-device-tap` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceTapElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceTapEvent>;
+/** `helix-device-text` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceTextElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceTextEvent>;
+/** `helix-device-touch` event type */
+export type HelixHeadlessDeviceScreenHelixDeviceTouchElementEvent =
+  HelixHeadlessDeviceScreenElementEvent<HelixDeviceTouchEvent>;
+
+export type HelixHeadlessDeviceScreenVueProps = {
+  /** The Back button's label. */
+  "back-label"?: (HelixHeadlessDeviceScreen["backLabel"]) | undefined;
+  /** The Back button's label. */
+  backLabel?: (HelixHeadlessDeviceScreen["backLabel"]) | undefined;
+  /** Which hardware buttons to draw, as a list: `back`, `home`, `recents`,
+`power`, `volume`, `rotate`, `screenshot`, and `fullscreen`, or `none`.
+They are drawn in that order whatever order the list is in. Absent is
+`home screenshot`. `volume` draws Volume up and Volume down, and `rotate`
+draws Rotate left and Rotate right. */
+  controls?: (HelixHeadlessDeviceScreen["controls"]) | undefined;
+  /** The name of the toolbar of hardware buttons, read by screen readers. */
+  "controls-label"?: (HelixHeadlessDeviceScreen["controlsLabel"]) | undefined;
+  /** The name of the toolbar of hardware buttons, read by screen readers. */
+  controlsLabel?: (HelixHeadlessDeviceScreen["controlsLabel"]) | undefined;
+  /** Which side of the device the hardware buttons sit on. Absent and `top`
+are a row above it, `bottom` is a row below it, and `start` and `end` are
+a column beside it, as the Android Emulator draws its toolbar. The words
+are sides, as Carousel's are, and not the corners a map's controls take. */
+  "controls-placement"?: (HelixHeadlessDeviceScreen["controlsPlacement"]) | undefined;
+  /** Which side of the device the hardware buttons sit on. Absent and `top`
+are a row above it, `bottom` is a row below it, and `start` and `end` are
+a column beside it, as the Android Emulator draws its toolbar. The words
+are sides, as Carousel's are, and not the corners a map's controls take. */
+  controlsPlacement?: (HelixHeadlessDeviceScreen["controlsPlacement"]) | undefined;
+  /** The screen's name where `label` is empty and the host has no `aria-label`. */
+  "fallback-label"?: (HelixHeadlessDeviceScreen["fallbackLabel"]) | undefined;
+  /** The screen's name where `label` is empty and the host has no `aria-label`. */
+  fallbackLabel?: (HelixHeadlessDeviceScreen["fallbackLabel"]) | undefined;
+  /** Also sends key presses with Control, Command, or Alt held, which are left
+to the browser otherwise. For an app that owns its window. Command or
+Control with V pastes either way. */
+  "forward-shortcuts"?: (HelixHeadlessDeviceScreen["forwardShortcuts"]) | undefined;
+  /** Also sends key presses with Control, Command, or Alt held, which are left
+to the browser otherwise. For an app that owns its window. Command or
+Control with V pastes either way. */
+  forwardShortcuts?: (HelixHeadlessDeviceScreen["forwardShortcuts"]) | undefined;
+  /** The fullscreen button's label. */
+  "fullscreen-label"?: (HelixHeadlessDeviceScreen["fullscreenLabel"]) | undefined;
+  /** The fullscreen button's label. */
+  fullscreenLabel?: (HelixHeadlessDeviceScreen["fullscreenLabel"]) | undefined;
+  /** The Home button's label. */
+  "home-label"?: (HelixHeadlessDeviceScreen["homeLabel"]) | undefined;
+  /** The Home button's label. */
+  homeLabel?: (HelixHeadlessDeviceScreen["homeLabel"]) | undefined;
+  /** What a screen reader says about the keys when it reaches the screen,
+after its name. */
+  "keys-hint-label"?: (HelixHeadlessDeviceScreen["keysHintLabel"]) | undefined;
+  /** What a screen reader says about the keys when it reaches the screen,
+after its name. */
+  keysHintLabel?: (HelixHeadlessDeviceScreen["keysHintLabel"]) | undefined;
+  /** The device's name, read by screen readers as the screen's name, such as
+"iPhone 17 Pro". Name each device on a page with several. Required. */
+  label?: (HelixHeadlessDeviceScreen["label"]) | undefined;
+  /** Shows the `loading` slot over the screen, for a stream that is starting
+or has stopped. Screen readers hear `loading-label`. */
+  loading?: (HelixHeadlessDeviceScreen["loading"]) | undefined;
+  /** What the screen shows and screen readers hear while `loading` is set and nothing is in the `loading` slot. */
+  "loading-label"?: (HelixHeadlessDeviceScreen["loadingLabel"]) | undefined;
+  /** What the screen shows and screen readers hear while `loading` is set and nothing is in the `loading` slot. */
+  loadingLabel?: (HelixHeadlessDeviceScreen["loadingLabel"]) | undefined;
+  /** The Power button's label. */
+  "power-label"?: (HelixHeadlessDeviceScreen["powerLabel"]) | undefined;
+  /** The Power button's label. */
+  powerLabel?: (HelixHeadlessDeviceScreen["powerLabel"]) | undefined;
+  /** Shows the screen and sends nothing: no touches, scrolls, keys, or button
+presses. The screen is then a picture, out of the tab order, and the
+hardware buttons are off but for screenshot and fullscreen. Buttons of
+your own in the `controls` slot are yours to turn off. */
+  readonly?: (HelixHeadlessDeviceScreen["readonly"]) | undefined;
+  /** The Recent apps button's label. */
+  "recents-label"?: (HelixHeadlessDeviceScreen["recentsLabel"]) | undefined;
+  /** The Recent apps button's label. */
+  recentsLabel?: (HelixHeadlessDeviceScreen["recentsLabel"]) | undefined;
+  /** What a screen reader calls the screen in place of its role, after its
+name: "iPhone 17 Pro, screen". Empty leaves the role. */
+  "role-label"?: (HelixHeadlessDeviceScreen["roleLabel"]) | undefined;
+  /** What a screen reader calls the screen in place of its role, after its
+name: "iPhone 17 Pro, screen". Empty leaves the role. */
+  roleLabel?: (HelixHeadlessDeviceScreen["roleLabel"]) | undefined;
+  /** The Rotate left button's label. */
+  "rotate-left-label"?: (HelixHeadlessDeviceScreen["rotateLeftLabel"]) | undefined;
+  /** The Rotate left button's label. */
+  rotateLeftLabel?: (HelixHeadlessDeviceScreen["rotateLeftLabel"]) | undefined;
+  /** The Rotate right button's label. */
+  "rotate-right-label"?: (HelixHeadlessDeviceScreen["rotateRightLabel"]) | undefined;
+  /** The Rotate right button's label. */
+  rotateRightLabel?: (HelixHeadlessDeviceScreen["rotateRightLabel"]) | undefined;
+  /** How far to turn the picture clockwise, in degrees: `90`, `180`, or `270`.
+For a source that sends frames in the device's natural orientation while
+the device is turned. Every point is turned back, so events stay in the
+device's own orientation. A source whose frames turn with the device
+needs none. */
+  rotation?: (HelixHeadlessDeviceScreen["rotation"]) | undefined;
+  /** The screen's height in the units your device takes input in: points for
+the iOS Simulator, pixels for an Android device. Set with `screen-width`.
+Set alone, the width follows the stream's shape, and with neither, both
+are the stream's own size in pixels. */
+  "screen-height"?: (HelixHeadlessDeviceScreen["screenHeight"] | `${number}`) | undefined;
+  /** The screen's height in the units your device takes input in: points for
+the iOS Simulator, pixels for an Android device. Set with `screen-width`.
+Set alone, the width follows the stream's shape, and with neither, both
+are the stream's own size in pixels. */
+  screenHeight?: (HelixHeadlessDeviceScreen["screenHeight"]) | undefined;
+  /** The screenshot button's label. */
+  "screenshot-label"?: (HelixHeadlessDeviceScreen["screenshotLabel"]) | undefined;
+  /** The screenshot button's label. */
+  screenshotLabel?: (HelixHeadlessDeviceScreen["screenshotLabel"]) | undefined;
+  /** The screen's width in the units your device takes input in, as
+`screen-height` is. Set alone, the height follows the stream's shape. */
+  "screen-width"?: (HelixHeadlessDeviceScreen["screenWidth"] | `${number}`) | undefined;
+  /** The screen's width in the units your device takes input in, as
+`screen-height` is. Set alone, the height follows the stream's shape. */
+  screenWidth?: (HelixHeadlessDeviceScreen["screenWidth"]) | undefined;
+  /** The screen's outline. Absent is a rectangle with rounded corners;
+`square` has square corners, as on a phone with a Home button or a
+television, and `circle` is round, as on a round watch, and takes
+touches inside the circle only. */
+  shape?: (HelixHeadlessDeviceScreen["shape"]) | undefined;
+  /** Draws a ring under each finger on the screen, as the iOS Simulator's
+Show single touches does. Rings from `showTap()` and `showSwipe()` are
+drawn either way. */
+  "show-touches"?: (HelixHeadlessDeviceScreen["showTouches"]) | undefined;
+  /** Draws a ring under each finger on the screen, as the iOS Simulator's
+Show single touches does. Rings from `showTap()` and `showSwipe()` are
+drawn either way. */
+  showTouches?: (HelixHeadlessDeviceScreen["showTouches"]) | undefined;
+  /** The Volume down button's label. */
+  "volume-down-label"?: (HelixHeadlessDeviceScreen["volumeDownLabel"]) | undefined;
+  /** The Volume down button's label. */
+  volumeDownLabel?: (HelixHeadlessDeviceScreen["volumeDownLabel"]) | undefined;
+  /** The Volume up button's label. */
+  "volume-up-label"?: (HelixHeadlessDeviceScreen["volumeUpLabel"]) | undefined;
+  /** The Volume up button's label. */
+  volumeUpLabel?: (HelixHeadlessDeviceScreen["volumeUpLabel"]) | undefined;
+};
+
+export type HelixHeadlessDeviceScreenVueEvents = {
+  /** A hardware button was pressed, with how long it was held. Press it on the device in response. */
+  "helix-device-button": HelixHeadlessDeviceScreenHelixDeviceButtonElementEvent;
+  /** A key went down or came up while the screen had focus. Press or release it on the device in response. */
+  "helix-device-key": HelixHeadlessDeviceScreenHelixDeviceKeyElementEvent;
+  /** A screenshot was asked for. Take one in response. */
+  "helix-device-screenshot": HelixHeadlessDeviceScreenHelixDeviceScreenshotElementEvent;
+  /** A wheel or a trackpad scrolled over the screen. Scroll the device in response. */
+  "helix-device-scroll": HelixHeadlessDeviceScreenHelixDeviceScrollElementEvent;
+  /** One finger moved across the screen and lifted. Swipe the device in response. */
+  "helix-device-swipe": HelixHeadlessDeviceScreenHelixDeviceSwipeElementEvent;
+  /** One finger touched the screen and lifted near where it landed. Tap the device in response. */
+  "helix-device-tap": HelixHeadlessDeviceScreenHelixDeviceTapElementEvent;
+  /** Text was pasted into the screen. Type it on the device in response. */
+  "helix-device-text": HelixHeadlessDeviceScreenHelixDeviceTextElementEvent;
+  /** A finger landed, moved, lifted, or was taken away. Touch the device in response. */
+  "helix-device-touch": HelixHeadlessDeviceScreenHelixDeviceTouchElementEvent;
+};
+
 /** `HelixHeadlessDialog` component event */
 export type HelixHeadlessDialogElementEvent<E = Event> = TypedEvent<
   HelixHeadlessDialog,
@@ -20593,6 +20788,20 @@ export type CustomCssProperties = {
   "--data-table-template"?: (string) | undefined;
   /** How many month columns are drawn, capped at two. `--date-picker-columns` overrides it. */
   "--date-picker-column-count"?: (string) | undefined;
+  /** The drawn screen's width divided by its height, turned by `rotation`, as a number. Written by the frame once the screen's size is known. */
+  "--device-screen-ratio"?: (string) | undefined;
+  /** How far the picture is turned, as an angle. The frame writes it from `rotation`. */
+  "--device-screen-rotation"?: (string) | undefined;
+  /** How long a swipe's ring takes to travel, as a time. Written on each ring from `showSwipe()`. */
+  "--device-screen-touch-duration"?: (string) | undefined;
+  /** Where a swipe's ring travels to, across the screen, as a percentage. Written on each ring from `showSwipe()`. */
+  "--device-screen-touch-to-x"?: (string) | undefined;
+  /** Where a swipe's ring travels to, down the screen, as a percentage. Written on each ring from `showSwipe()`. */
+  "--device-screen-touch-to-y"?: (string) | undefined;
+  /** Where a ring is, across the screen, as a percentage. Written on each ring. */
+  "--device-screen-touch-x"?: (string) | undefined;
+  /** Where a ring is, down the screen, as a percentage. Written on each ring. */
+  "--device-screen-touch-y"?: (string) | undefined;
   /** How thick the ring is drawn, derived from `hole`. */
   "--donut-chart-stroke"?: (string) | undefined;
   /** How far a swipe, or a snap point, has moved the panel across, in pixels, toward the right. */
@@ -21069,6 +21278,12 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessDescriptionListVueProps,
     HelixHeadlessDescriptionListVueEvents
   >;
+  /** Shows the screen of a phone, a tablet, or a watch, such as the iOS Simulator or the Android Emulator, and turns what you do on it into events. Helix does not connect to the device. Put the element that draws the stream inside: a '<video>' fed by WebRTC or Media Source, an '<img>' showing an MJPEG stream, or a '<canvas>' you draw decoded frames on. The frame gives the screen the device's shape and stretches the element to fill it.  Set 'screen-width' and 'screen-height' to the screen's size in the units your device takes input in: points for the iOS Simulator, and pixels for an Android device. Every point an event carries is in those units, beside the 'width' and 'height' it is measured against. Without them, the frame reads the stream's own size in pixels.  **Touches.** Listen in one of two ways, and not both, or the device moves twice: - 'helix-device-touch' for each finger as it lands, moves, and lifts, for a   source that takes live touches. A drag and a pinch need it. - 'helix-device-tap' and 'helix-device-swipe' once the finger lifts, for a   source that takes whole gestures. A long press is a tap with a long   'duration'.  Alt, or Option on a Mac, with a drag sends two touches mirrored about the middle of the screen, for a pinch or a turn, as the iOS Simulator does. A wheel or a trackpad over the screen sends 'helix-device-scroll'.  **Keyboard.** Press Tab to reach the screen, or press the screen. While it has focus:  | Key | What it does | |---|---| | Any key | Sends 'helix-device-key' as it goes down, and again as it comes up. | | Tab, Shift with Tab | Moves focus on from the screen. Never sent. | | Control, Command, or Alt with a key | Left to the browser, unless 'forward-shortcuts' is set. | | Command or Control with V | Sends the clipboard's text as 'helix-device-text'. |  A key still held when focus leaves is sent as released. The screen has the 'application' role, so a screen reader passes every key to it, and its description says how to leave.  **Buttons.** 'controls' names the hardware buttons to draw: 'back', 'home', 'recents', 'power', 'volume', 'rotate', 'screenshot', and 'fullscreen', 'home screenshot' by default. Each sends 'helix-device-button' with how long it was held, and the screenshot button sends 'helix-device-screenshot'. 'press()' and 'screenshot()' do the same from a script. Put buttons of your own in the 'controls' slot, and they join the row. The row is one tab stop, and the arrow keys move along it, or Up and Down in a column.  Set 'rotation' where your source sends frames in the device's natural orientation while the device is turned: the frame turns the picture, and turns every point back. Set 'readonly' to show the screen and send nothing, such as while an agent drives the device. The screen is then a picture, and 'showTap()' and 'showSwipe()' mark where the agent touched it. */
+  "helix-headless-device-screen": DefineCustomElement<
+    HelixHeadlessDeviceScreen,
+    HelixHeadlessDeviceScreenVueProps,
+    HelixHeadlessDeviceScreenVueEvents
+  >;
   /** Renders a native '<dialog>' opened with 'showModal()'. The platform provides:  - the top layer, so the dialog is above everything whatever the 'z-index' - a backdrop - closing with Escape - an inert page behind the dialog, unreachable by pointer, keyboard, or   virtual cursor  The dialog adds one thing to those: 'Tab' from its last control goes to its first, and 'Shift+Tab' from its first to its last. A native modal lets 'Tab' past its last control out to the browser's own controls.  'open' calls 'showModal()', and every way the dialog closes goes through 'requestOpen'. A native dialog closes three ways: the property, Escape, and a '<form method="dialog">' submit. Routing all three through 'requestOpen' keeps your state in step, so the dialog never closes while your state still says it is open, which would leave it impossible to reopen.  The dialog's name is 'label' when you set it. Otherwise it is the heading in the 'header' slot, or the elements an 'aria-labelledby' on the host names, and 'fallback-label' where nothing names it. While it is open, the page behind it does not scroll.  The dialog is described by the words at the start of its body: the elements in the default slot before the first one that is or holds a control. A question above a form describes the dialog, and the form does not. A Helix component that draws words and no control, such as 'Text', counts as words. An 'aria-describedby' on the host replaces it.  Set 'alert' for a dialog that interrupts to ask for an answer, such as a confirmation before a deletion. It is an 'alertdialog', which a screen reader announces with its description as it opens. Set 'dismissible' to draw a close control, labeled by 'dismiss-label'.  **Keyboard.** Opening moves focus to the first control in the dialog.  | Key | What it does | |---|---| | Tab, Shift+Tab | Moves through the controls in the dialog, from the last round to the first and from the first round to the last. | | Escape | Asks to close the dialog. A 'helix-before-close' listener can refuse, and 'persistent' or 'closedby="none"' keeps it open. | | Enter, Space | On the close control, closes the dialog. |  Closing puts focus back on the element that had it before the dialog opened. */
   "helix-headless-dialog": DefineCustomElement<
     HelixHeadlessDialog,

package/types/words.d.ts

@@ -1461,6 +1461,100 @@ declare module '@fusion.dev/helix-core' {
        */
       yearViewLabel: Message
     }
+    'helix-device-screen': {
+      /**
+       * The Back button's label.
+       *
+       * English: `Back`
+       */
+      backLabel: Message
+      /**
+       * The name of the toolbar of hardware buttons, read by screen readers.
+       *
+       * English: `Device controls`
+       */
+      controlsLabel: Message
+      /**
+       * The screen's name where `label` is empty and the host has no `aria-label`.
+       *
+       * English: `Device`
+       */
+      fallbackLabel: Message
+      /**
+       * The fullscreen button's label.
+       *
+       * English: `Fill the screen`
+       */
+      fullscreenLabel: Message
+      /**
+       * The Home button's label.
+       *
+       * English: `Home`
+       */
+      homeLabel: Message
+      /**
+       * What a screen reader says about the keys when it reaches the screen,
+       * after its name.
+       *
+       * English: `Keys you press go to the device. Press Tab to leave the screen.`
+       */
+      keysHintLabel: Message
+      /**
+       * What the screen shows and screen readers hear while `loading` is set and nothing is in the `loading` slot.
+       *
+       * English: `Connecting to the device`
+       */
+      loadingLabel: Message
+      /**
+       * The Power button's label.
+       *
+       * English: `Power`
+       */
+      powerLabel: Message
+      /**
+       * The Recent apps button's label.
+       *
+       * English: `Recent apps`
+       */
+      recentsLabel: Message
+      /**
+       * What a screen reader calls the screen in place of its role, after its
+       * name: "iPhone 17 Pro, screen". Empty leaves the role.
+       *
+       * English: `screen`
+       */
+      roleLabel: Message
+      /**
+       * The Rotate left button's label.
+       *
+       * English: `Rotate left`
+       */
+      rotateLeftLabel: Message
+      /**
+       * The Rotate right button's label.
+       *
+       * English: `Rotate right`
+       */
+      rotateRightLabel: Message
+      /**
+       * The screenshot button's label.
+       *
+       * English: `Take a screenshot`
+       */
+      screenshotLabel: Message
+      /**
+       * The Volume down button's label.
+       *
+       * English: `Volume down`
+       */
+      volumeDownLabel: Message
+      /**
+       * The Volume up button's label.
+       *
+       * English: `Volume up`
+       */
+      volumeUpLabel: Message
+    }
     'helix-dialog': {
       /**
        * The close control's accessible name. Translate it with the rest of your