use-screen-details

Snapshot a ScreenDetailed into a plain object.


Package	`@vizejs/composable/use-screen-details`
Own the source	`vize lib pull composable:use-screen-details`
Runtime exports	`useScreenDetails`, `placeWindow`, `snapshotScreen`
Gzip budget	2816 B

Usage

import { useScreenDetails, placeWindow, snapshotScreen } from "@vizejs/composable/use-screen-details";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useScreenDetails`	capability	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`
`placeWindow`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—
`snapshotScreen`	system	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—

API

`snapshotScreen`

Snapshot a ScreenDetailed into a plain object.

function snapshotScreen(screen: ScreenSnapshot): ScreenSnapshot

`placeWindow`

Compute absolute window geometry inside a screen's available area. Sizes are clamped to the available area; omitted offsets center the window.

function placeWindow( screen: ScreenArea, placement: WindowPlacementOptions = {}, ): WindowPlacement

`useScreenDetails`

Enumerate and target multiple screens with the Window Management API. isExtended is live from window.screen. request() asks for the window-management permission; once granted, screens and currentScreen stay current through screenschange, currentscreenchange, and per-screen change events. openOnScreen opens a window placed with placeWindow. Listeners are removed when the owning reactive scope stops; outside a scope call stop(). Server rendering: nothing is requested, supported and isExtended are false and screens is empty.

function useScreenDetails(options: UseScreenDetailsOptions = {}): ScreenDetailsControls

const { request, screens, openOnScreen } = useScreenDetails();
await request();
const external = screens.value.find((screen) => !screen.isPrimary);
if (external) openOnScreen("/slides", external, { features: "popup" });

Types

`ScreenArea`

Available (work) area of a screen in multi-screen coordinates.

Member	Type	Description
`availLeft`	`number`	Left edge of the available area.
`availTop`	`number`	Top edge of the available area.
`availWidth`	`number`	Width of the available area.
`availHeight`	`number`	Height of the available area.

`ScreenSnapshot`

Plain snapshot of a ScreenDetailed.

Member	Type	Description
`availLeft`	`number`	Left edge of the available area.
`availTop`	`number`	Top edge of the available area.
`availWidth`	`number`	Width of the available area.
`availHeight`	`number`	Height of the available area.
`label`	`string`	Human-readable label, possibly empty.
`left`	`number`	Left edge in multi-screen coordinates.
`top`	`number`	Top edge in multi-screen coordinates.
`width`	`number`	Full width.
`height`	`number`	Full height.
`devicePixelRatio`	`number`	Device pixel ratio.
`colorDepth`	`number`	Color depth in bits.
`isPrimary`	`boolean`	Whether this is the primary screen.
`isInternal`	`boolean`	Whether this screen is built into the device.

`ScreenDetailedLike`

Minimal ScreenDetailed.

Member	Type	Description
`availLeft`	`number`	Left edge of the available area.
`availTop`	`number`	Top edge of the available area.
`availWidth`	`number`	Width of the available area.
`availHeight`	`number`	Height of the available area.
`label`	`string`	Human-readable label, possibly empty.
`left`	`number`	Left edge in multi-screen coordinates.
`top`	`number`	Top edge in multi-screen coordinates.
`width`	`number`	Full width.
`height`	`number`	Full height.
`devicePixelRatio`	`number`	Device pixel ratio.
`colorDepth`	`number`	Color depth in bits.
`isPrimary`	`boolean`	Whether this is the primary screen.
`isInternal`	`boolean`	Whether this screen is built into the device.

`ScreenDetailsLike`

Minimal ScreenDetails.

Member	Type	Description
`screens`	`readonly ScreenDetailedLike[]`	Every connected screen.
`currentScreen`	`ScreenDetailedLike`	Screen hosting the current window.

`ScreenDetailsHost`

Capabilities used by useScreenDetails.

Member	Type	Description
`getScreenDetails`?	`() => Promise<ScreenDetailsLike>`	Window Management entry point (permission-gated).
`screen`?	`object \| null`	`window.screen`. Its `isExtended` flag is read and, when it is an `EventTarget`, its `change` event refreshes the flag.
`open`?	`(url: string, target: string, features: string) => Window \| null`	`window.open`, used by `openOnScreen`.

`UseScreenDetailsOptions`

Options for useScreenDetails.

Member	Type	Description
`host`?	`MaybeRefOrGetter<ScreenDetailsHost \| null \| undefined>`	Window Management capability for alternate runtimes and tests.

`WindowPlacementOptions`

Desired window geometry relative to a screen's available area.

Member	Type	Description
`width`?	`number`	Window width, clamped to the available width.
`height`?	`number`	Window height, clamped to the available height.
`left`?	`number`	Offset from the available area's left edge.
`top`?	`number`	Offset from the available area's top edge.

`WindowPlacement`

Absolute window geometry for window.open features or moveTo/resizeTo.

Member	Type	Description
`left`	`number`	Absolute left.
`top`	`number`	Absolute top.
`width`	`number`	Width.
`height`	`number`	Height.

`OpenOnScreenOptions`

Options of ScreenDetailsControls.openOnScreen.

Member	Type	Description
`width`?	`number`	Window width, clamped to the available width.
`height`?	`number`	Window height, clamped to the available height.
`left`?	`number`	Offset from the available area's left edge.
`top`?	`number`	Offset from the available area's top edge.
`target`?	`string`	Browsing context name.
`features`?	`string`	Extra comma-separated window features, for example `"popup"`.

`ScreenDetailsControls`

Reactive state and actions returned by useScreenDetails.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Window Management API is available.
`isExtended`	`Readonly<Ref<boolean>>`	Whether the window spans a multi-screen setup (`screen.isExtended`).
`screens`	`Readonly<ShallowRef<readonly ScreenSnapshot[]>>`	Snapshots of every screen, empty until `request` succeeds.
`currentScreen`	`Readonly<ShallowRef<ScreenSnapshot \| undefined>>`	Snapshot of the current screen, once granted.
`pending`	`Readonly<Ref<boolean>>`	Whether `request` is in progress.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent request failure, cleared on success.
`request`	`() => Promise<ScreenDetailsResult>`	Request screen details (prompts for the window-management permission).
`openOnScreen`	`( url: string, screen: ScreenArea, options?: OpenOnScreenOptions, ) => Window \| null`	Open a window placed on `screen`.
`stop`	`() => void`	Remove every listener. Idempotent.