native-fn 1.3.0 → 1.3.2

package/README.md

@@ -51,6 +51,8 @@ yarn add native-fn
     - [paste](#clipboard-paste)
 - **[dimension](#dimension)**
     - [value](#dimension-value)
+    - [screenOrientation](#dimension-screenorientation)
+    - [deviceOrientation](#dimension-deviceorientation)
     - [environment](#dimension-environment)
     - [onChange](#dimension-onchange)
 - **[fullscreen](#fullscreen)**
@@ -515,7 +517,7 @@ Promise<string>
 
 ## dimension
 
-[`value`](#dimension-value) · [`environment`](#dimension-environment) · [`onChange`](#dimension-onchange)
+[`value`](#dimension-value) · [`screenOrientation`](#dimension-screenorientation) · [`deviceOrientation`](#dimension-deviceorientation) · [`environment`](#dimension-environment) · [`onChange`](#dimension-onchange)
 
 <h3 id="dimension-value"><code>dimension.value</code></h3>
 
@@ -525,19 +527,15 @@ Promise<string>
 get value(): Dimensions
 ```
 
-Returns current viewport dimensions, device pixel ratio, and orientation.
+Returns current viewport dimensions, device pixel ratio.
 
 **Example**
 
 ```ts
-const { innerWidth, innerHeight, outerWidth, outerHeight, scale, orientation } = Native.dimension.value;
+const { innerWidth, innerHeight, outerWidth, outerHeight, scale } = Native.dimension.value;
 
 console.log(innerWidth, innerHeight); // visible viewport size
 console.log(scale);                   // device pixel ratio e.g. 2, 3
-
-if (orientation === Orientation.Portrait) {
-    console.log('Portrait mode');
-}
 ```
 
 **Returns**
@@ -549,21 +547,140 @@ Dimensions
 
 ```ts
 interface Dimensions {
-    outerWidth:  number;
-    outerHeight: number;
-    innerWidth:  number;
-    innerHeight: number;
-    scale:       number;
-    orientation: Orientation;
+    readonly outerWidth:  number;
+    readonly outerHeight: number;
+    readonly innerWidth:  number;
+    readonly innerHeight: number;
+    readonly scale:       number;
+}
+```
+
+---
+
+<h3 id="dimension-screenorientation"><code>dimension.screenOrientation</code></h3>
+
+**Signature**
+
+```ts
+screenOrientation: ScreenOrientationInstance
+```
+
+Provides access to the current screen orientation and subscribes to its changes.
+
+**Example**
+
+```ts
+// Check support
+if (Native.dimension.screenOrientation.supported) {
+    const orientation = Native.dimension.screenOrientation.value;
+    console.log(orientation); // e.g. Orientation.PortraitPrimary
+}
+
+// Subscribe to orientation changes
+const unsubscribe = Native.dimension.screenOrientation.onChange((orientation) => {
+    console.log(orientation); // Orientation.LandscapePrimary, etc.
+});
+
+unsubscribe();
+```
+
+**Returns**
+
+```ts
+ScreenOrientationInstance
+```
+
+
+```ts
+interface ScreenOrientationInstance {
+    get supported(): boolean;
+
+    readonly value: Orientation;
+
+    onChange(listener: (value: Orientation) => void, options?: AddEventListenerOptions): () => void;
 }
 
 enum Orientation {
-    Portrait  = 'portrait',
-    Landscape = 'landscape',
-    Unknown   = 'unknown',
+    PortraitPrimary = 'portrait-primary',
+    PortraitSecondary = 'portrait-secondary',
+    LandscapePrimary = 'landscape-primary',
+    LandscapeSecondary = 'landscape-secondary',
+}
+```
+
+**Throws**
+
+```ts
+throw new NotSupportedError // Thrown when screen.orientation, window.orientation, and the orientation media query are all unsupported'
+```
+
+---
+
+<h3 id="dimension-deviceorientation"><code>dimension.deviceOrientation</code></h3>
+
+**Signature**
+
+```ts
+deviceOrientation: DeviceOrientationInstance
+```
+
+Provides access to the physical device orientation (alpha, beta, gamma) via the DeviceOrientationEvent API. On iOS 13+, permission must be explicitly granted by the user.
+
+**Example**
+
+```ts
+// Check support
+if (Native.dimension.deviceOrientation.supported) {
+
+    // Get current value (triggers permission prompt on iOS if needed)
+    const { alpha, beta, gamma, absolute } = await Native.dimension.deviceOrientation.value;
+    console.log(alpha, beta, gamma); // rotation angles in degrees
+
+    // Subscribe to real-time orientation changes
+    const unsubscribe = Native.dimension.deviceOrientation.onChange((value) => {
+        console.log(value.alpha);    // Z-axis rotation: 0 ~ 360
+        console.log(value.beta);     // X-axis tilt: -180 ~ 180
+        console.log(value.gamma);    // Y-axis tilt: -90 ~ 90
+        console.log(value.absolute); // true if relative to Earth's coordinate frame
+    });
+
+    unsubscribe();
 }
 ```
 
+**Returns**
+
+```ts
+DeviceOrientationInstance
+```
+
+
+```ts
+interface DeviceOrientationInstance {
+    get supported(): boolean;
+
+    readonly value: Promise<DeviceOrientationValue>;
+
+    onChange(listener: (value: DeviceOrientationValue) => void, options?: AddEventListenerOptions): () => void;
+}
+
+interface DeviceOrientationValue {
+    readonly alpha:    number | null; // Z-axis rotation (0–360)
+    readonly beta:     number | null; // X-axis tilt (-180–180)
+    readonly gamma:    number | null; // Y-axis tilt (-90–90)
+    readonly absolute: boolean;       // Earth-relative if true
+}
+```
+
+**Throws**
+
+```ts
+throw new NotSupportedError // Thrown when window.DeviceOrientationEvent is not available in the current environment.
+```
+```ts
+throw new PermissionNotGrantedError // Thrown on iOS 13+ when the user denies the deviceorientation permission request.
+```
+
 ---
 
 <h3 id="dimension-environment"><code>dimension.environment</code></h3>
@@ -650,14 +767,13 @@ interface SegmentsObserver {
 onChange(listener: (dimension: Dimensions) => void, options?: AddEventListenerOptions): () => void
 ```
 
-Subscribes to viewport dimension and orientation changes.
+Subscribes to viewport dimension change.
 
 **Example**
 
 ```ts
 const unsubscribe = Native.dimension.onChange((dimension) => {
     console.log(dimension.innerWidth, dimension.innerHeight);
-    console.log(dimension.orientation); // 'portrait' | 'landscape'
 });
 
 unsubscribe();
@@ -1913,12 +2029,14 @@ Promise<PermissionState>
 
 ```ts
 enum PermissionType {
-    Notification  = 'notifications',
-    Geolocation   = 'geolocation',
-    Camera        = 'camera',
-    ClipboardRead = 'clipboard-read',
-    Microphone    = 'microphone',
-    MIDI          = 'midi',
+    Notification      = 'notifications',
+    Geolocation       = 'geolocation',
+    Camera            = 'camera',
+    ClipboardRead     = 'clipboard-read',
+    Microphone        = 'microphone',
+    MIDI              = 'midi',
+    DeviceOrientation = 'device-orientation',
+    DeviceMotion      = 'device-motion',
 }
 
 enum PermissionState {
@@ -2021,7 +2139,7 @@ Returns the video element currently in Picture-in-Picture, or null if not active
 
 ```ts
 const el = Native.pip.element;
- 
+
 if (el !== null) {
     console.log(el.src); // currently PiP video source
 }
@@ -2104,7 +2222,7 @@ flowchart TD
 ```ts
 // Default: first video element
 await Native.pip.request();
- 
+
 // Specific video element
 await Native.pip.request(document.querySelector('video#player'));
 ```
@@ -2201,7 +2319,7 @@ Toggles Picture-in-Picture for a video element.
 ```ts
 // Default: first video element
 await Native.pip.toggle();
- 
+
 // Specific video element
 await Native.pip.toggle(document.querySelector('video#player'));
 ```
@@ -2239,7 +2357,7 @@ throw new InvalidStateError // PiP transition already in progress
 
 ```ts
 onChange(listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void
-onChange(target: HTMLVideoElement, listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void
+    onChange(target: HTMLVideoElement, listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void
 ```
 
 Subscribes to Picture-in-Picture state changes.
@@ -2252,7 +2370,7 @@ const unsubscribe = Native.pip.onChange((payload) => {
     console.log(payload.element);     // HTMLVideoElement
     console.log(payload.nativeEvent); // Event
 });
- 
+
 unsubscribe();
 ```
 
@@ -2276,7 +2394,7 @@ unsubscribe();
 
 ```ts
 onError(listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void
-onError(target: HTMLVideoElement, listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void
+    onError(target: HTMLVideoElement, listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void
 ```
 
 Subscribes to Picture-in-Picture errors.
@@ -2347,8 +2465,8 @@ NameVersionPair<OS>
 
 ```ts
 interface NameVersionPair<T> {
-    name:    T;
-    version: string;
+    readonly name:    T;
+    readonly version: string;
 }
 
 enum OS {
@@ -2512,11 +2630,11 @@ Locale
 
 ```ts
 interface Locale {
-    language:  string | null;
-    languages: string[];
-    timezone:  string | null;
-    offset:    number;
-    isRTL:     boolean;
+    readonly language:  string | null;
+    readonly languages: string[];
+    readonly timezone:  string | null;
+    readonly offset:    number;
+    readonly isRTL:     boolean;
 }
 ```
 
@@ -2553,10 +2671,10 @@ GPU
 
 ```ts
 interface GPU {
-    vendor?:       string;
-    architecture?: string;
-    device?:       string;
-    description?:  string;
+    readonly vendor?:       string;
+    readonly architecture?: string;
+    readonly device?:       string;
+    readonly description?:  string;
 }
 ```
 

package/dist/index.d.ts

@@ -7,10 +7,10 @@ declare enum Appearances {
 declare interface AppearanceInstance {
     get value(): Appearances;
     onChange(listener: (appearance: Appearances) => void, options?: AddEventListenerOptions): () => void;
-    Constants: {
-        Appearances: typeof Appearances;
+    readonly Constants: {
+        readonly Appearances: typeof Appearances;
     };
-    Errors: {};
+    readonly Errors: {};
 }
 
 declare const Appearance: AppearanceInstance;
@@ -21,9 +21,9 @@ declare interface BadgeInstance {
     get supported(): boolean;
     set(contents: number): Promise<void>;
     clear(): Promise<void>;
-    Constants: {};
-    Errors: {
-        NotSupportedError: typeof NotSupportedError;
+    readonly Constants: {};
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
     };
 }
 
@@ -49,9 +49,9 @@ declare interface BatteryInstance {
     get supported(): boolean;
     get value(): Promise<BatteryManager>;
     onChange(listener: (battery: BatteryManager) => void, options?: AddEventListenerOptions): () => void;
-    Constants: {};
-    Errors: {
-        NotSupportedError: typeof NotSupportedError;
+    readonly Constants: {};
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
     };
 }
 
@@ -60,16 +60,21 @@ declare const Battery: BatteryInstance;
 declare interface ClipboardInstance {
     copy(item: any): Promise<boolean>;
     paste(): Promise<string>;
-    Constants: {};
-    Errors: {};
+    readonly Constants: {};
+    readonly Errors: {};
 }
 
 declare const Clipboard: ClipboardInstance;
 
 declare enum Orientation {
-    Portrait = "portrait",
-    Landscape = "landscape",
-    Unknown = "unknown"
+    PortraitPrimary = "portrait-primary",
+    PortraitSecondary = "portrait-secondary",
+    LandscapePrimary = "landscape-primary",
+    LandscapeSecondary = "landscape-secondary"
+}
+declare namespace Orientation {
+    function isLandscape(orientation: Orientation): boolean;
+    function isPortrait(orientation: Orientation): boolean;
 }
 declare const ENV_PRESETS: {
     readonly 'safe-area-inset': {
@@ -108,17 +113,19 @@ declare const ENV_PRESETS: {
     };
 };
 
+declare const PermissionNotGrantedError: ErrorConstructor;
+
 type EnvironmentPresetKey = keyof typeof ENV_PRESETS;
 type EnvironmentPresetAttribute<K extends EnvironmentPresetKey> = keyof typeof ENV_PRESETS[K];
 type EnvironmentPresetValues<K extends EnvironmentPresetKey> = {
     [P in EnvironmentPresetAttribute<K>]: number;
 };
 declare interface Environment {
-    safeAreaInset: EnvironmentObserver<'safe-area-inset'>;
-    safeAreaMaxInset: EnvironmentObserver<'safe-area-max-inset'>;
-    keyboardInset: EnvironmentObserver<'keyboard-inset'>;
-    titlebarArea: EnvironmentObserver<'titlebar-area'>;
-    viewportSegment: EnvironmentObserver<'viewport-segment'>;
+    readonly safeAreaInset: EnvironmentObserver<'safe-area-inset'>;
+    readonly safeAreaMaxInset: EnvironmentObserver<'safe-area-max-inset'>;
+    readonly keyboardInset: EnvironmentObserver<'keyboard-inset'>;
+    readonly titlebarArea: EnvironmentObserver<'titlebar-area'>;
+    readonly viewportSegment: EnvironmentObserver<'viewport-segment'>;
 }
 declare interface SegmentsObserver {
     get value(): EnvironmentPresetValues<'viewport-segment'>[];
@@ -131,21 +138,41 @@ declare type EnvironmentObserver<K extends EnvironmentPresetKey> = K extends 'vi
     useCssVariable(prefix: string): () => void;
 };
 declare interface Dimensions {
-    outerWidth: number;
-    outerHeight: number;
-    innerWidth: number;
-    innerHeight: number;
-    scale: number;
-    orientation: Orientation;
+    readonly outerWidth: number;
+    readonly outerHeight: number;
+    readonly innerWidth: number;
+    readonly innerHeight: number;
+    readonly scale: number;
+}
+declare interface DeviceOrientationValue {
+    readonly alpha: number | null;
+    readonly beta: number | null;
+    readonly gamma: number | null;
+    readonly absolute: boolean;
+}
+declare interface DeviceOrientationInstance {
+    get supported(): boolean;
+    readonly value: Promise<DeviceOrientationValue>;
+    onChange(listener: (value: DeviceOrientationValue) => void, options?: AddEventListenerOptions): () => void;
+}
+declare interface ScreenOrientationInstance {
+    get supported(): boolean;
+    readonly value: Orientation;
+    onChange(listener: (value: Orientation) => void, options?: AddEventListenerOptions): () => void;
 }
 declare interface DimensionInstance {
     get value(): Dimensions;
-    environment: Environment;
+    readonly environment: Environment;
+    readonly screenOrientation: ScreenOrientationInstance;
+    readonly deviceOrientation: DeviceOrientationInstance;
     onChange(listener: (dimension: Dimensions) => void, options?: AddEventListenerOptions): () => void;
-    Constants: {
-        Orientation: typeof Orientation;
+    readonly Constants: {
+        readonly Orientation: typeof Orientation;
+    };
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
+        readonly PermissionNotGrantedError: typeof PermissionNotGrantedError;
     };
-    Errors: {};
 }
 
 declare global {
@@ -178,16 +205,16 @@ declare interface FullscreenInstance {
     onChange(target: Element, listener: (payload: FullscreenEventPayload) => void, options?: AddEventListenerOptions): () => void;
     onError(listener: (payload: FullscreenEventPayload) => void, options?: AddEventListenerOptions): () => void;
     onChange(target: Element, listener: (payload: FullscreenEventPayload) => void, options?: AddEventListenerOptions): () => void;
-    Constants: {};
-    Errors: {
-        NotSupportedError: typeof NotSupportedError;
-        InvalidStateError: typeof InvalidStateError;
+    readonly Constants: {};
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
+        readonly InvalidStateError: typeof InvalidStateError;
     };
 }
 declare interface FullscreenEventPayload {
-    nativeEvent: Event;
-    element: Element;
-    isActive: boolean;
+    readonly nativeEvent: Event;
+    readonly element: Element;
+    readonly isActive: boolean;
 }
 
 declare global {
@@ -226,16 +253,14 @@ declare global {
 }
 declare const Fullscreen: FullscreenInstance;
 
-declare const PermissionNotGrantedError: ErrorConstructor;
-
 declare interface GeolocationInstance {
     get supported(): boolean;
     get value(): Promise<GeolocationCoordinates>;
     onChange(listener: (coordinates: GeolocationCoordinates) => void, options?: AddEventListenerOptions): () => void;
-    Constants: {};
-    Errors: {
-        NotSupportedError: typeof NotSupportedError;
-        PermissionNotGrantedError: typeof PermissionNotGrantedError;
+    readonly Constants: {};
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
+        readonly PermissionNotGrantedError: typeof PermissionNotGrantedError;
     };
 }
 
@@ -260,10 +285,10 @@ interface NotificationOptions {
 declare interface NotificationInstance {
     send(options: NotificationOptions): Promise<Notification>;
     get supported(): boolean;
-    Constants: {};
-    Errors: {
-        NotSupportedError: typeof NotSupportedError;
-        PermissionNotGrantedError: typeof PermissionNotGrantedError;
+    readonly Constants: {};
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
+        readonly PermissionNotGrantedError: typeof PermissionNotGrantedError;
     };
 }
 
@@ -358,24 +383,24 @@ declare interface PlatformInstance {
     get isNode(): boolean;
     get isStandalone(): boolean;
     get isWebview(): boolean;
-    Constants: {
-        OS: typeof OS;
-        Engines: typeof Engines;
-        Browsers: typeof Browsers;
-        Devices: typeof Devices;
+    readonly Constants: {
+        readonly OS: typeof OS;
+        readonly Engines: typeof Engines;
+        readonly Browsers: typeof Browsers;
+        readonly Devices: typeof Devices;
     };
-    Errors: {};
+    readonly Errors: {};
 }
 declare interface NameVersionPair<T> {
-    name: T;
-    version: string;
+    readonly name: T;
+    readonly version: string;
 }
 declare interface Locale {
-    language: string | null;
-    languages: string[];
-    timezone: string | null;
-    offset: number;
-    isRTL: boolean;
+    readonly language: string | null;
+    readonly languages: readonly string[];
+    readonly timezone: string | null;
+    readonly offset: number;
+    readonly isRTL: boolean;
 }
 interface GPUAdapterInfo {
     readonly vendor?: string;
@@ -528,8 +553,8 @@ interface DirectoryOptions {
     startIn?: ExplorerStartIn;
 }
 interface FileWithPath {
-    file: File;
-    relativePath: string;
+    readonly file: File;
+    readonly relativePath: string;
 }
 interface CameraOptions {
     type?: CameraType;
@@ -620,7 +645,7 @@ declare interface OpenInstance {
     contact(options?: ContactOptions): Promise<Contact[]>;
     share(options: ShareData): Promise<void>;
     calendar(options: CalendarOptions): void;
-    supported: {
+    readonly supported: {
         get intent(): boolean;
         get universal(): boolean;
         get setting(): boolean;
@@ -630,16 +655,16 @@ declare interface OpenInstance {
         get share(): boolean;
         get calendar(): boolean;
     };
-    Constants: {
-        AppOpenState: typeof AppOpenState;
-        SettingType: typeof SettingType;
-        CameraType: typeof CameraType;
-        CaptureType: typeof CaptureType;
+    readonly Constants: {
+        readonly AppOpenState: typeof AppOpenState;
+        readonly SettingType: typeof SettingType;
+        readonly CameraType: typeof CameraType;
+        readonly CaptureType: typeof CaptureType;
     };
-    Errors: {
-        URLOpenError: typeof URLOpenError;
-        NotSupportedError: typeof NotSupportedError;
-        UserCancelledError: typeof UserCancelledError;
+    readonly Errors: {
+        readonly URLOpenError: typeof URLOpenError;
+        readonly NotSupportedError: typeof NotSupportedError;
+        readonly UserCancelledError: typeof UserCancelledError;
     };
 }
 
@@ -700,8 +725,8 @@ declare const Open: OpenInstance;
 declare interface ThemeInstance {
     get value(): string | undefined;
     set value(color: string | undefined);
-    Constants: {};
-    Errors: {};
+    readonly Constants: {};
+    readonly Errors: {};
 }
 
 declare const Theme: ThemeInstance;
@@ -710,9 +735,9 @@ declare interface VibrationInstance {
     get supported(): boolean;
     run(pattern: number | number[]): boolean;
     stop(): boolean;
-    Constants: {};
-    Errors: {
-        NotSupportedError: typeof NotSupportedError;
+    readonly Constants: {};
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
     };
 }
 
@@ -732,7 +757,9 @@ declare enum PermissionType {
     Camera = "camera",
     ClipboardRead = "clipboard-read",
     Microphone = "microphone",
-    MIDI = "midi"
+    MIDI = "midi",
+    DeviceOrientation = "device-orientation",
+    DeviceMotion = "device-motion"
 }
 declare enum PermissionState {
     Grant = "grant",
@@ -745,11 +772,13 @@ declare interface PermissionInstance {
     get supported(): boolean;
     request(type: PermissionType): Promise<PermissionState>;
     check(type: PermissionType): Promise<PermissionState>;
-    Constants: {
-        PermissionType: typeof PermissionType;
-        PermissionState: typeof PermissionState;
+    readonly Constants: {
+        readonly PermissionType: typeof PermissionType;
+        readonly PermissionState: typeof PermissionState;
+    };
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
     };
-    Errors: {};
 }
 
 declare const Permission: PermissionInstance;
@@ -765,16 +794,16 @@ declare interface PipInstance {
     onChange(target: HTMLVideoElement, listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void;
     onError(listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void;
     onError(target: HTMLVideoElement, listener: (payload: PipEventPayload) => void, options?: AddEventListenerOptions): () => void;
-    Constants: {};
-    Errors: {
-        NotSupportedError: typeof NotSupportedError;
-        InvalidStateError: typeof InvalidStateError;
+    readonly Constants: {};
+    readonly Errors: {
+        readonly NotSupportedError: typeof NotSupportedError;
+        readonly InvalidStateError: typeof InvalidStateError;
     };
 }
 declare interface PipEventPayload {
-    nativeEvent: Event;
-    element: HTMLVideoElement;
-    isActive: boolean;
+    readonly nativeEvent: Event;
+    readonly element: HTMLVideoElement;
+    readonly isActive: boolean;
 }
 
 declare global {