@mpgd/target-config 0.3.3 → 0.4.0

package/dist/index.d.ts

@@ -2,5 +2,6 @@ import type { EffectiveTargetConfigMatrix } from './effective';
 import type { TargetConfigMatrix } from './runtime';
 export * from './effective';
 export * from './runtime';
+export * from './viewport';
 export declare const assertEffectiveTargetConfigMatrix: (input: unknown) => EffectiveTargetConfigMatrix;
 export declare const assertTargetConfigMatrix: (input: unknown) => TargetConfigMatrix;

package/dist/index.js

@@ -4,6 +4,7 @@ const __typia_transform__accessExpressionAsString = _b._accessExpressionAsString
 import typia from 'typia';
 export * from './effective';
 export * from './runtime';
+export * from './viewport';
 export const assertEffectiveTargetConfigMatrix = (() => {
     const _ip0 = input => "string" === typeof input["version"];
     const _ip1 = input => "boolean" === typeof input["iap"];

package/dist/viewport.d.ts

@@ -0,0 +1,69 @@
+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';
+export type TargetViewportControlPlacement = 'bottom' | 'side';
+export type TargetViewportPanelPlacement = 'below' | 'side' | 'drawer';
+export interface TargetViewportBreakpoints {
+  readonly compactMaxWidth: number;
+  readonly expandedMinWidth: number;
+}
+export interface TargetViewportInput {
+  readonly width: number;
+  readonly height: number;
+  readonly runtime?: TargetRuntimeKind;
+  readonly source?: TargetViewportMeasurementSource;
+  readonly orientationPolicy?: TargetViewportOrientationPolicy;
+}
+export interface TargetViewportLayout {
+  readonly width: number;
+  readonly height: number;
+  readonly shortSide: number;
+  readonly longSide: number;
+  readonly aspectRatio: number;
+  readonly orientation: TargetViewportOrientation;
+  readonly sizeClass: TargetViewportSizeClass;
+  readonly shell: TargetViewportShell;
+  readonly source: TargetViewportMeasurementSource;
+}
+export interface TargetViewportRecommendation {
+  readonly primaryControls: TargetViewportControlPlacement;
+  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

@@ -0,0 +1,156 @@
+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':
+        case 'capacitor-ios':
+        case 'apps-in-toss':
+            return 'mobile-webview';
+        case 'devvit-web':
+            return 'embedded-webview';
+        case 'web-preview':
+        case 'microsoft-store-pwa':
+            return 'browser';
+    }
+    const exhaustive = runtime;
+    return exhaustive;
+}
+export function targetViewportShellForConfig(config) {
+    return targetViewportShellForRuntime(config.runtime);
+}
+export function resolveTargetViewportLayout(input, breakpoints = defaultTargetViewportBreakpoints) {
+    const normalizedBreakpoints = normalizeTargetViewportBreakpoints(breakpoints);
+    const width = normalizeViewportDimension(input.width, 'width');
+    const height = normalizeViewportDimension(input.height, 'height');
+    const aspectRatio = width / height;
+    return {
+        width,
+        height,
+        shortSide: Math.min(width, height),
+        longSide: Math.max(width, height),
+        aspectRatio,
+        orientation: width >= height ? 'landscape' : 'portrait',
+        sizeClass: classifyTargetViewportSize(width, normalizedBreakpoints),
+        shell: input.runtime === undefined ? 'browser' : targetViewportShellForRuntime(input.runtime),
+        source: input.source ?? 'unknown',
+    };
+}
+export function resolveTargetViewportSizeClass(width, breakpoints = defaultTargetViewportBreakpoints) {
+    return classifyTargetViewportSize(normalizeViewportDimension(width, 'width'), normalizeTargetViewportBreakpoints(breakpoints));
+}
+export function resolveTargetViewportRecommendation(layout) {
+    const narrowOrPortrait = layout.sizeClass === 'compact' || layout.orientation === 'portrait';
+    const browserSafeAreaRisk = layout.shell === 'browser' &&
+        layout.orientation === 'landscape' &&
+        layout.shortSide <= defaultTargetViewportBreakpoints.compactMaxWidth;
+    return {
+        primaryControls: narrowOrPortrait ? 'bottom' : 'side',
+        secondaryPanels: resolveTargetViewportPanelPlacement(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) {
+    if (width <= breakpoints.compactMaxWidth) {
+        return 'compact';
+    }
+    if (width < breakpoints.expandedMinWidth) {
+        return 'medium';
+    }
+    return 'expanded';
+}
+function resolveTargetViewportPanelPlacement(layout) {
+    if (layout.sizeClass === 'compact') {
+        return 'drawer';
+    }
+    if (layout.orientation === 'portrait') {
+        return 'below';
+    }
+    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');
+    if (compactMaxWidth + 1 >= expandedMinWidth) {
+        throw new Error('compactMaxWidth must leave at least one integer width below expandedMinWidth for medium viewports.');
+    }
+    return {
+        compactMaxWidth,
+        expandedMinWidth,
+    };
+}
+function normalizeViewportDimension(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`Viewport ${name} must be a positive finite number.`);
+    }
+    const rounded = Math.round(value);
+    if (rounded <= 0) {
+        throw new Error(`Viewport ${name} must round to at least 1.`);
+    }
+    return rounded;
+}

package/package.json

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