@mpgd/target-config 0.3.4 → 0.4.0

package/dist/viewport.d.ts

@@ -1,5 +1,7 @@
 import type { TargetConfig, TargetRuntimeKind } from './runtime';
 export type TargetViewportOrientation = 'portrait' | 'landscape';
+export type TargetViewportOrientationPolicyMode = 'responsive' | 'prefer-landscape' | 'prefer-portrait' | 'lock-landscape' | 'lock-portrait';
+export type TargetViewportOrientationMismatchBehavior = 'continue' | 'letterbox' | 'show-rotate-prompt';
 export type TargetViewportSizeClass = 'compact' | 'medium' | 'expanded';
 export type TargetViewportShell = 'browser' | 'mobile-webview' | 'embedded-webview';
 export type TargetViewportMeasurementSource = 'container' | 'visual-viewport' | 'window' | 'unknown';
@@ -14,6 +16,7 @@ export interface TargetViewportInput {
   readonly height: number;
   readonly runtime?: TargetRuntimeKind;
   readonly source?: TargetViewportMeasurementSource;
+  readonly orientationPolicy?: TargetViewportOrientationPolicy;
 }
 export interface TargetViewportLayout {
   readonly width: number;
@@ -31,17 +34,36 @@ export interface TargetViewportRecommendation {
   readonly secondaryPanels: TargetViewportPanelPlacement;
   readonly safeAreaAware: boolean;
 }
+export interface TargetViewportOrientationPolicy {
+  readonly mode: TargetViewportOrientationPolicyMode;
+  readonly mismatchBehavior?: TargetViewportOrientationMismatchBehavior;
+}
+export interface TargetViewportOrientationPlan {
+  readonly mode: TargetViewportOrientationPolicyMode;
+  readonly preferredOrientation?: TargetViewportOrientation;
+  readonly lockedOrientation?: TargetViewportOrientation;
+  readonly mismatchBehavior: TargetViewportOrientationMismatchBehavior;
+  readonly isMismatch: boolean;
+  readonly shouldLetterbox: boolean;
+  readonly shouldShowRotatePrompt: boolean;
+}
 export interface TargetViewportPlan {
   readonly layout: TargetViewportLayout;
   readonly recommendation: TargetViewportRecommendation;
+  readonly orientation: TargetViewportOrientationPlan;
 }
 export declare const defaultTargetViewportBreakpoints: {
   readonly compactMaxWidth: 599;
   readonly expandedMinWidth: 900;
 };
+export declare const defaultTargetViewportOrientationPolicy: {
+  readonly mode: 'responsive';
+  readonly mismatchBehavior: 'continue';
+};
 export declare function targetViewportShellForRuntime(runtime: TargetRuntimeKind): TargetViewportShell;
 export declare function targetViewportShellForConfig(config: Pick<TargetConfig, 'runtime'>): TargetViewportShell;
 export declare function resolveTargetViewportLayout(input: TargetViewportInput, breakpoints?: TargetViewportBreakpoints): TargetViewportLayout;
 export declare function resolveTargetViewportSizeClass(width: number, breakpoints?: TargetViewportBreakpoints): TargetViewportSizeClass;
 export declare function resolveTargetViewportRecommendation(layout: TargetViewportLayout): TargetViewportRecommendation;
+export declare function resolveTargetViewportOrientationPlan(layout: Pick<TargetViewportLayout, 'orientation'>, policy?: TargetViewportOrientationPolicy): TargetViewportOrientationPlan;
 export declare function resolveTargetViewportPlan(input: TargetViewportInput, breakpoints?: TargetViewportBreakpoints): TargetViewportPlan;

package/dist/viewport.js

@@ -2,6 +2,37 @@ export const defaultTargetViewportBreakpoints = {
     compactMaxWidth: 599,
     expandedMinWidth: 900,
 };
+export const defaultTargetViewportOrientationPolicy = {
+    mode: 'responsive',
+    mismatchBehavior: 'continue',
+};
+const targetViewportOrientationPolicyModeDescriptors = {
+    responsive: {
+        preferredOrientation: undefined,
+        lockedOrientation: undefined,
+        isLocked: false,
+    },
+    'prefer-landscape': {
+        preferredOrientation: 'landscape',
+        lockedOrientation: undefined,
+        isLocked: false,
+    },
+    'prefer-portrait': {
+        preferredOrientation: 'portrait',
+        lockedOrientation: undefined,
+        isLocked: false,
+    },
+    'lock-landscape': {
+        preferredOrientation: 'landscape',
+        lockedOrientation: 'landscape',
+        isLocked: true,
+    },
+    'lock-portrait': {
+        preferredOrientation: 'portrait',
+        lockedOrientation: 'portrait',
+        isLocked: true,
+    },
+};
 export function targetViewportShellForRuntime(runtime) {
     switch (runtime) {
         case 'capacitor-android':
@@ -51,11 +82,29 @@ export function resolveTargetViewportRecommendation(layout) {
         safeAreaAware: layout.shell !== 'browser' || layout.sizeClass === 'compact' || browserSafeAreaRisk,
     };
 }
+export function resolveTargetViewportOrientationPlan(layout, policy = defaultTargetViewportOrientationPolicy) {
+    const normalizedPolicy = normalizeTargetViewportOrientationPolicy(policy);
+    const descriptor = targetViewportOrientationPolicyModeDescriptors[normalizedPolicy.mode];
+    const preferredOrientation = descriptor.preferredOrientation;
+    const lockedOrientation = descriptor.lockedOrientation;
+    const isMismatch = preferredOrientation !== undefined && layout.orientation !== preferredOrientation;
+    const mismatchBehavior = normalizedPolicy.mismatchBehavior;
+    return {
+        mode: normalizedPolicy.mode,
+        ...(preferredOrientation === undefined ? {} : { preferredOrientation }),
+        ...(lockedOrientation === undefined ? {} : { lockedOrientation }),
+        mismatchBehavior,
+        isMismatch,
+        shouldLetterbox: isMismatch && mismatchBehavior === 'letterbox',
+        shouldShowRotatePrompt: isMismatch && mismatchBehavior === 'show-rotate-prompt',
+    };
+}
 export function resolveTargetViewportPlan(input, breakpoints = defaultTargetViewportBreakpoints) {
     const layout = resolveTargetViewportLayout(input, breakpoints);
     return {
         layout,
         recommendation: resolveTargetViewportRecommendation(layout),
+        orientation: resolveTargetViewportOrientationPlan(layout, input.orientationPolicy),
     };
 }
 function classifyTargetViewportSize(width, breakpoints) {
@@ -76,6 +125,14 @@ function resolveTargetViewportPanelPlacement(layout) {
     }
     return 'side';
 }
+function normalizeTargetViewportOrientationPolicy(policy) {
+    const descriptor = targetViewportOrientationPolicyModeDescriptors[policy.mode];
+    return {
+        mode: policy.mode,
+        mismatchBehavior: policy.mismatchBehavior ??
+            (descriptor.isLocked ? 'show-rotate-prompt' : 'continue'),
+    };
+}
 function normalizeTargetViewportBreakpoints(breakpoints) {
     const compactMaxWidth = normalizeViewportDimension(breakpoints.compactMaxWidth, 'compactMaxWidth');
     const expandedMinWidth = normalizeViewportDimension(breakpoints.expandedMinWidth, 'expandedMinWidth');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/target-config",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Target-specific platform feature availability and effective config helpers for mpgd.",
   "license": "MIT",
   "repository": {