@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/screen/Fullscreen.d.ts

@@ -0,0 +1,73 @@
+import { ScreenResult } from './ScreenResult';
+/**
+ * The element currently presented fullscreen, or `null` when nothing is.
+ *
+ * Reads the standard `document.fullscreenElement` first and Safari's `webkitFullscreenElement` second. Returns
+ * `null` under SSR.
+ *
+ * @returns The fullscreen element, or `null`.
+ */
+export declare function getFullscreenElement(): Element | null;
+/**
+ * Whether anything is currently presented fullscreen.
+ *
+ * A point-in-time read, not a subscription — `useFullscreen` is the reactive form. Returns `false` under SSR.
+ *
+ * @returns `true` when a fullscreen element is present.
+ */
+export declare function isFullscreen(): boolean;
+/**
+ * Whether the Fullscreen API is present at all.
+ *
+ * Answers presence, not permission: an iframe lacking `allow="fullscreen"` still reports `true` here, and its
+ * request resolves to a non-`ok` status instead. Returns `false` under SSR. See this file's header for why
+ * `document.fullscreenEnabled` is not consulted.
+ *
+ * @returns `true` when a fullscreen request could be attempted.
+ */
+export declare function isFullscreenSupported(): boolean;
+/**
+ * Presents `element` fullscreen, defaulting to the document root.
+ *
+ * CALL THIS FROM A USER GESTURE. Browsers require transient activation, and a call that has lost it — because it
+ * sits outside a click handler, or because an `await` preceded it — resolves to `requires-gesture`, not `failed`.
+ *
+ * Never throws, never rejects.
+ *
+ * @param element The element to present. Defaults to `document.documentElement`.
+ * @returns `ok` once the platform accepts the request, or the classified failure.
+ */
+export declare function enterFullscreen(element?: Element): Promise<ScreenResult>;
+/**
+ * Leaves fullscreen.
+ *
+ * Idempotent: exiting when nothing is fullscreen resolves to `ok` rather than surfacing the `TypeError` browsers
+ * reject that call with. A caller unwinding its own state should not have to check first.
+ *
+ * Never throws, never rejects.
+ *
+ * @returns `ok` once the document is out of fullscreen, or the classified failure.
+ */
+export declare function exitFullscreen(): Promise<ScreenResult>;
+/**
+ * Exits fullscreen when something is presented, enters with `element` otherwise.
+ *
+ * Inherits {@link enterFullscreen}'s gesture requirement on the entering leg. Never throws, never rejects.
+ *
+ * @param element The element to present when entering. Defaults to `document.documentElement`.
+ * @returns The result of whichever leg ran.
+ */
+export declare function toggleFullscreen(element?: Element): Promise<ScreenResult>;
+/**
+ * Subscribes `listener` to fullscreen transitions, returning an unsubscribe.
+ *
+ * Listens on both `fullscreenchange` and `webkitfullscreenchange`, so a browser on either spelling is covered.
+ * A browser firing both invokes `listener` twice per transition — harmless for the snapshot reads this exists to
+ * drive, but do not use it to count transitions.
+ *
+ * Returns a no-op unsubscribe under SSR, so a caller never needs to branch on the environment.
+ *
+ * @param listener Invoked after every fullscreen transition.
+ * @returns A function that removes both listeners.
+ */
+export declare function onFullscreenChange(listener: () => void): () => void;

package/dist/foundation/screen/ScreenEnvironment.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reads `key` off `source`, yielding `undefined` for a non-object, a missing member, or a read that throws.
+ *
+ * The workhorse of this slice: prefixed members (`webkitRequestFullscreen`) are not in the DOM lib's types, and
+ * stubs in tests are partial by design, so nothing may assume a member is present or readable.
+ *
+ * @param source The value to read from — safely accepts `undefined`, `null`, and primitives.
+ * @param key The property name to read.
+ * @returns The member's value, or `undefined` when it is absent or unreadable.
+ */
+export declare function readMember(source: unknown, key: string): unknown;
+/**
+ * Whether `value` is callable — the capability check behind every `*Supported` predicate in this slice.
+ *
+ * Deliberately only a check: call sites cast to their own precise signature before invoking, so this never
+ * becomes a loose way to call an unknown value.
+ *
+ * @param value The value to test.
+ * @returns `true` when `value` is a function.
+ */
+export declare function isFunction(value: unknown): boolean;
+/**
+ * The document, or `undefined` when there is none — SSR, a worker, or any non-DOM host.
+ *
+ * @returns The global `document`, or `undefined`.
+ */
+export declare function getDocument(): Document | undefined;
+/**
+ * The navigator, or `undefined` when there is none.
+ *
+ * Note Node ships a real `globalThis.navigator` with none of the members this slice wants, so a defined
+ * navigator proves nothing on its own — every member is still capability-checked before use.
+ *
+ * @returns The global `navigator`, or `undefined`.
+ */
+export declare function getNavigator(): Navigator | undefined;
+/**
+ * The screen, or `undefined` when there is none.
+ *
+ * @returns The global `screen`, or `undefined`.
+ */
+export declare function getScreen(): Screen | undefined;

package/dist/foundation/screen/ScreenOrientation.d.ts

@@ -0,0 +1,110 @@
+import { ScreenResult } from './ScreenResult';
+/** The concrete orientations the platform reports — what `getOrientation` can return. */
+export declare const ScreenOrientationType: {
+    /** Upright, the device's natural portrait. */
+    readonly PortraitPrimary: "portrait-primary";
+    /** Upside-down portrait. */
+    readonly PortraitSecondary: "portrait-secondary";
+    /** Rotated a quarter turn from natural portrait. */
+    readonly LandscapePrimary: "landscape-primary";
+    /** Rotated the other quarter turn. */
+    readonly LandscapeSecondary: "landscape-secondary";
+};
+/** One of the {@link ScreenOrientationType} values. */
+export type ScreenOrientationType = (typeof ScreenOrientationType)[keyof typeof ScreenOrientationType];
+/** The lock targets the platform accepts — the four concrete orientations plus four relative ones. */
+export declare const ScreenOrientationLock: {
+    /** Any orientation — effectively releases a lock while keeping one nominally set. */
+    readonly Any: "any";
+    /** The device's own natural orientation, whichever that is. */
+    readonly Natural: "natural";
+    /** Either portrait orientation, letting the device flip between them. */
+    readonly Portrait: "portrait";
+    /** Either landscape orientation. */
+    readonly Landscape: "landscape";
+    /** Upright portrait only. */
+    readonly PortraitPrimary: "portrait-primary";
+    /** Upside-down portrait only. */
+    readonly PortraitSecondary: "portrait-secondary";
+    /** One landscape direction only. */
+    readonly LandscapePrimary: "landscape-primary";
+    /** The other landscape direction only. */
+    readonly LandscapeSecondary: "landscape-secondary";
+};
+/** One of the {@link ScreenOrientationLock} values. */
+export type ScreenOrientationLock = (typeof ScreenOrientationLock)[keyof typeof ScreenOrientationLock];
+/**
+ * A {@link ScreenResult} widened with the precondition that only orientation locking has.
+ *
+ * `requires-fullscreen` means the API is present and willing, but the document is not fullscreen — enter
+ * fullscreen and retry. Distinct from `denied` (the platform refused outright) and from `unsupported` (this
+ * device cannot lock at all, which is every desktop browser and all of Safari).
+ */
+export type OrientationLockResult = ScreenResult | {
+    readonly status: 'requires-fullscreen';
+    readonly error: Error;
+};
+/** The `status` discriminant of an {@link OrientationLockResult}. */
+export type OrientationLockStatus = OrientationLockResult['status'];
+/**
+ * The current device orientation, or `null` when it cannot be determined — SSR, or a browser without
+ * `screen.orientation` (iOS before 16.4).
+ *
+ * A point-in-time read; `useOrientation` is the reactive form. An unrecognized value from the platform reads as
+ * `null` rather than being passed through, so the return type is honest.
+ *
+ * @returns The current {@link ScreenOrientationType}, or `null`.
+ */
+export declare function getOrientation(): ScreenOrientationType | null;
+/**
+ * The current orientation angle in degrees (`0`, `90`, `180`, `270`), or `null` when unavailable.
+ *
+ * Relative to the device's natural orientation, so `0` is portrait on a phone and landscape on many tablets —
+ * never infer a shape from the angle alone. Pair it with {@link getOrientation}.
+ *
+ * @returns The angle, or `null`.
+ */
+export declare function getOrientationAngle(): number | null;
+/**
+ * Whether orientation locking is present at all.
+ *
+ * `true` says the method exists, not that it will succeed — a lock outside fullscreen still fails on the devices
+ * that have it. `false` under SSR, on desktop Safari, and on iOS.
+ *
+ * @returns `true` when a lock could be attempted.
+ */
+export declare function isOrientationLockSupported(): boolean;
+/**
+ * Asks the device to hold `orientation`.
+ *
+ * ENTER FULLSCREEN FIRST. Mobile browsers require it, and a call from a normal page resolves to
+ * `requires-fullscreen` — a distinct status precisely because it is fixable, unlike `unsupported`. Desktop
+ * browsers and Safari resolve to `unsupported` no matter what you do.
+ *
+ * Never throws, never rejects.
+ *
+ * @param orientation The lock target — a concrete orientation, or a relative one like `natural`.
+ * @returns `ok` once the device honours the lock, or the classified failure.
+ */
+export declare function lockOrientation(orientation: ScreenOrientationLock): Promise<OrientationLockResult>;
+/**
+ * Releases any orientation lock, letting the device rotate freely again.
+ *
+ * Synchronous, unlike {@link lockOrientation} — the platform's `unlock()` returns nothing and takes effect
+ * immediately. Safe to call when no lock is held. Resolves to `unsupported` rather than `ok` where the API is
+ * absent, so "nothing to unlock" and "cannot unlock" stay distinguishable.
+ *
+ * Never throws.
+ *
+ * @returns `ok` when the lock was released, `unsupported` where the API is absent, `failed` on a throw.
+ */
+export declare function unlockOrientation(): ScreenResult;
+/**
+ * Subscribes `listener` to orientation changes, returning an unsubscribe.
+ *
+ * Returns a no-op unsubscribe where the API is absent, so a caller never branches on the environment.
+ *
+ * @param listener Invoked after every orientation change.
+ * @returns A function that removes the listener.
+ */
+export declare function onOrientationChange(listener: () => void): () => void;

package/dist/foundation/screen/ScreenResult.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The non-success half of {@link ScreenResult}, shared by the value-carrying and void variants.
+ *
+ * - `unsupported` — the API is absent: SSR, an older browser, or a platform that cannot honour the request at
+ *   all. Carries no error because no call was made. Hide the affordance rather than disabling it.
+ * - `denied` — the API exists and the platform refused. A permissions policy, an OS-level block, or a
+ *   precondition the caller cannot satisfy. Not retryable by repeating the same call.
+ * - `requires-gesture` — the call was made outside a user gesture (transient activation). Retryable: move it
+ *   into a `click` / `keydown` handler. Its own status precisely because the fix is mechanical.
+ * - `failed` — anything else, carrying the normalized `Error`.
+ */
+export type ScreenFailure = {
+    readonly status: 'unsupported';
+} | {
+    readonly status: 'denied';
+    readonly error: Error;
+} | {
+    readonly status: 'requires-gesture';
+    readonly error: Error;
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/** The outcome of a screen action that yields nothing on success — entering fullscreen, unlocking orientation. */
+export type ScreenResult = {
+    readonly status: 'ok';
+} | ScreenFailure;
+/**
+ * The outcome of a screen action that yields a `TValue` on success — the wake-lock handle, today's only case.
+ * The failure legs are identical to {@link ScreenResult}'s, so `result.status === 'ok'` narrows to the value and
+ * every other branch reads the same as it does elsewhere in the slice.
+ */
+export type ScreenValueResult<TValue> = {
+    readonly status: 'ok';
+    readonly value: TValue;
+} | ScreenFailure;
+/** The `status` discriminant of a {@link ScreenResult} — for a consumer's own status→copy map. */
+export type ScreenStatus = ScreenResult['status'];

package/dist/foundation/screen/UseFullscreen.d.ts

@@ -0,0 +1,28 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { ScreenResult } from './ScreenResult';
+/** What {@link useFullscreen} returns. */
+export interface FullscreenControls {
+    /** Whether anything is currently presented fullscreen — including a transition this composable did not initiate. */
+    readonly isFullscreen: Readonly<ShallowRef<boolean>>;
+    /** Whether the Fullscreen API is present. `false` under SSR; render the control only once this is `true`. */
+    readonly supported: Readonly<ShallowRef<boolean>>;
+    /** Presents the composable's target fullscreen. Call from a user gesture. Resolves to the result; never throws. */
+    readonly enter: () => Promise<ScreenResult>;
+    /** Leaves fullscreen. Resolves to `ok` when nothing was presented. Never throws. */
+    readonly exit: () => Promise<ScreenResult>;
+    /** Exits when presented, enters otherwise. Call from a user gesture. Never throws. */
+    readonly toggle: () => Promise<ScreenResult>;
+}
+/**
+ * Tracks fullscreen state and exposes the three actions against an optional target.
+ *
+ * Pass `target` to present one element (a video, a canvas, a dashboard panel); omit it to present the whole
+ * document. Takes the element as a ref or getter rather than handing one back, so a `useTemplateRef` drops
+ * straight in — and it is read at call time, so it may still be `null` when the handler is wired up.
+ *
+ * Inherits the module's never-throws contract.
+ *
+ * @param target The element to present. Defaults to `document.documentElement` when omitted or still `null`.
+ * @returns The current state plus the `enter` / `exit` / `toggle` actions.
+ */
+export declare function useFullscreen(target?: MaybeRefOrGetter<Element | null | undefined>): FullscreenControls;

package/dist/foundation/screen/UseOrientation.d.ts

@@ -0,0 +1,28 @@
+import { ShallowRef } from 'vue';
+import { OrientationLockResult, ScreenOrientationLock, ScreenOrientationType } from './ScreenOrientation';
+import { ScreenResult } from './ScreenResult';
+/** What {@link useOrientation} returns. */
+export interface OrientationControls {
+    /** The current device orientation, or `null` under SSR and where `screen.orientation` is absent. */
+    readonly orientation: Readonly<ShallowRef<ScreenOrientationType | null>>;
+    /** The current angle in degrees relative to the device's natural orientation, or `null` when unavailable. */
+    readonly angle: Readonly<ShallowRef<number | null>>;
+    /** Whether locking is present. `false` under SSR, on desktop, and on Safari — hide the control when `false`. */
+    readonly supported: Readonly<ShallowRef<boolean>>;
+    /** Asks the device to hold an orientation. Enter fullscreen first. Resolves to the result; never throws. */
+    readonly lock: (orientation: ScreenOrientationLock) => Promise<OrientationLockResult>;
+    /** Releases the lock. Synchronous, like the platform's own `unlock()`. Never throws. */
+    readonly unlock: () => ScreenResult;
+}
+/**
+ * Tracks the device orientation and exposes the lock actions.
+ *
+ * Use the reported orientation to adapt a layout only where a CSS media query genuinely cannot — the query is
+ * cheaper and needs no JavaScript. The real reason to reach for this composable is `lock` / `unlock`, which have
+ * no CSS equivalent.
+ *
+ * Inherits the module's never-throws contract.
+ *
+ * @returns The current orientation and angle plus the `lock` / `unlock` actions.
+ */
+export declare function useOrientation(): OrientationControls;

package/dist/foundation/screen/UseWakeLock.d.ts

@@ -0,0 +1,18 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { WakeLockKind, WakeLockState } from './WakeLock';
+/**
+ * Holds a screen wake lock for as long as `active` resolves to `true`, re-acquiring it after every visibility
+ * change.
+ *
+ * Drive it from whatever state means "the user is watching": a running timer, a playing video, an open recipe.
+ * Flipping `active` to `false` releases; so does disposing the scope. The lock is re-acquired automatically when
+ * the page returns to visible, which is the behaviour a raw `navigator.wakeLock.request` does not give you.
+ *
+ * Holds a defined `idle` state under SSR and on browsers without the API — check `status === 'unsupported'`
+ * before offering a "keep screen awake" control.
+ *
+ * @param active Whether the lock should be held. A ref or getter is how it flips.
+ * @param type The kind of lock. Defaults to `screen`. Changing it re-acquires.
+ * @returns The current {@link WakeLockState}.
+ */
+export declare function useWakeLock(active: MaybeRefOrGetter<boolean>, type?: MaybeRefOrGetter<WakeLockKind | undefined>): Readonly<ShallowRef<WakeLockState>>;

package/dist/foundation/screen/WakeLock.d.ts

@@ -0,0 +1,79 @@
+import { ScreenStatus, ScreenValueResult } from './ScreenResult';
+/** The kinds of wake lock the platform defines. Only `screen` exists; the spec keeps the axis open. */
+export declare const WakeLockKind: {
+    /** Keeps the display on and undimmed. The only kind any browser implements today. */
+    readonly Screen: "screen";
+};
+/** One of the {@link WakeLockKind} values. */
+export type WakeLockKind = (typeof WakeLockKind)[keyof typeof WakeLockKind];
+/**
+ * A held wake lock. Wraps the platform's `WakeLockSentinel` so that {@link WakeLockHandle.release} is total and
+ * {@link WakeLockHandle.released} reads through to the live sentinel rather than a snapshot taken at request
+ * time — the platform flips that flag on its own when the page is hidden.
+ */
+export interface WakeLockHandle {
+    /** The kind of lock held. */
+    readonly type: WakeLockKind;
+    /** Whether the lock is no longer held — by an explicit release, or by the platform hiding the page. */
+    readonly released: boolean;
+    /** Releases the lock. Safe to call twice, and on an already-released lock. Never throws. */
+    release: () => Promise<void>;
+}
+/** Where a {@link holdWakeLock} sits: `idle` before its first request settles, then the last request's status. */
+export type WakeLockStatus = 'idle' | ScreenStatus;
+/** The observable state of a {@link WakeLockHold}. */
+export interface WakeLockState {
+    /** Whether a lock is held right now. Drops to `false` when the page is hidden, back to `true` on return. */
+    readonly held: boolean;
+    /** The status of the most recent request, or `idle` before the first one settles. */
+    readonly status: WakeLockStatus;
+    /** The error from the most recent non-`ok` request, or `null`. Always `null` for `unsupported`. */
+    readonly error: Error | null;
+}
+/** Tunes a {@link holdWakeLock}. */
+export interface WakeLockHoldOptions {
+    /** The kind of lock to hold. Defaults to `screen`, the only kind implemented. */
+    readonly type?: WakeLockKind;
+    /** Called on every state transition — the seam `useWakeLock` renders from. A throw from it is swallowed. */
+    readonly onChange?: (state: WakeLockState) => void;
+}
+/** A wake lock held across visibility changes until released. */
+export interface WakeLockHold {
+    /** The current state. Re-read it after an `onChange`; it is not reactive on its own. */
+    readonly state: WakeLockState;
+    /** Stops re-acquiring, unsubscribes, and releases any held lock. Idempotent. */
+    release: () => void;
+}
+/**
+ * The state before any request has settled. A module constant, not a fresh literal: `useWakeLock` resets to it
+ * whenever it goes inactive, and a stable identity is what keeps that reset from waking every watcher on it.
+ */
+export declare const IdleWakeLockState: WakeLockState;
+/**
+ * Requests a single wake lock.
+ *
+ * The lock this yields is released by the platform as soon as the page is hidden and is NOT restored on return —
+ * prefer {@link holdWakeLock} unless you genuinely want one attempt. Must be called from an active, visible
+ * document; a hidden one is rejected as `denied`.
+ *
+ * Never throws, never rejects.
+ *
+ * @param type The kind of lock. Defaults to `screen`.
+ * @returns `ok` with the handle, or the classified failure.
+ */
+export declare function requestWakeLock(type?: WakeLockKind): Promise<ScreenValueResult<WakeLockHandle>>;
+/**
+ * Holds a wake lock, re-acquiring it whenever the page returns to visible.
+ *
+ * This is the form a consumer normally wants: the platform drops the lock on every tab switch, notification, and
+ * screen blank, and without the re-acquire the feature quietly stops working after the first one. Starts
+ * requesting immediately and reports each transition through `options.onChange`.
+ *
+ * Call {@link WakeLockHold.release} when done — nothing else ends the cycle.
+ *
+ * Never throws.
+ *
+ * @param options The lock kind and the state-change callback.
+ * @returns The live hold.
+ */
+export declare function holdWakeLock(options?: WakeLockHoldOptions): WakeLockHold;

package/dist/foundation/screen/index.d.ts

@@ -0,0 +1,7 @@
+export { type ScreenResult, type ScreenValueResult, type ScreenFailure, type ScreenStatus, } from './ScreenResult';
+export { enterFullscreen, exitFullscreen, toggleFullscreen, isFullscreen, isFullscreenSupported, getFullscreenElement, onFullscreenChange, } from './Fullscreen';
+export { useFullscreen, type FullscreenControls } from './UseFullscreen';
+export { requestWakeLock, holdWakeLock, WakeLockKind, IdleWakeLockState, type WakeLockHandle, type WakeLockHold, type WakeLockHoldOptions, type WakeLockState, type WakeLockStatus, } from './WakeLock';
+export { useWakeLock } from './UseWakeLock';
+export { lockOrientation, unlockOrientation, getOrientation, getOrientationAngle, isOrientationLockSupported, onOrientationChange, ScreenOrientationType, ScreenOrientationLock, type OrientationLockResult, type OrientationLockStatus, } from './ScreenOrientation';
+export { useOrientation, type OrientationControls } from './UseOrientation';